Skip to main content

TaxKitProvider

TaxKitProvider is the entry point for the Tax Kit. It manages the iframe lifecycle, the post-robot bridge to the parent app, and serializes your configuration into the iframe's URL.

The new (2.2.0) prop shape groups configuration into four optional sub-objects: theme, options, metadata, and copy. Callbacks and the required fetchAccessToken stay at the top level. Each grouped sub-object has its own reference page linked from the sidebar.

note

Mount the provider once per page. Each TaxKitProvider renders its own iframe and its own post-robot bridge — mounting two on the same page produces two iframes (almost certainly not what you want) and useTaxKit() consumers will only see state from whichever provider is closest in their React tree. The provider itself produces no visible markup beyond the iframe: until the user triggers it (or you pass options.defaultOpen), the iframe is hidden behind an overlay primitive.

Required props​

fetchAccessToken() => Promise<string | null | undefined>required

Returns a fresh CoinTracker access token (JWT). The provider calls this whenever the iframe needs to authenticate — including when the existing token is within 30 seconds of expiry. The iframe deduplicates concurrent token requests internally, so your fetchAccessToken won't be hammered by parallel GraphQL queries.

Return null or undefined to signal that no authenticated session is available — the iframe will treat this as an unauthenticated state.

Configuration groups​

themeTaxKitTheme

Color tokens for light and dark mode, plus the mode override. See Theme.

optionsTaxKitOptions

Behavior switches: environment, flow, overlay style, UI toggles, partner help URL. See Options.

metadataTaxKitMetadata

Partner-supplied bag forwarded to the iframe. The reserved promoCode key has typed special handling; everything else passes through opaquely. See Metadata.

copyPartnerCopy

Override partner-facing copy strings inside the iframe (e.g. import confirmation checklist, add-connections disclaimer). See Copy.

Callbacks​

See Callbacks for full signatures and use cases.

onOpenLink(href: string, options?: { target?: 'self' | 'blank' }) => void

Invoked when the iframe wants to open an external link. If omitted, the SDK falls back to a default open behavior.

onDisconnectUser() => void

Invoked when the iframe disconnects the user from CoinTracker.

onPartnerImportTransactionsSuccess() => void

Invoked after a partner-side import succeeds following an OAuth round-trip.

onReceivedAdditionalMetadata(metadata: Record<string, unknown>) => void

Invoked when the iframe forwards metadata back to the parent app. Use this for partner-specific analytics or business-logic hooks.

childrenReactNode

Your application tree. Anything that needs to read kit state via useTaxKit() must be rendered inside the provider.

Minimal example​

import { TaxKitProvider } from '@cointracker/tax-kit';

<TaxKitProvider fetchAccessToken={fetchAccessToken}>
  <YourApp />
</TaxKitProvider>

Full example​

<TaxKitProvider
  fetchAccessToken={fetchAccessToken}
  theme={{
    mode: 'dark',
    light: lightTokens,
    dark: darkTokens,
  }}
  options={{
    mode: 'production',
    flow: 'one-way',
    overlayMode: 'responsive',
    defaultOpen: false,
    helpLinkUrl: 'https://help.your-partner.com/tax',
  }}
  metadata={{
    promoCode: 'PARTNER_2026',
    // Arbitrary partner-defined keys pass through opaquely.
    sourcePage: 'tax-center',
  }}
  copy={{
    addConnections: {
      disclaimer: 'Connecting accounts shares transaction history with CoinTracker for tax calculation.',
    },
  }}
  onOpenLink={(href) => window.open(href, '_blank', 'noopener')}
  onDisconnectUser={() => analytics.track('tax_kit_disconnected')}
  onPartnerImportTransactionsSuccess={() => refreshImports()}
  onReceivedAdditionalMetadata={(meta) => analytics.track('tax_kit_metadata', meta)}
>
  <YourApp />
</TaxKitProvider>

Legacy flat props​

The pre-2.2.0 flat props (apiBaseUrl, themeContract, themeMode, etc.) are preserved as @deprecated aliases. When both the new shape and a legacy prop are passed, the new shape wins. See Migrating from 2.1 for the full mapping.