Providers

Top-level providers for configuring auth, locale, and your design system. Wrap your application with one of these before rendering any SDK component.

GustoProvider

Top-level provider that configures the SDK at the application level.

Remarks

Wrap your application's component tree with GustoProvider so that any SDK component below it has access to the API client, theme, locale, translations, and UI components. Components you provide via the components prop override the SDK's React Aria defaults; any component you do not supply uses the default.

For full UI control without the bundled React Aria defaults, use GustoProviderCustomUIAdapter instead and supply a complete component map.

GustoProviderProps

Props for GustoProvider.

Remarks

Extends GustoProviderProps but makes components optional and partial: any components you do not supply fall back to the SDK's built-in React Aria implementations.

Property	Type	Description
config	APIConfig	API client configuration, including the proxy baseUrl, request hooks, and observability. See APIConfig.
children?	ReactNode	The application tree that should have access to the SDK.
components?	Partial<ComponentsContextType>	Partial component overrides. Any component you do not supply uses the SDK's default React Aria implementation.
dictionary?	GlobalResourceDictionary	Translation overrides keyed by language and i18next namespace. Strings supplied here replace the SDK defaults for the matching keys.
queryClient?	QueryClient	Optional TanStack Query QueryClient to share with the rest of your app. When omitted, the SDK creates its own client configured for Gusto's API.

Inherits currency, lng, LoaderComponent, locale, nonce, portalContainer, theme from Omit.

---

GustoProviderCustomUIAdapter

Top-level provider that requires a complete component map and ships no UI defaults.

Remarks

Use this adapter when you want full control over every UI primitive the SDK renders, or when you want to avoid the React Aria dependency for tree-shaking. Unlike GustoProvider, the components prop on GustoProviderProps is required and must supply every component the SDK renders.

GustoProviderCustomUIAdapterProps

Props for GustoProviderCustomUIAdapter.

Property	Type	Description
components	ComponentsContextType	Complete map of UI components the SDK renders. Required because this adapter ships no defaults.
config	APIConfig	API client configuration, including the proxy baseUrl, request hooks, and observability. See APIConfig.
children?	ReactNode	The application tree that should have access to the SDK.
dictionary?	GlobalResourceDictionary	Translation overrides keyed by language and i18next namespace. Strings supplied here replace the SDK defaults for the matching keys.

Inherits currency, lng, LoaderComponent, locale, nonce, portalContainer, queryClient, theme from GustoBaseProviderProps.

Utility types

APIConfig

API client configuration passed to GustoProvider (and GustoProviderCustomUIAdapter).

Properties

Property	Type	Description
baseUrl	string	URL of your backend proxy that forwards SDK requests to the Gusto Embedded API. SDK components never call Gusto directly.
headers?	HeadersInit	Extra headers applied to every API request. Combined with any headers your proxy adds.
hooks?	SDKHooks	Request interceptor hooks. Use these to inspect, modify, or react to requests and responses. See SDKHooks.
observability?	ObservabilityHook	Observability hook for surfacing errors and metrics from the SDK to your monitoring stack. See ObservabilityHook.

---

GustoBaseProviderProps

Shared configuration props accepted by GustoProvider and GustoProviderCustomUIAdapter.

Extended by

• GustoProviderCustomUIAdapterProps

Properties

Property	Type	Description
components	ComponentsContextType	Complete map of UI components the SDK renders. Required because this adapter ships no defaults.
config	APIConfig	API client configuration, including the proxy baseUrl, request hooks, and observability. See APIConfig.
currency?	string	ISO 4217 currency code used for monetary formatting. Defaults to 'USD'.
dictionary?	GlobalResourceDictionary	Translation overrides keyed by language and i18next namespace. Strings supplied here replace the SDK defaults for the matching keys.
lng?	string	Active i18next language. Defaults to 'en'.
LoaderComponent?	(__namedParameters: object) => Element	Loading indicator rendered while SDK queries are pending. Overrides the SDK default spinner.
locale?	string	BCP 47 locale used for number, date, and currency formatting throughout the SDK. Defaults to 'en-US'.
nonce?	string	CSP nonce to apply to runtime-injected <style> elements (theming, PDF download window). Pass the same per-request nonce your app uses in its style-src 'nonce-…' directive. Also exposed to custom UI components via useNonce.
portalContainer?	HTMLElement	Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root.
queryClient?	QueryClient	Optional TanStack Query QueryClient. When omitted, the SDK creates its own client configured for Gusto's API.
theme?	Partial<GustoSDKTheme>	Theme overrides applied to SDK components. See GustoSDKTheme.

---

useNonce()

useNonce(): string | undefined

Returns the CSP nonce supplied to GustoProvider, or undefined when none was provided.

Remarks

Use this when a custom UI component or partner-provided code injects a runtime <style> or <script> element and the integrating app serves a nonce-based Content Security Policy. Apply the returned value as the nonce property on the created element (e.g. el.nonce = useNonce()) before appending it to the document.

Example

import { useNonce } from '@gusto/embedded-react-sdk'

function InjectThemeStyles({ css }: { css: string }) {
  const nonce = useNonce()
  useEffect(() => {
    const el = document.createElement('style')
    if (nonce) el.nonce = nonce
    el.textContent = css
    document.head.appendChild(el)
    return () => el.remove()
  }, [css, nonce])
  return null
}

Returns

string | undefined

The active nonce, or undefined when GustoProvider was not given a nonce.

Page

providers