`useDeployment()` hook

useDeployment() is the root hook for the shared client layer. It reads the deployment context created by <DeploymentProvider /> and gives the rest of the client hooks their deployment-aware behavior.

Usage

The following example shows a basic usage of useDeployment().

export default function DeploymentDebug() {  const { deployment, loading, adapter } = useDeployment();  if (loading) {    return <div>Loading deployment...</div>;  }  return (    <div>      <p>{deployment.ui_settings.app_name}</p>      <p>{deployment.frontend_host}</p>      <p>{adapter.useNavigate() ? 'Adapter ready' : 'No adapter'}</p>    </div>  );}

Return value

The hook returns the following fields and methods.

›

loading: boolean;

Whether the deployment request is still in flight.

›

deployment: Deployment | null;

The resolved deployment object from `DeploymentProvider`.

›

backend_host?: string | undefined;

The backend host resolved from the public key and used for client requests.

›

frontend_host?: string | undefined;

The frontend host configured for the deployment.

›

mode?: "production" | "staging" | undefined;

The deployment mode, used for staging-only behaviors like the development session handshake.

›

auth_settings?: AuthSettings | undefined;

The deployment-level authentication settings that drive the shared auth UI and flows.

›

first_factor?: FirstFactor | undefined;

The default first-factor strategy for sign-in.

›

second_factor_policy?: SecondFactorPolicy | undefined;

Whether second-factor auth is disabled, optional, or enforced.

›

multi_session_support?: MultiSessionSupport | undefined;

Controls whether the deployment allows multiple signed-in accounts in one session.

›

enabled?: boolean | undefined;

Whether multi-session support is enabled.

›

max_accounts_per_session?: number | undefined;

The maximum number of accounts allowed in one browser session.

›

passkey?: PasskeySettings | undefined;

Passkey availability and prompting rules.

›

enabled?: boolean | undefined;

Whether passkeys are enabled for the deployment.

›

prompt_registration_on_auth?: boolean | undefined;

Whether users are prompted to register a passkey after signing in.

›

b2b_settings?: B2BSettings | undefined;

The deployment-level organization and workspace settings.

›

organizations_enabled?: boolean | undefined;

Whether organizations are enabled for the deployment.

›

workspaces_enabled?: boolean | undefined;

Whether workspaces are enabled under organizations.

›

allow_users_to_create_orgs?: boolean | undefined;

Whether end users can create organizations without operator intervention.

›

custom_org_role_enabled?: boolean | undefined;

Whether custom organization roles are enabled.

›

custom_workspace_role_enabled?: boolean | undefined;

Whether custom workspace roles are enabled.

›

enterprise_sso_enabled?: boolean | undefined;

Whether enterprise SSO is enabled for organizations.

›

ui_settings?: DeploymentUISettings | undefined;

The UI settings for hosted routes, redirects, and embedded auth configuration.

›

deployment_id?: number | undefined;

Override the deployment UI settings record identifier.

›

app_name?: string | undefined;

Override the product or application name shown in shared auth UI.

›

privacy_policy_url?: string | undefined;

Override the privacy policy URL shown in auth surfaces.

›

tos_page_url?: string | undefined;

Override the terms of service URL shown in auth surfaces.

›

sign_in_page_url?: string | undefined;

Override the sign-in route used by shared navigation helpers and hosted auth redirects.

›

sign_up_page_url?: string | undefined;

Override the sign-up route used by shared navigation helpers and sign-up entry points.

›

waitlist_page_url?: string | undefined;

Override the waitlist page URL used by waitlist flows.

›

support_page_url?: string | undefined;

Override the support page URL linked from auth and recovery flows.

›

after_logo_click_url?: string | undefined;

Override the URL used when a user clicks the logo in shared auth UI.

›

user_profile_url?: string | undefined;

Override the user profile page URL used by account navigation.

›

organization_profile_url?: string | undefined;

Override the organization profile page URL used by organization management flows.

›

create_organization_url?: string | undefined;

Override the create-organization page URL used by organization creation flows.

›

after_sign_out_one_page_url?: string | undefined;

