For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/components/tao-provider.md.
v0.0.57
  • English
  • TaoProvider

    Config@rockshin/tao-ui

    Provides global component defaults, portal scoping, and theme seed token overrides.

    When to use

    Wrap an app or subtree with TaoProvider to set size, disabled, variant, and theme defaults.

    Recommended

    • Prefer provider-level defaults for app-wide decisions.
    • Use nested providers for scoped theme overrides.

    Avoid

    • Do not override derived CSS variables directly unless a theme token cannot express the change.

    Examples

    Basic usage

    TSX

    Global sizes

    TSX

    Brand tokens and component tokens

    TSX

    Dark mode, compact density, and isolation

    TSX

    Global variants

    Set a common appearance for form controls and override individual controls when needed.

    TSX

    Brand colors

    Change brand colors across the same components while retaining status semantics.

    Default (Anthropic-neutral)
    oklch(0.205 0.01 70)
    Tag
    Vercel Black
    oklch(0.145 0 0)
    Tag
    Linear Indigo
    oklch(0.52 0.19 275)
    Tag
    Stripe Purple
    oklch(0.55 0.22 300)
    Tag
    Supabase Green
    oklch(0.62 0.17 155)
    Tag
    Notion Orange
    oklch(0.68 0.17 45)
    Tag
    TSX

    Semantic colors

    Configure success, warning, and error colors separately so states remain distinguishable.

    successDeployedPassedReady
    warningDegradedPreviewDraft
    errorFailedBlockedBroken

    ring color follows colorError token

    TSX

    Radius scale

    The base radius derives size-specific radii; compare the effect across controls.

    sharp · 2px
    r-2
    Tag
    default (10) · 10px
    r-10
    Tag
    rounded · 16px
    r-16
    Tag
    pill-ish · 24px
    r-24
    Tag
    TSX

    Nesting and isolation

    Nested providers can inherit or reset their theme without affecting the outer scope.

    outer · purple / large
    outer
    Tag
    inner · orange, size inherited (large)
    inner
    Tag
    inner · color inherited (purple), size=small
    inner
    Tag
    TSX

    Portal theme inheritance

    Open the dropdown to see that portal content retains its provider theme.

    Select popup portals to body but still reads the closest TaoProvider — both dropdowns below should match their parent primary.
    TSX

    Dynamic theme switching

    Change theme settings through state and observe the controls and popups update.

    active · Default (Anthropic-neutral)
    live
    Tag
    TSX

    Layout transparency

    The provider does not add a layout wrapper, so components retain their parent layout.

    Children of a single TaoProvider must land in separate grid columns. If the wrapper collapsed layout, both cards would stack in column 1.
    Sidebar
    col 1 · 200px
    Main
    col 2 · 1fr — buttons below should feel indigo
    TSX

    Component tokens

    Override tokens for a target component while other components retain the global theme.

    theme.components.Button — pill radius + custom padding/font weight
    TSX

    Compact density

    Compact mode changes spacing and control density while retaining the theme font size.

    theme.compact: control height 32→28, paddings one notch tighter
    Default
    Compact
    TSX

    Right-to-left layouts

    Set direction="rtl" on TaoProvider or use HTML dir="rtl" on a surrounding element. Components inherit the local direction, and popups keep the direction of their trigger even when rendered into a portal. An explicit component direction prop or nested provider can override it; Carousel uses rtl. Locale and direction are independent. Explicit popup placements such as bottomLeft retain their physical meaning.

    TSX

    17 languages and regional formats

    Switch the language to update component defaults, dates and numbers. Existing ISO date formats remain the default; this example explicitly requests a regional date with format="L". Numeric input still emits canonical ASCII decimal strings. Caller-owned labels are independent of the component dictionary.

    1 234 567,89
    Aucune donnée
    TSX

    API

    useTaoInternalConfig

    Internal component access for token propagation through third-party portals.

    PropertyDescriptionTypeDefault Value

    useTaoDirection

    Resolve DOM inheritance at a component's source, before it creates portals.

    PropertyDescriptionTypeDefault Value

    useTaoToken

    **antd theme.useToken counterpart, zero-runtime edition: returns every design token as a var(--tao-*) reference string, so custom components can stay visually consistent with tao-ui and still resolve in the browser against the live theme (dark mode, seed overrides, compact density):

    const { token } = useTaoToken();
    <div style={{ borderRadius: token['--tao-radius-lg'], padding: token['--tao-padding-lg'] }} />
    ```**
    
      |Property|Description|Type|Default Value|
    |:---:|:---:|:---:|:---:|
      
        
    
      ### TaoPortalScope
    
      **Re-establishes the theme token scope inside a portal. Floating components
    portal their popup to document.body, escaping the `[data-tao-provider]`
    element that carries custom token overrides; wrapping the portal content in
    this component re-applies those overrides so colors/sizes stay consistent.
    
    With `asChild`, merges the tokens onto the immediate child (via Radix Slot)
    instead of adding a wrapper div. Prefer `asChild` inside portals whose Radix
    primitive does NOT Presence-gate its Portal (notably `@radix-ui/react-select`
    — see `SelectPortal` in `node_modules/@radix-ui/react-select`): the wrapper
    div would otherwise render even while the popup is closed, leaving a ghost
    `<div data-tao-provider>` in the body for every mounted-but-closed Select.**
    
      |Property|Description|Type|Default Value|
    |:---:|:---:|:---:|:---:|
      |style|Additional style|`CSSProperties \| undefined`|`-`|
        
    
      ### TaoProvider
    
      
      |Property|Description|Type|Default Value|
    |:---:|:---:|:---:|:---:|
      |direction|Text and interaction direction. Defaults to the surrounding DOM direction.|`TaoDirection \| undefined`|`-`|
    |locale|Component text and regional settings; omitted keys inherit from the parent.|`Partial<TaoLocale> \| undefined`|`-`|
    |disabled|Whether to disable |`boolean \| undefined`|`-`|
        
    
      ### BuiltinTaoLocale
    
      **Complete dictionaries shipped by tao-ui; custom TaoLocale values stay compatible.**
    
      |Property|Description|Type|Default Value|
    |:---:|:---:|:---:|:---:|
      
        
    
      ### TaoLocale
    
      **Built-in Select and date-picker text. Arrays use calendar order (Monday first).**
    
      |Property|Description|Type|Default Value|
    |:---:|:---:|:---:|:---:|