Skip to content

providers.md

Latest commit

 

History

History
124 lines (85 loc) · 6.94 KB

providers.md

File metadata and controls

124 lines (85 loc) · 6.94 KB
Raw
title Providers
description Top-level providers for configuring auth, locale, and your design system. Wrap your application with one of these before rendering any SDK component.
sidebar_position 10
generated_by typedoc
custom_edit_url

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, 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, 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

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'.
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.