Override the redirect target after signing out only the active sign-in.

›

after_sign_out_all_page_url?: string | undefined;

Override the redirect target after signing out the whole session.

›

after_signup_redirect_url?: string | undefined;

Override the default redirect target after sign-up completes.

›

after_signin_redirect_url?: string | undefined;

Override the default redirect target after sign-in completes.

›

after_create_organization_redirect_url?: string | undefined;

Override the redirect target after creating an organization.

›

favicon_image_url?: string | undefined;

Override the favicon image URL used by shared auth pages.

›

default_user_profile_image_url?: string | undefined;

Override the default user profile image URL.

›

default_organization_profile_image_url?: string | undefined;

Override the default organization profile image URL.

›

default_workspace_profile_image_url?: string | undefined;

Override the default workspace profile image URL.

›

use_initials_for_user_profile_image?: boolean | undefined;

Whether shared UI should use initials when a user profile image is missing.

›

use_initials_for_organization_profile_image?: boolean | undefined;

Whether shared UI should use initials when an organization profile image is missing.

›

logo_image_url?: string | undefined;

Override the logo image URL used in shared auth UI.

›

signup_terms_statement?: string | undefined;

Override the sign-up terms statement shown during registration.

›

signup_terms_statement_shown?: boolean | undefined;

Whether the sign-up terms statement should be shown.

›

light_mode_settings?: LightModeSettings | undefined;

Override the light mode theme settings used by the embedded UI.

›

primary_color?: string | undefined;

Override the light mode primary color.

›

background_color?: string | undefined;

Override the light mode background color.

›

text_color?: string | undefined;

Override the light mode text color.

›

token_overrides?: UITokenOverrides | undefined;

Fine-grained light mode token overrides for the embedded UI theme.

›

space_unit?: string | undefined;

Override the base spacing unit used by the shared UI theme.

›

card?: string | undefined;

Override the card background color.

›

card_foreground?: string | undefined;

Override the card foreground color.

›

popover?: string | undefined;

Override the popover background color.

›

popover_foreground?: string | undefined;

Override the popover foreground color.

›

primary_foreground?: string | undefined;

Override the foreground color used on primary surfaces.

›

secondary?: string | undefined;

Override the secondary surface color.

›

secondary_foreground?: string | undefined;

Override the foreground color used on secondary surfaces.

›

accent?: string | undefined;

Override the accent surface color.

›

accent_foreground?: string | undefined;

Override the foreground color used on accent surfaces.

›

ring?: string | undefined;

Override the focus ring color.

›

foreground?: string | undefined;

Override the main foreground color.

›

foreground_inverse?: string | undefined;

Override the inverse foreground color.

›

secondary_text?: string | undefined;

Override the secondary text color.

›

muted?: string | undefined;

Override the muted text or surface color.

›

border?: string | undefined;

Override the default border color.

›

border_hover?: string | undefined;

Override the border color used on hover states.

›

divider?: string | undefined;

Override the divider color.

›

input_background?: string | undefined;

Override the input background color.

›

input_border?: string | undefined;

Override the input border color.

›

input_focus_border?: string | undefined;

Override the input border color used on focus.

›

background_subtle?: string | undefined;

Override the subtle background color.

›

background_hover?: string | undefined;

Override the background color used on hover states.

›

primary_hover?: string | undefined;

Override the hover color for primary actions.

›

error?: string | undefined;

Override the error text or accent color.

›

error_background?: string | undefined;

Override the error background color.

›

error_border?: string | undefined;

Override the error border color.

›

warning?: string | undefined;

Override the warning text or accent color.

›

warning_background?: string | undefined;

Override the warning background color.

›

warning_border?: string | undefined;

Override the warning border color.

›

warning_text?: string | undefined;

Override the warning text color.

›

success?: string | undefined;

Override the success text or accent color.

›

success_background?: string | undefined;

Override the success background color.

›

success_border?: string | undefined;

Override the success border color.

›

info?: string | undefined;

Override the info text or accent color.

›

info_background?: string | undefined;

Override the info background color.

›

radius_md?: string | undefined;

Override the medium radius token.

