# @fayegram-ai/faye-ui/provider/provider

Public exports and dependency-resolved component properties, with usage and rendering guidance.

## Import

```tsx
import { FayeUIProvider, ThemeScope, PortalTheme, ComponentStyleScope } from '@fayegram-ai/faye-ui/provider/provider';
```

[Usage and behavior guide](/docs/theming/) · [API JSON](/api/packages/provider/provider.json)

This entry declares a client boundary. Follow the rendering guide for framework integration.

## Public exports

| Name | Kind | Resolved declaration type |
|---|---|---|
| `FayeUIProvider` | value | `({ accessibility, interaction, children, initialPreference, serverScheme, storageKey, store: externalStore, density, direction, locale, catalogs, themeId, axes, motion, variables, profiles, settings, ownerDocument, portalContainer, nonce, applyToDocument }: FayeUIProviderProps) => import("react").JSX.Element` |
| `useColorScheme` | value | `() => { setPreference: (value: ColorPreference) => void; preference: ColorPreference; scheme: Scheme; }` |
| `useEnvironment` | value | `() => Environment & { message: MessageFormatter; }` |
| `useVisualScope` | value | `() => VisualScope` |
| `useAccessibilityPreferences` | value | `() => AccessibilityPreferences` |
| `useInputModality` | value | `(ownerDocument?: Document) => InputModality` |
| `ThemeScope` | value | `({ accessibility, interaction, scheme, density, direction, themeId, axes, motion, variables, mode, profiles, settings, children, style, className, ...props }: ThemeScopeProps) => import("react").JSX.Element` |
| `PortalTheme` | value | `({ children }: { children: ReactNode; }) => import("react").JSX.Element` |
| `ComponentStyleScope` | value | `<N extends string>({ name, variants, children }: { name: N; variants: VisualVariants<N>; children: ReactNode; }) => import("react").JSX.Element` |
| `useComponentStyle` | value | `(name: string, part?: string, instance?: Readonly<Record<string, string \| undefined>>) => { className: string \| undefined; variants: Readonly<Record<string, string>>; attributes: { [k: string]: string; }; }` |
| `useConfiguredProps` | value | `<T extends object>(name: string, part: string, props: T, libraryDefaults?: Partial<T>) => T` |
| `useInteractionVisuals` | value | `(options?: InteractionOptions) => { attributes: { "data-faye-ui-interaction-variant": import("@fayegram-ai/faye-ui/contracts").InteractionVariant; "data-faye-ui-interaction-level": import("@fayegram-ai/faye-ui/contracts").InteractionLevel; "data-faye-ui-track-effect": "expand" \| "highlight" \| "none"; "data-faye-ui-track-highlight": true \| undefined; }; style: CSSProperties; }` |
| `InputModality` | type | `InputModality` |
| `TokenVariables` | type | `Readonly<Record<'--faye-ui-${string}', string>>` |
| `VisualScope` | type | `VisualScope` |
| `Environment` | type | `Environment` |
| `ComponentConfiguration` | type | `ComponentConfiguration` |
| `FayeUIProviderProps` | type | `FayeUIProviderProps` |
| `ThemeScopeProps` | type | `ThemeScopeProps` |

## FayeUIProvider

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Properties

| Property | Required | Type | Meaning |
|---|---|---|---|
| `accessibility` | No | `AccessibilityOptions \| undefined` | See the usage contract and declaration. |
| `applyToDocument` | No | `boolean \| undefined` | Set false when another root already owns the document theme. |
| `axes` | No | `Readonly<Record<string, string>> \| undefined` | See the usage contract and declaration. |
| `catalogs` | No | `readonly MessageCatalog[] \| undefined` | See the usage contract and declaration. |
| `children` | Yes | `ReactNode` | See the usage contract and declaration. |
| `density` | No | `Density \| undefined` | See the usage contract and declaration. |
| `direction` | No | `Direction \| undefined` | See the usage contract and declaration. |
| `initialPreference` | No | `ColorPreference \| undefined` | See the usage contract and declaration. |
| `interaction` | No | `InteractionOptions \| undefined` | See the usage contract and declaration. |
| `locale` | No | `string \| undefined` | See the usage contract and declaration. |
| `motion` | No | `"system" \| "reduced" \| undefined` | See the usage contract and declaration. |
| `nonce` | No | `string \| undefined` | See the usage contract and declaration. |
| `ownerDocument` | No | `Document \| undefined` | See the usage contract and declaration. |
| `portalContainer` | No | `HTMLElement \| ShadowRoot \| undefined` | See the usage contract and declaration. |
| `profiles` | No | `readonly ComponentProfile[] \| undefined` | See the usage contract and declaration. |
| `serverScheme` | No | `Scheme \| undefined` | See the usage contract and declaration. |
| `settings` | No | `readonly ComponentSettings[] \| undefined` | See the usage contract and declaration. |
| `storageKey` | No | `string \| undefined` | See the usage contract and declaration. |
| `store` | No | `PreferenceStore \| undefined` | See the usage contract and declaration. |
| `themeId` | No | `string \| undefined` | See the usage contract and declaration. |
| `variables` | No | `Readonly<Record<'--faye-ui-${string}', string>> \| undefined` | See the usage contract and declaration. |



## ThemeScope

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Properties

| Property | Required | Type | Meaning |
|---|---|---|---|
| `accessibility` | No | `AccessibilityOptions \| undefined` | See the usage contract and declaration. |
| `axes` | No | `Readonly<Record<string, string>> \| undefined` | See the usage contract and declaration. |
| `density` | No | `Density \| undefined` | See the usage contract and declaration. |
| `direction` | No | `Direction \| undefined` | See the usage contract and declaration. |
| `interaction` | No | `InteractionOptions \| undefined` | See the usage contract and declaration. |
| `mode` | No | `"extend" \| "isolate" \| undefined` | See the usage contract and declaration. |
| `motion` | No | `"system" \| "reduced" \| undefined` | See the usage contract and declaration. |
| `profiles` | No | `readonly ComponentProfile[] \| undefined` | See the usage contract and declaration. |
| `scheme` | No | `Scheme \| undefined` | See the usage contract and declaration. |
| `settings` | No | `readonly ComponentSettings[] \| undefined` | See the usage contract and declaration. |
| `themeId` | No | `string \| undefined` | See the usage contract and declaration. |
| `variables` | No | `Readonly<Record<'--faye-ui-${string}', string>> \| undefined` | See the usage contract and declaration. |



## PortalTheme

Mirrors the logical scope onto the actual portal DOM, without another focus manager.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Properties

| Property | Required | Type | Meaning |
|---|---|---|---|
| `children` | Yes | `ReactNode` | See the usage contract and declaration. |



## ComponentStyleScope

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Properties

| Property | Required | Type | Meaning |
|---|---|---|---|
| `children` | Yes | `ReactNode` | See the usage contract and declaration. |
| `name` | Yes | `N` | See the usage contract and declaration. |
| `variants` | Yes | `VisualVariants<N>` | See the usage contract and declaration. |



## Defaults and customization

Defaults and native behavior are documented in the linked family guide. This reference does not infer a default from an optional property.

Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.

## State, events and accessibility

For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.

## Declaration authority

Generated from `packages/faye-ui/dist/provider/provider.d.ts` after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. [React DOM attributes](https://react.dev/reference/react-dom/components/common) and [Base UI component contracts](https://base-ui.com/react/overview/quick-start) describe the inherited foundations.