tesouro-embedded-components-react

This package is the public npm surface for Tesouro embedded React widgets.

Consuming the package

@tesouro/embedded-components-react is an ESM package for bundler-based React apps (Vite, webpack, esbuild, Next.js). react and react-dom (v19) are peer dependencies.

npm install @tesouro/embedded-components-react
# or: yarn add @tesouro/embedded-components-react

Import the stylesheet once at your app's entry point — widgets render unstyled without it:

import '@tesouro/embedded-components-react/styles.css';

Then render a widget inside a provider that establishes its authenticated scope:

import '@tesouro/embedded-components-react/styles.css';
import {
  RootWidgetProvider,
  BankAccountsWidget,
} from '@tesouro/embedded-components-react';

export function App() {
  return (
    <RootWidgetProvider
      baseUrl="https://api.tesouro.com"
      widgetToken="wt_live_…"
      organizationId="org_…"
    >
      <BankAccountsWidget />
    </RootWidgetProvider>
  );
}

Every provider and widget prop is fully typed in the shipped declarations, so your editor documents the full auth/config model inline — per-widget WidgetProvider, config inheritance, token refresh, and the built-in error boundary.

Entry points

| Import path | What you get | | ------------------------------------------------- | ------------------------------------------------------------------------------------ | | @tesouro/embedded-components-react | All widgets plus RootWidgetProvider / WidgetProvider. | | @tesouro/embedded-components-react/styles.css | The widget stylesheet — see About the stylesheet. | | @tesouro/embedded-components-react/core | Framework-agnostic token utilities (createWidgetTokenManager). | | @tesouro/embedded-components-react/monite-sdk | Monite SDK surface for Monite-backed widgets. | | @tesouro/embedded-components-react/experimental | Work in progress — no compatibility promise. See below. |

Experimental entry point

@tesouro/embedded-components-react/experimental (and the per-module @tesouro/embedded-components-react/experimental/<Module>) is a staging area for work in progress. It is outside this package's semver contract:

• Anything exported there can change shape or be removed outright in any release, including a patch. There is no deprecation window.
• Its exports are deliberately not documented here — no prop tables, no reference entry. Read the shipped types.
• It is unsupported. If you hit a problem with it, use the released widget on the main entry point instead.

Use it only when we have pointed you at a specific module, and pin the package to an exact version if you do.

