> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# TapRailsThemeProvider

> Root context provider for TapRails UI theming and automatic session key setup.

`TapRailsThemeProvider` is the root context provider for all TapRails UI components. It serves two purposes:

1. **Theme context** — makes your color overrides available to all TapRails components via `useTheme`
2. **Session key management** — automatically detects when a session key is missing and shows the `SessionKeySetupFlow`

## Import

```ts theme={null}
import { TapRailsThemeProvider } from '@taprails/tap-to-pay';
```

## Usage

```tsx theme={null}
// Wrap your root component
export default function App() {
  return (
    <TapRailsThemeProvider
      colorOverrides={{
        primary: '#6366F1',
      }}
    >
      <YourApp />
    </TapRailsThemeProvider>
  );
}
```

## Props

<ParamField path="colorOverrides" type="Partial<TapRailsColors>">
  Optional color overrides to apply to the TapRails theme. Any keys not provided fall back to TapRails defaults.
</ParamField>

***

## TapRailsColors

```ts theme={null}
interface TapRailsColors {
  primary: string;
  success: string;
  error: string;
  background: string;
  surface: string;
  text: string;
  textMuted: string;
  border: string;
}
```

***

## useTheme

Access the merged theme (your overrides + TapRails defaults) inside any child component:

```ts theme={null}
import { useTheme } from '@taprails/tap-to-pay';

const theme = useTheme();
// theme.colors.primary
// theme.typography.styles.h1
// theme.typography.styles.body
```

<Warning>
  `useTheme` must be called within a component that is a descendant of `TapRailsThemeProvider`. Calling it outside will throw an error.
</Warning>

***

## TapRailsTheme Type

```ts theme={null}
interface TapRailsTheme {
  colors: TapRailsColors;
  typography: {
    styles: {
      h1: TextStyle;
      h2: TextStyle;
      h3: TextStyle;
      body: TextStyle;
      bodySmall: TextStyle;
      label: TextStyle;
      button: TextStyle;
      mono: TextStyle;
    };
  };
}
```