›

radius_lg?: string | undefined;

Override the large radius token.

›

radius_xl?: string | undefined;

Override the extra-large radius token.

›

radius_2xl?: string | undefined;

Override the 2xl radius token.

›

radius_2xs?: string | undefined;

Override the 2xs radius token.

›

radius_xs?: string | undefined;

Override the extra-small radius token.

›

radius_full?: string | undefined;

Override the fully rounded radius token.

›

border_width_thin?: string | undefined;

Override the thin border width token.

›

border_width_regular?: string | undefined;

Override the regular border width token.

›

scrollbar_track?: string | undefined;

Override the scrollbar track color.

›

scrollbar_thumb?: string | undefined;

Override the scrollbar thumb color.

›

scrollbar_thumb_hover?: string | undefined;

Override the scrollbar thumb hover color.

›

shadow_color?: string | undefined;

Override the base shadow color.

›

shadow_light_color?: string | undefined;

Override the light shadow color.

›

shadow_medium_color?: string | undefined;

Override the medium shadow color.

›

success_shadow?: string | undefined;

Override the success shadow color.

›

success_background_light?: string | undefined;

Override the light success background color.

›

button_ripple?: string | undefined;

Override the button ripple color.

›

dialog_backdrop?: string | undefined;

Override the dialog backdrop color.

›

space_0u?: string | undefined;

Override the 0u spacing token.

›

space_1u?: string | undefined;

Override the 1u spacing token.

›

space_2u?: string | undefined;

Override the 2u spacing token.

›

space_3u?: string | undefined;

Override the 3u spacing token.

›

space_4u?: string | undefined;

Override the 4u spacing token.

›

space_5u?: string | undefined;

Override the 5u spacing token.

›

space_6u?: string | undefined;

Override the 6u spacing token.

›

space_7u?: string | undefined;

Override the 7u spacing token.

›

space_8u?: string | undefined;

Override the 8u spacing token.

›

space_10u?: string | undefined;

Override the 10u spacing token.

›

space_12u?: string | undefined;

Override the 12u spacing token.

›

space_14u?: string | undefined;

Override the 14u spacing token.

›

space_16u?: string | undefined;

Override the 16u spacing token.

›

space_24u?: string | undefined;

Override the 24u spacing token.

›

font_size_2xs?: string | undefined;

Override the 2xs font size token.

›

font_size_xs?: string | undefined;

Override the xs font size token.

›

font_size_sm?: string | undefined;

Override the sm font size token.

›

font_size_md?: string | undefined;

Override the md font size token.

›

font_size_lg?: string | undefined;

Override the lg font size token.

›

font_size_xl?: string | undefined;

Override the xl font size token.

›

font_size_2xl?: string | undefined;

Override the 2xl font size token.

›

font_size_3xl?: string | undefined;

Override the 3xl font size token.

›

size_8u?: string | undefined;

Override the 8u size token.

›

size_10u?: string | undefined;

Override the 10u size token.

›

size_12u?: string | undefined;

Override the 12u size token.

›

size_18u?: string | undefined;

Override the 18u size token.

›

size_20u?: string | undefined;

Override the 20u size token.

›

size_24u?: string | undefined;

Override the 24u size token.

›

size_32u?: string | undefined;

Override the 32u size token.

›

size_36u?: string | undefined;

Override the 36u size token.

›

size_40u?: string | undefined;

Override the 40u size token.

›

size_45u?: string | undefined;

Override the 45u size token.

›

size_50u?: string | undefined;

Override the 50u size token.

›

shadow_sm?: string | undefined;

Override the small shadow token.

›

shadow_md?: string | undefined;

Override the medium shadow token.

›

shadow_lg?: string | undefined;

Override the large shadow token.

›

shadow_xl?: string | undefined;

Override the xl shadow token.

›

shadow_success?: string | undefined;

Override the success shadow token.

›

ring_primary?: string | undefined;

Override the primary ring color token.

›

letter_spacing_tight?: string | undefined;

Override the tight letter spacing token.

›

dark_mode_settings?: DarkModeSettings | undefined;