Everything else in this package — the main entry point, ./core, ./monite-sdk, ./lib/* and the stylesheet — carries the normal compatibility promise and is unaffected by churn on this path.

About the stylesheet

The stylesheet is host-safe by design. It ships no global CSS reset: Tailwind's Preflight is omitted and instead re-expressed scoped under the .tesouro-embedded wrapper that every widget renders, and all utilities are ttw-prefixed — so loading it won't restyle your host page or collide with your own Tailwind. Design tokens (--ttw-*) are declared on :root/.dark; dark mode follows an ancestor .dark class, and the widget font can be white-labeled via --ttw-font-family.

Providers

Every widget renders inside a provider that establishes its authenticated scope. Place a RootWidgetProvider once near the root of your app; use a WidgetProvider to override config (token, base URL, UI framework) for a subtree, or as a standalone root when you mount a single widget on its own. For automatic token rotation, use WidgetTokenRefreshProvider (or the bundled RefreshingRootWidgetProvider). Providers wrap their subtree in a built-in error boundary and expose the resolved config through the useWidgetConfig, useWidgetLoading, useWidgetError, and useRefetchWidget hooks; non-React hosts can seed config through the global store (setGlobalWidgetConfig).

RootWidgetProvider

App-level provider. Resolves baseUrl / widgetToken / organizationId (falling back to the global store), calls the widget init endpoint once a base URL and token both resolve, and shares the response with every descendant.

Props

| Prop | Type | Description | | ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | baseUrl | string | Base URL of the Tesouro embedded API (e.g. "https://api.tesouro.com"). Falls back to global.baseUrl when omitted. | | widgetToken | string \| null | Bearer token for widget auth. Falls back to global.widgetToken when omitted. Pass null to suppress auth. | | organizationId | string \| null | Org ID forwarded to data-access hooks. Falls back to global.organizationId when omitted; if still unset, defaults to initResponse.organizationId once the fetch resolves. Pass null to clear org scoping (never falls back). | | configClient | (client: EmbeddedClient) => EmbeddedClient | Optional post-creation hook for the HTTP client. Called after the built-in auth and gateway-routing interceptors. Falls back to global.configClient. | | gatewayRouting | boolean | Overrides widget-gateway routing (the /api/widget-gateway/proxy path prefix plus the X-Widget-Token header). Unset, routing applies per request when the request origin is a known Tesouro API host; true forces it on (e.g. a custom domain in front of the gateway), false forces it off (a host that routes its own requests). Falls back to global.gatewayRouting. | | linkComponent | LinkComponent | Host link component widgets use to render navigational links. Falls back to global.linkComponent. | | uiFramework | 'shadcn' \| 'tecton' \| null | UI framework the widget UI layer renders with for this tree. Falls back to global.uiFramework, then to 'shadcn'. See UI framework selection. | | implementation | 'native' \| 'monite' \| null | Which implementation the widgets render with for this tree. Falls back to global.implementation, then to 'native'. See Implementation selection. | | analytics | boolean | Enables anonymous analytics for this provider tree (default true). RootWidgetProvider is the analytics owner; set false to disable capture and skip loading PostHog. | | unstable_initResponseOverride | WidgetInitResponse | First-party hosts only. Skips the GET /api/widget-gateway/init fetch and exposes this host-authored object as initResponse to the subtree. Use when the host authenticates users directly against the Tesouro issuer and passes the user's bearer access token as widgetToken. Embed integrations minting widget JWEs must leave this unset. | | disclosuresAcceptance | ReactNode | Accept surface shown when the caller owes disclosures (INVITED, or REQUIRED with disclosuresAccepted: false). Pass <AcceptDisclosuresWidget />. Cascades to nested providers. | | children | ReactNode | The React subtree that consumes the widget context. |

WidgetProvider

Mid-tree or standalone provider. With no props it is a transparent pass-through that inherits everything from its parent; set baseUrl or widgetToken and it fetches its own init response for that subtree; with no provider ancestor it behaves as a standalone root — the right pattern for a single embedded widget.

Props

| Prop | Type | Description | | ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | baseUrl | string | Override the base URL for this subtree. Recreates the HTTP client. When omitted, inherits from the nearest ancestor. | | widgetToken | string \| null | Override the widget token for this subtree. Triggers a new /api/widget-gateway/init fetch. Pass null to suppress auth at this level. When omitted, inherits from parent. | | organizationId | string \| null | Override the org ID for this subtree. Does not trigger a re-fetch on its own. When omitted, inherits from parent; if unset through the whole cascade, defaults to this level's initResponse.organizationId (an ancestor's explicit org wins over it). Pass null to explicitly clear org scoping (never falls back). | | configClient | (client: EmbeddedClient) => EmbeddedClient | Optional post-creation hook for the scoped HTTP client. Only called when this provider creates its own client (i.e. not in pass-through mode). When omitted, inherits from parent. | | gatewayRouting | boolean | Overrides widget-gateway routing (the /api/widget-gateway/proxy path prefix plus the X-Widget-Token header) for this subtree's scoped client. Unset, routing applies per request when the request origin is a known Tesouro API host; true forces it on, false forces it off. When omitted, inherits from parent. | | linkComponent | LinkComponent | Override the host link component for this subtree. When omitted, inherits from parent. | | uiFramework | 'shadcn' \| 'tecton' \| null | Override the UI framework for this subtree. When omitted (or null), inherits the nearest ancestor's selection, defaulting to 'shadcn'. See UI framework selection. | | implementation | 'native' \| 'monite' \| null | Override the implementation for this subtree. When omitted (or null), inherits the nearest ancestor's selection, defaulting to 'native'. See Implementation selection. | | errorFallback | ReactNode \| (props: FallbackProps) => ReactNode | Custom fallback for the built-in error boundary in this subtree. A ReactNode is rendered as-is; a function receives { error, resetErrorBoundary }. Defaults to a generic role="alert" message. | | onError | (error: unknown, info: ErrorInfo) => void | Optional telemetry hook. Runs once per caught error before the fallback renders. | | analytics | boolean | Enables anonymous analytics (default true). Honored only when this is a standalone analytics owner (no RootWidgetProvider ancestor); on a nested provider it is a no-op. | | disclosuresAcceptance | ReactNode | Accept surface shown when the caller owes disclosures (INVITED, or REQUIRED with disclosuresAccepted: false). Pass <AcceptDisclosuresWidget />. When omitted, inherits from the nearest ancestor. | | children | ReactNode | The React subtree that consumes the overridden context. |

WidgetTokenRefreshProvider

Owns the token-refresh lifecycle: calls your fetcher, proactively refreshes before expiry, and exposes the live token via useWidgetToken() to feed into a RootWidgetProvider.

Props

| Prop | Type | Default | Description | | ------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | fetcher | () => Promise<{ widgetToken: string; exp?: number }> | — | Required. Called on mount and whenever a refresh is scheduled or requested. exp is unix seconds; if omitted, no proactive refresh is scheduled. | | leadSeconds | number | 60 | Schedule the next refresh leadSeconds before exp. Lower this if your tokens have a very short lifetime. | | onToken | (widgetToken: string) => void | — | Optional callback fired once per distinct token produced by the manager. Useful for telemetry, persistence, or — for non-React hosts (web components, cross-React-root setups) — mirroring the token into the global store via updateGlobalWidgetConfig. React consumers should drive widgetToken from useWidgetToken() instead. | | children | ReactNode | — | The React subtree that consumes the manager via useWidgetToken(). |

RefreshingRootWidgetProvider

Bundles WidgetTokenRefreshProvider + RootWidgetProvider and wires the live token through automatically — the recommended one-provider setup. Takes the RootWidgetProvider props (minus widgetToken) plus the refresh provider’s.

Props

| Prop | Source | Notes | | ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | baseUrl | RootWidgetProvider | Falls back to the global store when omitted. | | organizationId | RootWidgetProvider | Pass null to clear the org scope; falls back to the global store when omitted. | | configClient | RootWidgetProvider | Optional post-creation hook for the scoped HTTP client. | | gatewayRouting | RootWidgetProvider | Overrides widget-gateway routing; unset, it applies per request when the request origin is a known Tesouro API host. | | linkComponent | RootWidgetProvider | Component used in place of plain <a> tags inside widgets. | | uiFramework | RootWidgetProvider | 'shadcn' (default) or 'tecton'; inherits down the provider cascade. | | implementation | RootWidgetProvider | 'native' (default) or 'monite'; inherits down the provider cascade. | | analytics | RootWidgetProvider | Enables anonymous analytics (default true); set false to disable capture. | | unstable_initResponseOverride | RootWidgetProvider | First-party hosts only. Skips the gateway init fetch and supplies host-authored identity for the subtree. | | disclosuresAcceptance | RootWidgetProvider | Accept surface shown when the caller owes disclosures (INVITED, or REQUIRED with disclosuresAccepted: false). Cascades to nested providers. | | fetcher | WidgetTokenRefreshProvider | Required. | | leadSeconds | WidgetTokenRefreshProvider | Default 60. | | onToken | WidgetTokenRefreshProvider | Fires once per distinct token; useful for telemetry, persistence, or — for non-React hosts — mirroring the token via updateGlobalWidgetConfig. | | children | — | Render inside both providers' contexts (so useWidgetToken() and useWidgetConfig() both work in descendants). |

Components

Every widget below also accepts the shared auth/scope props from WidgetProviderProps (see Providers), so it can inherit config from a parent provider or take it directly. Only each widget’s own props are listed here.

AcceptDisclosuresWidget

A self-contained widget for reviewing and accepting required banking disclosures. Fetches the caller's disclosure document set (title/url pairs, in presentation order) from GET /identity/v1/disclosures and renders an inline bordered card with those links, an agreement checkbox, and an Accept action. The host supplies no document URLs — the document set, its titles, and its order are entirely backend configuration for the bank partner's program. The provider attribution and agreement copy come from the widget init tenant identity.

The widget token identifies the caller on both the disclosures lookup and the accept. Mount this when widget init reports status: 'INVITED', or disclosuresRequired: 'REQUIRED' with disclosuresAccepted: false. The first covers an invited teammate who is not yet active — including orgs whose requirement is NOT_REQUIRED, where Accept still posts a null version to activate them. The second covers an already-active user who owes a newly published version. Do not gate on REQUIRED alone: that would skip INVITED users in NOT_REQUIRED orgs and leave them stuck.

Accept posts POST /api/widget-gateway/disclosure-acceptance with the version that was on screen, after a second GET /identity/v1/disclosures confirms that version is still in force (hosts rewrite that onto /api/widget-gateway/proxy/identity/v1/disclosures the same way as other identity calls — do not call the generated catch-all proxy helper, which percent-encodes path slashes and surfaces as a browser CORS error). If a newer version was published while the caller was reading, accept is refused (no POST) and the widget refetches so they can review the documents that are now in force. version may be null when the org's requirement is NOT_REQUIRED; that value is posted through and ignored by the gateway so invitees in those orgs can still activate. The accept is one transaction: it activates the invitee (when they are still invited) and records disclosure acceptance together, so a failed second hop cannot leave an ACTIVE user with no acceptance on record. After accept succeeds, the widget awaits any async onAccepted continuation, then kicks a widget-init refresh so host gates keyed on INVITED — or on the disclosure flags — can clear. Accept and onAccepted failures are handled separately — a rejected host continuation does not look like (or re-run) a failed gateway accept. The refresh is fire-and-forget and runs only after onAccepted settles — hosts that unmount this widget when status leaves INVITED would otherwise hide a rejected continuation. Auth uses the normal widgetToken provider contract — never pass an application (APP) / M2M bearer as widgetToken. This widget does not take invite-link credentials and does not read URL search params.

A failed disclosures fetch renders an error surface with retry instead of a blank INVITED screen. The widget otherwise renders nothing until the disclosures fetch resolves and init resolves a bankName — it never substitutes another tenant's legal copy, and never falls back to a Tesouro-hosted document (a published embeddable library must not depend on infrastructure a consumer's content-security policy cannot see). An empty document list (requirement: NOT_REQUIRED, version: null) is a resolved payload, not missing data: the widget still renders Accept so those invitees can activate. Agreement copy names the returned document titles, in backend order, so the sentence cannot list instruments the links do not show. If init omits vspName, provider attribution falls back to the bank name so the sentence remains complete.

Once the atomic accept and any async onAccepted continuation succeed, the checkbox and Accept control stay disabled, so a legal acceptance is never posted twice even if the host does not navigate away. A failed accept or rejected onAccepted shows an inline error and leaves the control usable for a retry; a successful accept is skipped on retry after a later failure. Init refresh is kicked only after onAccepted succeeds.

Props

| Prop | Type | Default | Description | | ----------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | labels | Partial<AcceptDisclosuresWidgetLabels> | — | Override shell copy (title, Accept, agreement/attribution templates). {documents} in agreementTextTemplate is replaced with the backend-returned titles; a template that omits {documents} still has those titles appended. When the backend returns no documents, noDocumentsTitle / noDocumentsAgreementTextTemplate / noDocumentsAgreementCheckboxAriaLabel replace the disclosures copy (including the checkbox aria-label). Document titles themselves are not overridable. | | onAccepted | () => void \| Promise<void> | — | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable. | | disclosureLinks | AcceptDisclosuresLinks | — | Deprecated. Ignored. Documents come from GET /identity/v1/disclosures. Kept so existing hosts continue to typecheck until a breaking release. |

BankAccountsWidget

A self-contained banking widget for listing Tesouro bank accounts, creating an account with team access, and viewing account details.

Props

| Prop | Type | Default | Description | | --------------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- | | isBankingTaglineVisible | boolean | true | Shows the banking tagline under the page title. | | bankLogoSrc | string | undefined | Bank logo for the tagline row. Omit and the row shows the bank name alone. | | bankLogoAlt | string | undefined | Alt text when bankLogoSrc is set. | | depositAgreementUrl | string | undefined | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it is not rendered. | | bankAddress | string | undefined | Bank postal address shown in the account-details domestic wire panel. | | supportTeamUrl | string | undefined | Support URL linked from the account-details domestic wire copy. | | labels | Partial<BankAccountsWidgetLabels> | English labels | Overrides list/create-account UI copy. | | accountDetailsLabels | Partial<AccountDetailsWidgetLabels> | English labels | Overrides the internal account details UI copy. | | featureLabels | Partial<BankAccountsWidgetFeatureLabels> | English labels | Overrides feature-level copy (account fallback name, create/edit/copy toasts, and account-details export toasts). | | data-testid | string | undefined | Optional test id forwarded to the widget root. | | selectedAccountId | string \| null | undefined | Controls the open details account. | | defaultSelectedAccountId | string \| null | undefined | Initial uncontrolled details account. | | onSelectedAccountIdChange | (id: string \| null) => void | undefined | Called when the user opens details or goes back. |

BillPayWidget

A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.

Props

| Prop | Type | Default | Description | | -------------------- | ------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pageTitleComponent | (children: ReactNode) => ReactNode | Pass-through | Customizes Monite's page title action region. | | finopsThemeColors | FinopsThemeColors | undefined | Optional Monite theme color overrides. | | poweredByBankName | string | undefined | Bank shown as "Powered by {bank}" next to the source account when paying a bill. Native implementation only (implementation="native"); has no effect under the default Monite implementation. |

CardsWidget

One page of an organization's credit or debit cards, with a scope-gated "Show my cards" toggle, Create card and per-row Activate affordances. Selecting a row opens that card's read-only details in a side sheet. On a debit list with cardArtSrc, Create card opens the same sheet with the built-in debit issuance flow.

Props

| Prop | Type | Default | Description | | -------------------------- | --------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cardProgram | 'credit' \| 'debit' | Required | Which issuing program the list shows. Also selects the scopes that gate each affordance. | | pagination | { paginationToken?, pageSize? } | undefined | Controlled cursor and page size. Supply with onPaginationChange when your app owns the list position. | | defaultPagination | { paginationToken?, pageSize? } | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when pagination is supplied. | | onPaginationChange | (pagination) => void | undefined | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone. | | labels | PartialDeep<CardsWidgetLabels> | English labels | Overrides the copy of the list screen, including the details sheet's screen-reader name under detailsSheet and the create sheet's under createSheet. Nested groups merge per group. | | featureLabels | PartialDeep<CardsWidgetFeatureLabels> | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks. | | selectedCardId | string \| null | undefined | Controlled selection of the card whose details panel is open. null closes it; omit for uncontrolled. See Selection below. | | defaultSelectedCardId | string \| null | undefined | Initial selection when uncontrolled. Ignored when selectedCardId is supplied. | | onSelectedCardIdChange | (cardId: string \| null) => void | undefined | Fires whenever the open card changes, including on close (null). Supplying it does not change what renders. | | cardDetailsLabels | PartialDeep<CardDetailsWidgetLabels> | English labels | Label overrides forwarded into the details panel. | | cardDetailsFeatureLabels | PartialDeep<CardDetailsFeatureLabels> | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from featureLabels. | | bankLogoSrc | string | undefined | Bank logo for the details panel's card face. Omit and the face renders without a logo rather than with a placeholder. | | bankLogoAlt | string | undefined | Alt text for bankLogoSrc. | | cardArtSrc | string | undefined | Plastic art for the built-in debit create sheet. Required for that sheet: omit it (with no onCreateCard) and Create card is hidden. See Create card below. | | createCardLabels | PartialDeep<CreateCardWidgetLabels> | English labels | Label overrides forwarded into the nested create-card panel. | | createCardFeatureLabels | toast / untitled-funding overrides | English labels | Overrides for the copy the create panel's feature layer resolves — mutation toasts, untitled funding-account fallback, pending-activation success copy. | | onCreateCard | () => void | undefined | Host-owned Create card handler. When supplied, the built-in debit sheet does not open. Credit Create card still requires this callback. | | onActivateCard | (cardId: string) => void | undefined | Called when a row's Activate button is clicked. Omit it and the button is not rendered. |

CardDetailsWidget

Read-only details for one credit or debit card — status, form factor, program, masked card number, and copyable cardholder and nickname rows. It renders panel content rather than its own drawer, so it sits on a page of your own as readily as inside chrome you already have.

Props

| Prop | Type | Default | Description | | ---------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | cardId | string | Required | Id of the card to show. | | cardProgram | 'credit' \| 'debit' | Required | Which issuing program cardId belongs to. Selects the endpoint the card is fetched from. | | onClose | () => void | undefined | Called when the header's close control is pressed. Omit it and no close control is rendered at all. | | labels | PartialDeep<CardDetailsWidgetLabels> | English labels | Overrides the panel's own copy — header, card face alt text, row headings, copy-button accessible names, and the loading/error/not-found screens. | | featureLabels | PartialDeep<CardDetailsFeatureLabels> | English labels | Overrides the copy this widget resolves rather than passes through — status, form-factor and program vocabulary, plus the copy-success toast. | | bankLogoSrc | string | undefined | Bank logo for the card face. Omit and the face renders without a logo rather than with a placeholder. | | bankLogoAlt | string | undefined | Alt text for bankLogoSrc. Falls back to labels.cardFace.bankLogoAlt. |

CreateCardWidget

Issues a new debit card for an enrolled team member: cardholder, format (virtual / physical), funding bank account, and — for physical cards — a mailing destination. Loading, success, and error feedback use both full-screen views and sonner toasts.

Props

| Prop | Type | Default | Description | | --------------- | ------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ | | cardArtSrc | string | Required | Static card plastic image URL (no name overlays). | | labels | PartialDeep<CreateCardWidgetLabels> | English labels | Overrides presentational copy (header, setup, mailing, preparing, success, footer). Nested groups merge per group. | | featureLabels | toast / untitled-funding overrides | English labels | Overrides mutation toast strings and the funding-account fallback name. | | className | string | — | Optional class on the presentational root. | | onClose | () => void | — | Header close control. Omit and no close control is rendered. | | onCancel | () => void | — | Called when Cancel is pressed (also invokes onClose when both are set). | | onViewCard | (cardId: string) => void | — | Called with the new debit card id after a successful create when the user presses View card. |

CounterpartsWidget

A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.

Props

| Prop | Type | Default | Description | | -------------------- | ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | counterpartType | 'customer' \| 'vendor' | — | Required. Selects receivables/customer copy and queries or payables/vendor copy and queries. | | pageSizeOptions | number[] | [10, 25, 50, 100] | Page-size choices shown by the table. | | showTitle | boolean | true | Whether to render the screen title row. Pass false when the embedding surface already titles this screen; the create action then moves into the search row. | | onViewAllDocuments | () => void | undefined | Reveals a "View all" action beside the recent-bills/invoices heading in the details sheet. Omit when the host has no document list to navigate to; the action stays hidden rather than dead. |

| Prop | Type | Description | | ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | screenLabels | Partial<CounterpartsScreenLabels> | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy. | | formLabels | Partial<CounterpartFormSheetLabels> | Create/edit counterpart form copy. | | detailsLabels | Partial<CounterpartDetailsSheetLabels> | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. | | bankAccountLabels | Partial<BankAccountFormSheetLabels> | Vendor payment-method form copy. | | addressLabels | Partial<AddressFormSheetLabels> | Address form copy. | | deleteLabels | Partial<ConfirmDeleteDialogLabels> | Delete-dialog copy. | | messageLabels | Partial<CounterpartMessageLabels> | Validation, API failure, and delete-prompt messages produced by feature logic. |

ExpenseManagementWidget

A composite expense widget for receipt upload, matching slots, approval policies, and transaction requirements.

Props

| Prop | Type | Default | Description | | --------------------- | -------------------------- | ------------------------ | -------------------------------------------------- | | labels | Partial<Labels> | English labels | Overrides tab and heading copy. | | receiptUpload | UploadReceiptWidgetProps | undefined | Enables the default receipt upload control. | | receiptsContent | ReactNode | Upload widget or empty | Replaces the receipts tab content. | | matchingContent | ReactNode | Empty | Supplies host-owned matching UI without URL state. | | policiesContent | ReactNode | Approval policies widget | Replaces the policies tab content. | | requirementsContent | ReactNode | Requirements widget | Replaces the requirements tab content. |

ExpenseApprovalPoliciesWidget

Lets an organization view and manage its expense approval rules — each rule maps an amount range to an outcome (auto-approve or require approval) and, where approval is required, the approving roles. It is backed by the embedded REST API.

Props

No props beyond the shared auth/scope props.

ExpenseRequirementsWidget

An editable settings surface for an organization's transaction validation rules. It lets an admin toggle whether a receipt and a description/memo are required on expenses, set per-field amount thresholds, and save the changes back to the embedded REST API.

Props

No props beyond the shared auth/scope props.

BalancesWidget

A self-contained widget that loads embedded bank accounts for the organization, shows up to a configurable number of account balance rows, optionally aggregates a total when multiple accounts exist, and can link out to a host “view all accounts” destination.

Props

| Prop | Type | Default | Description | | ------------------------ | ------------------------------- | ------- | --------------------------------------------------------------------------- | | maxAccounts | number | 5 | Maximum rows rendered in-card; additional accounts use the view-all CTA. | | labels | Partial<BalancesWidgetLabels> | — | Override shell copy (title, errors, view-all label, total balance tooltip). | | onBalanceRowClick | (accountId: string) => void | — | When set, balance rows are clickable and receive the account id. | | onViewAllAccountsClick | () => void | — | When set and more than maxAccounts exist, shows View all accounts. |

InsightsWidget

A self-contained widget that derives onboarding-style insights from embedded and external bank account data, persists dismissed insight ids via the embed user-data API, and exposes optional host callbacks for routing and linking external accounts.

Props

| Prop | Type | Default | Description | | ---------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | | routingEnabled | boolean | false | Controlled switch state for the routing onboarding insight. | | onRoutingToggleChange | (enabled: boolean) => void | — | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. | | onLinkExternalAccountClick | () => void | — | When set, the connect-external-account insight shows a Link account CTA. | | labels | Partial<InsightsWidgetLabels> | — | Shell copy (tabs, empty, error). | | singleInsightLabels | Partial<SingleInsightLabels> | — | Per-row UI strings (e.g. dismiss aria label). | | featureLabels | Partial<InsightsFeatureLabels> | — | Generated insight body copy and action labels. |

ChartOfAccountsWidget

A self-contained widget that renders an organization's chart of accounts: a paginated, sortable table of ledger accounts with built-in create, edit, and delete. It handles its own API communication, loading and error states, server-side sorting, and cursor-based pagination. The host application only needs to supply auth credentials and optional UI callbacks.

Props

| Prop | Type | Description | | ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | title | string | Overrides the built-in "Chart of accounts" heading. Pass an empty string to suppress it when the host renders its own. | | onEdit | (row: LedgerAccountRow) => void | Overrides the built-in edit flow. Not offered on externally-synced rows (is_external), which the API refuses to update. | | onDelete | (row: LedgerAccountRow) => void | Overrides the built-in delete flow. Not offered on externally-synced rows (is_external), which the API refuses to delete. | | onAdd | () => void | Overrides the built-in create flow. Omit it to use the widget's own create sheet. |

| Prop | Type | Covers | | --------------- | --------------------------------------- | ----------------------------------------------------------------------------------- | | screenLabels | Partial<ChartOfAccountsLabels> | Table copy: heading, column headers, row actions, sort control, empty/error states. | | formLabels | Partial<AccountFormSheetLabels> | Create/edit sheet: titles, field labels, placeholders, counter, buttons, menu. | | deleteLabels | Partial<AccountDeleteDialogLabels> | Delete confirmation: title, message, buttons. | | messageLabels | Partial<ChartOfAccountsMessageLabels> | Validation messages, save/delete failure fallbacks, and success toasts. |

HelpWidget

A self-contained Help widget: a static FAQ accordion with an optional "Contact Us" card. It renders no network requests — all content comes from props, defaulting to the built-in English FAQ so the widget works with no configuration.

Props

| Prop | Type | Default | Description | | ------------ | --------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | faq | HelpFaqSection[] | HELP_FAQ_EN | FAQ content to render, grouped into titled sections. | | bankName | string | initResponse.bankName | Bank/provider name interpolated into the contact line. Defaults to the bank resolved by widget init; pass this only to override it. | | contactUrl | string | undefined | When set, renders a "Contact Us" card linking here. Omit to hide it. The card also needs a bank name, so it appears once widget init resolves. | | labels | Partial<HelpWidgetLabels> | HELP_WIDGET_LABELS_EN | Display-string overrides, merged over HELP_WIDGET_LABELS_EN (FAQ + contact copy). |

InvoicingWidget

A self-contained invoicing widget that renders the Monite SDK receivables experience (invoices, quotes, and credit notes) against your widget auth — the host only supplies credentials and optional theming.

Props

| Prop | Type | Default | Description | | -------------------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | finopsThemeColors | FinopsThemeColors | undefined | Overrides the Monite theme's primary colors. Omit to use Monite defaults. | | embeddedBankName | string | undefined | Display name of the sponsor bank powering embedded bank accounts (e.g. "Zenith Bank"). Shown next to embedded accounts in the invoice payment-account picker as "Powered by {embeddedBankName}". | | pageTitleComponent | (children: ReactNode) => ReactNode | Passthrough | Wraps the page header region. The default returns its children unchanged; supply a wrapper to add a title, branding, or toolbar around the widget's action buttons. |

LinkedAccountsWidget

A self-contained widget that lists and manages external bank accounts, including connect, edit, micro-deposit initiation, micro-deposit validation, and unlink actions.

Props

| Prop | Type | Default | Description | | --------------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | labels | Partial<LinkedAccountsWidgetLabels> | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults. | | featureLabels | Partial<LinkedAccountsWidgetFeatureLabels> | English labels | Overrides strings produced by the feature layer, such as row title fallback, account-number subtitle fragments, and the success toast messages shown after editing or unlinking an account. |

BankAccountOnboardingWidget

A self-contained widget that walks an applicant through the embedded bank-account onboarding flow: business details, personal details, optional additional owners, and a result screen. It owns all REST mutations (createApplication, updateApplication, submitApplication), step navigation, validation, and polling for provisioning to complete — the host application only supplies auth credentials and two callbacks.

Props

| Prop | Type | Required | Description | | ------------------------------------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onEmbeddedOnboardingCompletedSuccessfully | () => void | Yes | Called when the application is submitted and approved. | | onNavigateToDashboard | () => void | Yes | Called when the user clicks the dashboard CTA on the result screen. | | initialBusinessDetails | Partial<BusinessDetailsValues> | No | Prefills step 1 (business details). Unset fields start empty; the user can still edit before continuing. | | initialPersonalDetails | Partial<PersonalDetailsValues> | No | Prefills step 2 (personal / about-you details). Unset fields start empty; the user can still edit before continuing. | | initialAdditionalOwners | AdditionalOwner[] | No | Prefills step 3 (additional owners). Defaults to an empty list when omitted. | | open | boolean | No | Controlled open state for the modal. When provided the host owns open/close and must update it via onOpenChange. Omit for uncontrolled mode. | | defaultOpen | boolean | No | Initial open state when uncontrolled. Defaults to false so the modal stays closed until the host or marketing CTA opens it. Ignored when open is set. | | onOpenChange | (open: boolean) => void | No | Notified whenever the modal opens or closes — fires on overlay click, escape key, the close button, and any controlled state update. Used both as the change handler in controlled mode and a side hook. | | labels | BankAccountOnboardingWidgetLabels | No | Per-step label overrides — see Labels section. Accepts a modalTitle override for the modal's accessible title (default: Bank account onboarding). | | bankLogoSrc | string | No | URL for the bank logo rendered on the result screen; falls back to bank name text. | | disclosureLinks | DisclosureLinks | No | Host-resolved URLs for Terms of Use, Privacy Policy, Electronic Communication, and Patriot Act on the business-details agreement step. Omit to leave those links unset. | | marketingContent | `MarketingWidgetConte