Override the dark mode theme settings used by the embedded UI.

›

primary_color?: string | undefined;

Override the dark mode primary color.

›

background_color?: string | undefined;

Override the dark mode background color.

›

text_color?: string | undefined;

Override the dark mode text color.

›

token_overrides?: UITokenOverrides | undefined;

Fine-grained dark mode token overrides for the embedded UI theme.

›

space_unit?: string | undefined;

Override the base spacing unit used by the shared UI theme.

›

card?: string | undefined;

Override the card background color.

›

card_foreground?: string | undefined;

Override the card foreground color.

›

popover?: string | undefined;

Override the popover background color.

›

popover_foreground?: string | undefined;

Override the popover foreground color.

›

primary_foreground?: string | undefined;

Override the foreground color used on primary surfaces.

›

secondary?: string | undefined;

Override the secondary surface color.

›

secondary_foreground?: string | undefined;

Override the foreground color used on secondary surfaces.

›

accent?: string | undefined;

Override the accent surface color.

›

accent_foreground?: string | undefined;

Override the foreground color used on accent surfaces.

›

ring?: string | undefined;

Override the focus ring color.

›

foreground?: string | undefined;

Override the main foreground color.

›

foreground_inverse?: string | undefined;

Override the inverse foreground color.

›

secondary_text?: string | undefined;

Override the secondary text color.

›

muted?: string | undefined;

Override the muted text or surface color.

›

border?: string | undefined;

Override the default border color.

›

border_hover?: string | undefined;

Override the border color used on hover states.

›

divider?: string | undefined;

Override the divider color.

›

input_background?: string | undefined;

Override the input background color.

›

input_border?: string | undefined;

Override the input border color.

›

input_focus_border?: string | undefined;

Override the input border color used on focus.

›

background_subtle?: string | undefined;

Override the subtle background color.

›

background_hover?: string | undefined;

Override the background color used on hover states.

›

primary_hover?: string | undefined;

Override the hover color for primary actions.

›

error?: string | undefined;

Override the error text or accent color.

›

error_background?: string | undefined;

Override the error background color.

›

error_border?: string | undefined;

Override the error border color.

›

warning?: string | undefined;

Override the warning text or accent color.

›

warning_background?: string | undefined;

Override the warning background color.

›

warning_border?: string | undefined;

Override the warning border color.

›

warning_text?: string | undefined;

Override the warning text color.

›

success?: string | undefined;

Override the success text or accent color.

›

success_background?: string | undefined;

Override the success background color.

›

success_border?: string | undefined;

Override the success border color.

›

info?: string | undefined;

Override the info text or accent color.

›

info_background?: string | undefined;

Override the info background color.

›

radius_md?: string | undefined;

Override the medium radius token.

›

radius_lg?: string | undefined;

Override the large radius token.

›

radius_xl?: string | undefined;

Override the extra-large radius token.

›

radius_2xl?: string | undefined;

Override the 2xl radius token.

›

radius_2xs?: string | undefined;

Override the 2xs radius token.

›

radius_xs?: string | undefined;

Override the extra-small radius token.

›

radius_full?: string | undefined;

Override the fully rounded radius token.

›

border_width_thin?: string | undefined;

Override the thin border width token.

›

border_width_regular?: string | undefined;

Override the regular border width token.

›

scrollbar_track?: string | undefined;

Override the scrollbar track color.

›

scrollbar_thumb?: string | undefined;

Override the scrollbar thumb color.

›

scrollbar_thumb_hover?: string | undefined;

Override the scrollbar thumb hover color.

›

shadow_color?: string | undefined;

Override the base shadow color.

›

shadow_light_color?: string | undefined;

Override the light shadow color.

›

shadow_medium_color?: string | undefined;

Override the medium shadow color.

›

success_shadow?: string | undefined;

Override the success shadow color.

›

success_background_light?: string | undefined;

Override the light success background color.

›

button_ripple?: string | undefined;

Override the button ripple color.

›

dialog_backdrop?: string | undefined;

Override the dialog backdrop color.

›

space_0u?: string | undefined;

Override the 0u spacing token.

›

space_1u?: string | undefined;

Override the 1u spacing token.

›

space_2u?: string | undefined;

Override the 2u spacing token.

›

space_3u?: string | undefined;

Override the 3u spacing token.

›

space_4u?: string | undefined;

Override the 4u spacing token.

›

space_5u?: string | undefined;

Override the 5u spacing token.

›

space_6u?: string | undefined;

Override the 6u spacing token.

›

space_7u?: string | undefined;

Override the 7u spacing token.

›

space_8u?: string | undefined;

Override the 8u spacing token.

›

space_10u?: string | undefined;

Override the 10u spacing token.

›

space_12u?: string | undefined;

Override the 12u spacing token.

›

space_14u?: string | undefined;

Override the 14u spacing token.

›

space_16u?: string | undefined;

Override the 16u spacing token.

›

space_24u?: string | undefined;

Override the 24u spacing token.

›

font_size_2xs?: string | undefined;

Override the 2xs font size token.

›

font_size_xs?: string | undefined;

Override the xs font size token.

›

font_size_sm?: string | undefined;

Override the sm font size token.

›

font_size_md?: string | undefined;

Override the md font size token.

›

font_size_lg?: string | undefined;

Override the lg font size token.

›

font_size_xl?: string | undefined;

Override the xl font size token.

›

font_size_2xl?: string | undefined;

Override the 2xl font size token.

›

font_size_3xl?: string | undefined;

Override the 3xl font size token.

›

size_8u?: string | undefined;

Override the 8u size token.

›

size_10u?: string | undefined;

Override the 10u size token.

›

size_12u?: string | undefined;

Override the 12u size token.

›

size_18u?: string | undefined;

Override the 18u size token.

›

size_20u?: string | undefined;

Override the 20u size token.

›

size_24u?: string | undefined;

Override the 24u size token.

›

size_32u?: string | undefined;

Override the 32u size token.

›

size_36u?: string | undefined;

Override the 36u size token.

›

size_40u?: string | undefined;

Override the 40u size token.

›

size_45u?: string | undefined;

Override the 45u size token.

›

size_50u?: string | undefined;

Override the 50u size token.

›

shadow_sm?: string | undefined;

Override the small shadow token.

›

shadow_md?: string | undefined;

Override the medium shadow token.

›

shadow_lg?: string | undefined;

Override the large shadow token.

›

shadow_xl?: string | undefined;

Override the xl shadow token.

›

shadow_success?: string | undefined;

Override the success shadow token.

›

ring_primary?: string | undefined;

Override the primary ring color token.

›

letter_spacing_tight?: string | undefined;

Override the tight letter spacing token.

›

adapter: PlatformAdapter;

The adapter object injected by the framework package. This is what gives the shared hooks framework-aware navigation.

How it works

The hook itself is small. It reads the value from DeploymentContext, then enforces the two invariants the rest of the shared client layer depends on: the hook must be inside <DeploymentProvider />, and once loading is finished there must be a deployment object.

The provider does the real work. It decodes the backend host from the public key, loads /deployment, applies any uiOverwrites, and persists the staging __dev_session__ handshake when the deployment is in test mode.

Because every other shared client hook depends on that same context, useDeployment() is the cleanest way to inspect what the client layer thinks the current deployment looks like.

When to use it

Use it when a component needs deployment settings, frontend URLs, or adapter behavior.
It throws if you call it outside <DeploymentProvider />.

Examples

Read app branding from the deployment

export default function AppHeader() {  const { deployment, loading } = useDeployment();  if (loading) {    return null;  }  return <h1>{deployment.ui_settings.app_name}</h1>;}

Use deployment settings to branch UI

export default function WorkspaceGate() {  const { deployment, loading } = useDeployment();  if (loading) {    return null;  }  return deployment.b2b_settings.workspaces_enabled ? (    <div>Workspace-enabled deployment</div>  ) : (    <div>Organizations only</div>  );}

useDeployment() hook

Usage

Return value

How it works

When to use it

Examples

Read app branding from the deployment

Use deployment settings to branch UI

On this page

`useDeployment()` hook