# Tamagui Complete Documentation

> Tamagui is a complete UI solution for React Native and Web, with a fully-featured UI kit, styling engine, and optimizing compiler.



## core/settings

---
title: Settings
description: Strictness, SSR, theme class placement, and other createTamagui settings.
---

<IntroParagraph>
  Pass a `settings` object to `createTamagui` to control type strictness, SSR
  behavior, flex behavior, units, and how themes reach the DOM.
</IntroParagraph>

```tsx fileName="tamagui.config.ts"
export const config = createTamagui({
  // ...
  settings: {
    disableSSR: true,
    allowedStyleValues: 'somewhat-strict-web',
    defaultFont: 'body',
  },
})
```

[`@tamagui/config/v6`](/docs/core/config-v6) sets sensible values for all of these.
Spread `defaultConfig.settings` and override the keys you need.

## Options

<PropsTable
  data={[
    {
      name: `disableSSR`,
      type: `boolean`,
      description: `For SSR compatibility on the web, Tamagui renders once with the mediaQueryDefaultActive values for every media query, then renders again with the real values so hydration matches the server. Set this to true to skip the first pass and render with live media state right away, which is what client-only (SPA) apps want. See Server Rendering for the ClientOnly component and related hooks.`,
    },
    {
      name: `defaultFont`,
      required: false,
      type: `string`,
      description: `The key of the font given to createTamagui that text falls back to when it sets no fontFamily, so "body" or "heading".`,
    },
    {
      name: 'mediaQueryDefaultActive',
      required: false,
      type: 'Record<string, boolean>',
      description: `Which media queries count as active on the first render. Used for SSR.`,
    },
    {
      name: 'addThemeClassName',
      required: false,
      type: "false | 'html' | 'body'",
      default: false,
      description: `Where to put the root theme className on web. Styling <body> with theme CSS variables needs the class on body or above. When false, the class goes on the element TamaguiProvider renders.`,
    },
    {
      name: 'selectionStyles',
      required: false,
      type: '(theme) => ({ backgroundColor: Variable | string; color: Variable | string })',
      default: false,
      description: `Generates ::selection styles for text selection on the web.`,
    },
    {
      name: 'shouldAddPrefersColorThemes',
      required: false,
      type: 'boolean',
      default: `true`,
      description: `Generates prefers-color-scheme media queries for your light and dark themes. Increases total CSS size.`,
    },
    {
      name: 'onlyAllowShorthands',
      required: false,
      type: 'boolean',
      default: false,
      description: `Removes the types for the long-form version of every shorthand you define. See Shorthands.`,
    },
    {
      name: 'styleValueSyntax',
      required: false,
      type: `'string' | 'object'`,
      default: `undefined`,
      description: `Restrict conditional style values to one syntax. Flat values accept both the string form (bg="red hover:blue") and the object form (bg={{ default: 'red', hover: 'blue' }}). Setting this narrows the types to one form, makes the runtime warn on the other in development, and tells tamagui generate-prompt and the skills to only show that form.`,
    },
    {
      name: `allowedStyleValues`,
      required: false,
      type: 'AllowedStyleValuesSetting',
      description: `Controls type validation of single-token style values. See below. Run tamagui check --strict to validate conditional payloads against the project config too.`,
    },
    {
      name: 'styleCompat',
      required: false,
      type: `'legacy' | 'react-native' | 'web'`,
      default: `'web'`,
      description: `Which flex expansion semantics to follow where Yoga and CSS differ. Numeric lineHeight values are ratios in every mode.`,
    },
    {
      name: 'remBaseFontSize',
      required: false,
      type: 'number',
      default: `16`,
      description: `Base font size for rem calculations on native. On web, browsers use the root font size.`,
    },
    {
      name: 'defaultPosition',
      required: false,
      type: `'static' | 'relative'`,
      default: `'static'`,
      description: `Default position value for all Tamagui components.`,
    },
    {
      name: 'onlyShorthandStyleProps',
      required: false,
      type: 'boolean',
      default: false,
      description: `Removes the longhand border, outline, and shadow props (borderWidth, outlineWidth, shadowColor, and the rest) from the types, encouraging the combined border, outline, and boxShadow props instead. Type-level only.`,
    },
    {
      name: 'fastSchemeChange',
      required: false,
      type: 'boolean',
      default: false,
      description: `On iOS, returns color values as DynamicColorIOS so light and dark switches skip a re-render. The defaultTheme you pass to TamaguiProvider must match the current system color scheme.`,
    },
    {
      name: 'optimizeFor',
      required: false,
      type: `'updates' | 'first-render'`,
      default: `'updates' on web, 'first-render' on native`,
      description: `Chooses the render performance tradeoff. "updates" tracks which theme and media keys each component reads so changes re-render only their consumers, at a small per-component first-render cost. "first-render" skips per-key tracking for the fastest initial render. Theme and media changes still apply, but re-render coarsely. This is a startup-level setting. Do not change it at runtime.`,
    },
  ]}
/>

## allowedStyleValues

Controls which values the types accept for token-backed style props:

- `false` (default): any string, or number for styles that accept numbers
- `strict`: only tokens for any token-enabled property
- `strict-web`: same as strict, plus web-only values like `auto` and `inherit`
- `somewhat-strict`: tokens, or:
  - for `space` and `size`: percentage strings or numbers
  - for `radius`: numbers
  - for `zIndex`: numbers
  - for `color`: named colors or rgba and hsla strings
- `somewhat-strict-web`: same as somewhat-strict, plus web-only values

Pass one value for every category, or an object to set each category on its own:

```tsx
type AllowedValueSetting =
  | boolean
  | 'strict'
  | 'somewhat-strict'
  | 'strict-web'
  | 'somewhat-strict-web'

type AllowedStyleValuesSetting =
  | AllowedValueSetting
  | {
      space?: AllowedValueSetting
      size?: AllowedValueSetting
      radius?: AllowedValueSetting
      zIndex?: AllowedValueSetting
      color?: AllowedValueSetting
    }
```

## Environment variables

A few behaviors are set with environment variables rather than `settings`. Your
bundler can then drop the code paths you do not use. On web, use the Tamagui Vite or
Next.js plugin, or define them in your own bundler config. On native the extra size
is small enough not to matter.

<PropsTable
  data={[
    {
      name: 'TAMAGUI_TARGET',
      type: `'web' | 'native'`,
      description: `Which platform the bundle runs on. The Vite and Next.js plugins set it to web. Native builds set it to native on their own.`,
    },
    {
      name: 'TAMAGUI_CSS_VARIABLE_PREFIX',
      type: 'string',
      description: `Prefix added to every CSS variable Tamagui generates on web. Use it to avoid collisions with another library's custom properties.`,
    },
    {
      name: 'TAMAGUI_CSS_LAYER',
      type: 'string',
      description: `Wraps all generated CSS in a named @layer so other stylesheets can order themselves against it.`,
    },
    {
      name: 'TAMAGUI_DISABLE_NO_THEME_WARNING',
      type: `'1'`,
      description: `Silences the development warning when a component renders without any theme. Set it when you use Tamagui without themes on purpose.`,
    },
  ]}
/>


## core/html-primitives

---
title: HTML elements
description: Semantic HTML elements that render on web and native, in early development
---

<IntroParagraph>
  The `html` export renders semantic HTML on web and the matching React Native
  primitives on native. It follows web and React Strict DOM semantics, and suits
  screens that are mostly web content.
</IntroParagraph>

Each member is an ordinary Tamagui component, so it takes Tamagui style props
alongside the DOM props for that element.

```tsx
import { html } from 'tamagui'

export function Article() {
  return (
    <html.article maxWidth={720} margin="auto" padding="4 md:8">
      <html.h1 color="color" fontSize="8">
        A semantic, styled heading
      </html.h1>
      <html.p color="color" marginTop="4" opacity={0.75}>
        The same source renders semantic tags on web and native primitives in a
        native app.
      </html.p>
    </html.article>
  )
}
```

You can also import `html` from `@tamagui/core`.

## Before you use it

`html.*` is in early development. Its elements keep the browser's default
`display`, so on web `html.div` and `html.p` are `display: block` and `html.span`
is inline. React Native only has flex layout, so the same tree can lay out
differently on native. [`View` and `Text`](/docs/core/view-and-text) are flex
columns everywhere, which is why they stay the default for cross-platform
screens.

Every `html.*` member is built on `View` or `Text`, so both take the same style
props, tokens, themes, and variants, and you can mix them in one tree.

## What renders

On web, `html.article`, `html.h1`, and `html.p` render literal `article`, `h1`,
and `p` elements. Tamagui applies explicit element defaults so the result does
not depend on whether the page loaded a CSS reset.

On native, the same members render through one of four backing primitives:

| Source element | Native backing |
| --- | --- |
| layout elements such as `div`, `article`, `main`, `section`, and `ul` | `View` |
| text elements such as `span`, `p`, `strong`, and `h1` | `Text` |
| `img` | `Image` |
| `input` and `textarea` | `TextInput` |

The native runtime maps supported DOM prop names to their React Native names.
It also wraps literal text inside a View-backed element, because a React Native
`View` cannot render a raw string. The compiler performs the same mapping and
text wrapping ahead of time when it can lower the element.

## Available elements

The root export includes:

```txt
a article aside b bdi bdo blockquote br button code del div em
fieldset footer form h1 h2 h3 h4 h5 h6 header hr i img input
ins kbd label li main mark nav ol optgroup option p pre s section
select span strong sub sup textarea u ul
```

Props are specific to the element. For example, `html.a` accepts `href`,
`html.img` accepts `src` and `alt`, and `html.input` accepts input props. Void
elements such as `br`, `hr`, `img`, and `input` reject children in TypeScript.

Because these are Tamagui components, style props use the same tokens, themes,
shorthands, and [flat conditional values](/docs/guides/flat-values) as `View`
and `Text`:

```tsx
<html.button
  backgroundColor="background hover:background-hover"
  borderColor="border-color"
  borderWidth={1}
  padding="3"
  onPress={save}
>
  Save
</html.button>
```

## Native support is explicit

A browser feature without a faithful native equivalent does not silently turn
into a different control. Native builds reject `html.select`, `html.option`, and
`html.optgroup`, because React Native has no menu-based select control. Unsupported
props and events also produce a diagnostic naming the unsupported behavior.

Some elements preserve their useful native subset. `html.form` and
`html.fieldset`, for example, render containers on native, while browser form
submission, validation, and reset behavior remain web-only.

The compiler and runtime read the same generated compatibility tables. Running
with or without compiler lowering therefore uses the same supported tag and prop
contract.

## Compiler behavior

The compiler treats `html.*` as regular lowering candidates. On web it can
replace a component with its literal tag, extracted classes, and any remaining
host props. On native it can replace the same component with its backing
primitive and mapped props. If the compiler cannot lower an ordinary use, the
root export still has a runtime implementation on both platforms.

For new code, use the root `html` export shown here. The standalone
`tamagui/dom` and `@tamagui/core/dom` entries are deprecated implementation
surfaces. Their `style()` handles are compile-only and throw if they reach the
runtime.


## core/tamagui-provider

---
title: TamaguiProvider
description: Mount your config, generate its CSS, and trim theme JS from the client bundle.
---

<IntroParagraph>
  `TamaguiProvider` makes the object returned by `createTamagui` available to
  every component below it.
</IntroParagraph>

Render it once at the root of your app:

```tsx line=3-5 fileName="App.tsx"
import { TamaguiProvider } from 'tamagui'
import { config } from './tamagui.config'

export default function App() {
  return (
    <TamaguiProvider config={config} defaultTheme="light">
      <AppContents />
    </TamaguiProvider>
  )
}
```

Import `tamagui.config.ts` in one place near the root. Importing it from many files
invites circular imports and breaks hot reloading. Other files reach the config
through style props, `useMedia`, `useTheme`, or getters like `getTokenValue`. The full
object is available from `getConfig` when you need it.

Set your root theme with `defaultTheme` instead of wrapping the app in `<Theme>`.
That keeps the [`fastSchemeChange` setting](/docs/core/settings) working on native,
and lets light and dark switches on web use media query updates during SSR.

## Props

<PropsTable
  data={[
    {
      name: 'config',
      required: true,
      type: 'TamaguiInternalConfig',
      description: `The object returned by createTamagui.`,
    },
    {
      name: 'defaultTheme',
      required: false,
      type: 'string',
      description: `The initial top level theme. Falls back to the first theme in your config when null or undefined, which covers useColorScheme() returning null on the first render.`,
    },
    {
      name: 'disableInjectCSS',
      required: false,
      type: 'boolean',
      description: `By default Tamagui inserts its CSS with useInsertionEffect on load. Turn this on when you serve the CSS yourself, which every SSR setup should. See Generating CSS below.`,
    },
    {
      name: 'insets',
      required: false,
      type: '{ top?: number; bottom?: number; left?: number; right?: number }',
      description: `Safe area insets for iOS. Required for vertical Slider to behave on iOS. Pass the value from the useSafeAreaInsets() hook.`,
    },
    {
      name: 'className',
      required: false,
      type: 'string',
      description: `Extra class names for the root element on web.`,
    },
  ]}
/>

## Generating CSS

On the client, Tamagui injects the CSS for your configuration into `document.head`.
For production you want that CSS served with the page. Set `disableInjectCSS` on
`TamaguiProvider`, then pick one of three ways to emit it.

If your framework has server-side layouts, render it inline:

```tsx fileName=app/_layout.tsx
import { config } from './tamagui.config'

export default () => (
  <html>
    <head>
      <style
        dangerouslySetInnerHTML={{
          __html: config.getCSS(),
        }}
      />
    </head>
    <body>
      <Slot />
    </body>
  </html>
)
```

To share one CSS file across every page, use the `outputCSS` option of a bundler
plugin and import the generated file in your app:

```tsx fileName=vite.config.ts
import { tamaguiPlugin } from '@tamagui/cli/vite'

export default {
  plugins: [
    tamaguiPlugin({
      config: './src/tamagui.config.ts',
      outputCSS: './src/tamagui.generated.css',
    }),
  ],
}
```

Or generate it with the CLI. Create a `tamagui.build.ts`:

```tsx fileName=tamagui.build.ts
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  components: ['tamagui'],
  config: './config/tamagui.config.ts',
  outputCSS: './tamagui.generated.css',
} satisfies TamaguiBuildOptions
```

Then run:

```bash
npx @tamagui/cli generate
```

The [CLI guide](/docs/core/cli#generate) covers `generate` and the other commands.

## Tree shaking themes

Theme JS can reach 20KB or more. Tamagui writes every theme value to a CSS variable,
and the client can read those variables back from the DOM instead of loading the
theme object. Dropping themes from the client bundle helps Lighthouse scores.

This only applies to server rendered web apps such as Next.js, One, and Vite SSR.
The CSS must come from `config.getCSS()` or a bundler plugin's `outputCSS` so it is
present before hydration. Metro, Expo, and static sites keep their themes in JS.

```tsx fileName="tamagui.config.ts"
import { defaultConfig, themes } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  // only load themes on server - client hydrates from CSS
  // for non-One Vite apps, use import.meta.env.SSR instead
  themes: process.env.VITE_ENVIRONMENT === 'client' ? ({} as typeof themes) : themes,
})
```


## core/exports

---
title: Exports
description: Constants, helpers, hooks, components, and types
---

<IntroParagraph>
  Import core utilities from `tamagui` or `@tamagui/core`. Ref utilities are
  also available from `@tamagui/element`.
</IntroParagraph>

## Constants

[Constants are re-exported from @tamagui/constants](https://github.com/tamagui/tamagui/blob/main/code/core/constants/src/constants.ts):

- `isWeb`: true if targeting the web (true for SSR and client)
- `isBrowser`: true when both `navigator` and `location` are defined
- `isServer`: `isWeb && !isBrowser`
- `isClient`: `isWeb && isBrowser`
- `isChrome`: client-side Chrome
- `isWebTouchable`: web-only touch device (client side only)
- `isTouchable`: true on native or touch-capable web clients

---

## Helpers

### getConfig

`getConfig` returns your fully parsed Tamagui config. It avoids the circular
imports that come with importing the config directly. Prefer `useTheme` for
themes and `getTokens`/`getToken`/`getTokenValue` for tokens, and use this for
other parts of the config.

### insertFont

```tsx
type insertFont = (name: string, fontIn: GenericFont) => ParsedFont
```

Adds a new font after the initial `createTamagui` call. `GenericFont` matches a
font passed to `createTamagui`, and `ParsedFont` is the font with subkeys
turned into variable objects.

### updateFont

The same as insertFont, but will update an existing font.

### isTamaguiComponent

```tsx
type isTamaguiComponent = (component: any, name?: string) => boolean
```

If no name given, true if a Tamagui component, if name given ensures it's the
specific named Tamagui component.

### isTamaguiElement

```tsx
type isTamaguiElement = (child: any, name?: string) => boolean
```

If no name given, true if a Tamagui ReactElement, if name given ensures it's the
specific named Tamagui component element.

### getTokens

```tsx
;() => TokensParsed
```

Returns the parsed Tamagui config object of all your tokens, can be used at
runtime to get values from tokens. If you are looking to get a single token
value, prefer `getToken` or `getTokenValue`.

### getToken

```tsx
;(name: Token, group?: keyof Tokens) => any
```

Given the specific name of a token or a name + group, will return the value as
either a variable on the web, or raw value on native. So if you define a size
token with key `small` and value of `14`:

```tsx
getToken('size.small') // returns on web var(--size-small), native 14
getToken('small', 'size') // returns on web var(--size-small), native 14
```

### getTokenValue

```tsx
;(name: Token, group?: keyof Tokens) => any
```

Similar to getToken, but always returns the raw value rather than the variable
name. If you define a size token with key `small` and value of `14`:

```tsx
getTokenValue('size.small') // returns 14
getTokenValue('small', 'size') // returns 14
```

### getVariable

```tsx
type getVariable = (value: Variable) => string
```

Accepts a `Variable` from a parsed theme or token (returned by
`createTamagui`, `useTheme`, or `getTokens`).

Calling `getVariable(useTheme().color)` returns `var(--color)` on web, and
`#fff` on other platforms.

### splitStyleProps

`splitStyleProps` partitions an object in one pass and returns
`[selectedProps, remainingProps]`. With no options, the first object contains
style props and the second contains everything else. Props keep their authored
keys by default. It is exported from `@tamagui/core`, `@tamagui/ui`, and
`tamagui`:

```tsx
import { splitStyleProps } from 'tamagui'

const [styleProps, regularProps] = splitStyleProps(props)
```

Pass `expandShorthands: true` to write selected shorthand props under their
canonical keys:

```tsx
const [styleProps, regularProps] = splitStyleProps(props, {
  expandShorthands: true,
})
```

A filter map selects only its canonical keys. Style props excluded by the map
remain in the second object. This also lets a component intentionally select
non-style behavior props:

```tsx
import { splitStyleProps, stylePropsTextOnly } from '@tamagui/core'

const [textProps, frameProps] = splitStyleProps(props, {
  expandShorthands: true,
  filter: {
    ...stylePropsTextOnly,
    ellipsis: true,
    numberOfLines: true,
  },
})
```

For dynamic rules, `filter` can be a callback. It receives the canonical key,
the value, the original authored key, and whether the canonical key is a known
style prop:

```tsx
const [selectedProps, remainingProps] = splitStyleProps(props, {
  filter: (key, value, originalKey, isStyleProp) => {
    return (isStyleProp && key.startsWith('font')) || originalKey === 'numberOfLines'
  },
})
```

Filter maps infer the selected keys precisely. A callback can return a type
predicate on `originalKey` when its rule narrows to a known key union.

### getWebElement

A runtime utility that narrows a `TamaguiElement` to an `HTMLElement`. Throws if
the element is not an HTMLElement. Useful for platform-specific code where you
know you're on web.

```tsx
import { getWebElement } from 'tamagui' // or '@tamagui/element'

// Narrows to HTMLElement
const el = getWebElement(ref.current)

// Or narrow to a specific element type
const input = getWebElement<HTMLInputElement>(ref.current)
input.selectionStart // typed correctly
```

---

## Hooks

See [useMedia](/docs/core/use-media) for media queries and
[useTheme](/docs/core/use-theme) for theme values.

### useIsomorphicLayoutEffect

Uses `useEffect` on the server and `useLayoutEffect` on the client to avoid
layout effect warnings during server rendering.

### useWebRef

For platform-specific files (`.tsx` and `.native.tsx`), this hook creates a
properly typed ref for web that also composes with a forwarded ref. When you
need to access `HTMLElement`-specific properties like `selectionStart` on
inputs, this avoids needing `any` casts.

```tsx
import { useWebRef } from 'tamagui' // or '@tamagui/element'

// In your .tsx (web) file:
function MyInput(props, forwardedRef) {
  const { ref, composedRef } = useWebRef<HTMLInputElement>(forwardedRef)

  // ref.current is typed as HTMLInputElement
  // Access web-specific properties safely:
  const start = ref.current?.selectionStart

  // composedRef forwards to both ref and forwardedRef
  return <StyledInput ref={composedRef} />
}
```

### useNativeRef

For platform-specific files (`.native.tsx`), this hook creates a properly typed
ref for React Native that also composes with a forwarded ref. Pairs with
`useWebRef` for cross-platform component development.

```tsx
import { useNativeRef } from 'tamagui' // or '@tamagui/element'

// In your .native.tsx file:
function MyComponent(props, forwardedRef) {
  const { ref, composedRef } = useNativeRef(forwardedRef)

  // ref.current is typed as View
  return <StyledView ref={composedRef} />
}
```

For input components, use `useNativeInputRef` which types to `TextInput`:

```tsx
import { useNativeInputRef } from 'tamagui' // or '@tamagui/element'

function MyInput(props, forwardedRef) {
  const { ref, composedRef } = useNativeInputRef(forwardedRef)
  // ref.current is typed as TextInput
  return <StyledInput ref={composedRef} />
}
```

### useThemeName

Returns the string name of the current theme.

### useIsTouchDevice

SSR-friendly, only true if native touchable or web touchable device (client
side, not server side).

### useDidFinishSSR

SSR-friendly, returns true if SSR has completed on the client, false before
hydration done. On server it's always false.

## Components

### ClientOnly

A component that opts its children out of SSR. When wrapped in `ClientOnly`,
Tamagui avoids double-renders in various places which results in faster
client-side rendering.

```tsx
import { ClientOnly } from 'tamagui' // or '@tamagui/core'

// Children will render only on the client, skipping SSR entirely
<ClientOnly>
  <MyClientOnlyComponent />
</ClientOnly>

// Can be conditionally enabled
<ClientOnly enabled={shouldSkipSSR}>
  <MyComponent />
</ClientOnly>
```

---

## Type helpers

### GetProps

Fetches the type of props for a Tamagui component:

```tsx
import { View, GetProps, styled } from '@tamagui/core'

const X = styled(View, {})

type XProps = GetProps<typeof X>
```

### GetRef

Fetches the type of a ref for a Tamagui component, or any React component:

```tsx
import { View, GetRef, styled } from '@tamagui/core'

const X = styled(View, {})

const MyComponent = () => {
  const ref = useRef<GetRef<typeof X>>()
  return <X ref={ref} />
}
```


## core/theme

---
title: Theme
description: Change the theme for any subtree
---

<IntroParagraph>
  Change the theme for any subtree by passing its name to the `Theme` component.
</IntroParagraph>

## Usage

Change the theme for any subtree:

```tsx
import { Button, Theme } from 'tamagui'

export default () => (
  <Theme name="dark">
    <Button>I'm a dark button</Button>
    <Button theme="level2">I'm using dark_level2 theme</Button>
  </Theme>
)
```

## Theme updates

Use `<ThemeUpdate>` to override theme values for a subtree, much like redefining
a CSS custom property on one node. Listed keys override and everything else
inherits from the parent theme.

```tsx
import { ThemeUpdate, html } from 'tamagui'

export default () => (
  <ThemeUpdate background-hover="blue-500 dark:blue-300">
    <html.div bg="background hover:background-hover" />
  </ThemeUpdate>
)
```

Values use the same flat grammar as style props. `<ThemeUpdate>` applies its values
to a whole subtree, so it supports modifiers that describe a subtree:

- **Theme:** `dark:`, `light:`, or any configured theme name. `blue:` applies
  under `dark_blue`, `light_blue`, or a theme named `blue`.
- **Platform:** `ios:`, `android:`, `web:`, and `native:`.

Interaction states such as `hover:` and `press:`, and media queries such as
`sm:`, describe an element rather than a subtree. They warn in development and
are dropped here.

A named theme and an update compose through nesting:

```tsx
<Theme name="dark">
  <ThemeUpdate background="red">
    {/* dark, with background overridden */}
  </ThemeUpdate>
</Theme>
```

Keys must be theme keys or [custom variables](#custom-variables) declared in
the config. Unknown keys warn in development and are dropped so web and native
behave the same. `<ThemeUpdate>` accepts children and typed theme or custom
variable keys. Theme controls such as `name` and `shallow` stay on
`<Theme>`.

### Custom variables

Declare design-system values in `createTamagui` to make them work anywhere a
theme key works: style props, `useTheme()`, and `<ThemeUpdate>` values.

```tsx
const config = createTamagui({
  // ...tokens, themes
  variables: {
    surfaceBorder: 'border-color',
    disabledOpacity: 0.5,
    focusRingColor: 'blue-500',
    focusRingWidth: 2,
    pressScale: 0.97,
    accent: { light: '#005ac8', dark: '#78b4ff' },
  },
})
```

Use and redefine them like any other theme value:

```tsx
<html.div borderColor="surfaceBorder" />

<ThemeUpdate surfaceBorder="red-500">
  {/* this subtree sees the red surface border */}
</ThemeUpdate>
```

### References and units

Inline values can reference theme keys and tokens:

- `background` finds the theme key or custom variable visible at the `<ThemeUpdate>`
  node.
- `size.4` and `color.blue-500` reference tokens by category.
- A bare token name such as `blue-500` checks theme keys first, then scans color,
  space, size, radius, and zIndex tokens. Use the qualified form when a name
  exists in more than one category.

References resolve at the `<ThemeUpdate>` node and descendants inherit the result.
Chains are supported, while a reference cycle drops the involved keys on both
platforms with a development warning.

Numbers become `px` on web and stay numbers on native, matching numeric style
props. Keys ending in `opacity`, `scale`, `zIndex`, `weight`, `flex`, `grow`,
`shrink`, or `ratio` stay unitless. Use a string such as `"10px"`
or `px(10)` for an explicit pixel value.

### Nesting and updates

ThemeUpdate layers stack, with the nearest definition winning per key. A `<Theme>`
that resolves a new name resets keys defined by that theme. Put the ThemeUpdate
inside that boundary when it should survive the switch. Custom variables are
defined on base themes, so sub-themes inherit their updates.

Changing update values leaves unrelated descendants alone. Tamagui tracks
which keys each component reads, and only readers of a changed key update. On
web, styled components restyle through CSS custom properties without a
JavaScript render. JavaScript readers such as `useTheme()` and animation
drivers see the same values on both platforms. With `settings.fastSchemeChange`
on iOS, keys whose light and dark values are literals retain the
`DynamicColorIOS` fast path.

## Defining themes

Themes sit above tokens. Tokens are static values, while themes change per
subtree like CSS variables.

Define themes however you want, but the `tamagui` components style themselves
from a set of pre-defined keys:

- `background`, `background-hover`, `background-press`, `background-focus`
- `border-color`, `border-color-hover`, `border-color-press`, `border-color-focus`
- `shadow-color`

These are optional, as you can always set `unstyled` on any Tamagui component to
use your own styles.

A simplified theme definition:

```tsx
import { createTamagui, createTokens } from 'tamagui'

const tokens = createTokens({
  color: {
    pinkDark: '#610c62',
    pinkLight: '#f17efc',
  },
  // ... see configuration docs for required tokens
})

export default createTamagui({
  tokens,
  themes: {
    dark: {
      background: '#000',
      color: '#fff',
    },
    light: {
      color: '#000',
      background: '#fff',
    },
    dark_pink: {
      background: tokens.color.pinkDark,
      color: tokens.color.pinkLight,
    },
    light_pink: {
      background: tokens.color.pinkLight,
      color: tokens.color.pinkDark,
    },
  },
})
```

Passing tokens to themes will reduce CSS, but is not required.

Access theme values through `styled()` or directly on a component:

```tsx
const P = styled(Text, {
  color: 'color-11'
})

// or directly
<Text color="color-11" />
```

Because we defined sub-themes `light_pink` and `dark_pink`, the `Theme`
component will now let us do this:

```tsx
import { Button, Theme } from 'tamagui'

export default () => {
  return (
    <Theme name="dark">
      <Button>I have the theme dark</Button>
      <Theme name="pink">
        <Button>I have the theme dark_pink</Button>
      </Theme>
    </Theme>
  )
}
```

Notice we just use the name `pink`.

For larger typed theme suites, see [Creating themes](/docs/guides/theme-builder),
which introduces `createThemes`, recipe trees, scales, and relative levels.


## core/animation-drivers

---
title: Animation Drivers
description: Choose and configure animation drivers for your platform
---

<IntroParagraph>
  Tamagui supports four animation drivers across its platforms. Web supports
  CSS, Reanimated, and Motion. Native supports React Native and Reanimated.
</IntroParagraph>

<SimpleTable
  headers={['Driver', 'Platform', 'Bundle Impact', 'Performance', 'Spring Physics']}
  rows={[
    ['**CSS**', 'Web only', 'Lightest', 'Fast (CSS transitions)', 'Yes (sampled to `linear()`)'],
    [
      '**React Native**',
      'Native only',
      'None',
      'On-thread',
      'Yes (basic)',
    ],
    [
      '**Reanimated**',
      'Web + Native',
      'Larger',
      'Off-thread (native), medium (web)',
      'Yes',
    ],
    ['**Motion**', 'Web only', 'Medium', 'Off-thread (WAAPI)', 'Yes'],
  ]}
/>

You can swap drivers per platform, or dynamically load heavier drivers later in your app. For example, you can start with the lightweight CSS driver on initial load and upgrade to Motion once the user is authenticated.

---

## Using config v6

With [`@tamagui/config/v6`](/docs/core/config-v6), add one animation entry for your platform. The entries share matching keys:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { animations } from '@tamagui/config/animations-css' // or animations-motion, animations-rn, animations-reanimated
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations,
})
```

Every entry ships the same preset table, so `bouncy`, `quick`, and `lazy` mean
the same motion whichever driver you pick. There are no `100ms`-style keys: a
duration is CSS now, so `transition="100ms"` works with nothing configured.

---

## CSS Driver

The lightest bundle size. Springs work here too: they compile to a `linear()`
easing that traces the real spring curve with no JavaScript running. Best for
simple web-only apps.

### Installation

```bash
yarn add @tamagui/animations-css
```

### Configuration

```tsx
import { createAnimations } from '@tamagui/animations-css'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 160, bounce: 0.25 },
    medium: { duration: 300, bounce: 0.15 },
    slow: 'ease-in 450ms',
  }),
  // ...
})
```

An entry is a spring written as `{ duration, bounce }`, or a plain CSS timing
string.

**Supported easing functions:** `ease`, `linear`, `ease-in`, `ease-out`, `ease-in-out`, `cubic-bezier(x1, y1, x2, y2)`

---

## React Native Driver

Uses React Native's built-in Animated API with no extra animation-library bundle.
Use CSS, Motion, or Reanimated on web.

### Installation

```bash
yarn add @tamagui/animations-react-native
```

### Configuration

```tsx
import { createAnimations } from '@tamagui/animations-react-native'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 160, bounce: 0.25 },
    medium: { duration: 300, bounce: 0.15 },
    slow: { duration: 450, bounce: 0.1 },
  }),
  // ...
})
```

**Spring parameters:**

- `duration`: the spring's undamped period in milliseconds, defining how fast it feels
- `bounce`: 0 is critically damped, toward 1 is loose, and negative is sluggish
- `stiffness`, `damping`, and `mass` still work for a config already tuned
  against them

---

## Reanimated Driver

Supports both native and web with advanced features, but has a larger bundle size. Best performance on native platforms with off-thread animations.

### Installation

```bash
yarn add @tamagui/animations-reanimated react-native-reanimated
```

Follow the [Reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/) to complete setup.

### Configuration

```tsx
import { createAnimations } from '@tamagui/animations-reanimated'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 160, bounce: 0.25 },
    medium: { duration: 300, bounce: 0.15 },
    // timing animations also supported
    quick: { type: 'timing', duration: 300, easing: 'ease-out' },
  }),
  // ...
})
```

---

## Motion Driver

Off-thread performance via WAAPI with excellent spring physics and a medium bundle size. Best for web-only apps that need smooth, physics-based animations.

### Installation

```bash
yarn add @tamagui/animations-motion motion
```

### Configuration

```tsx
import { createAnimations } from '@tamagui/animations-motion'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    bouncy: { duration: 400, bounce: 0.5 },
    quick: { duration: 220, bounce: 0.3 },
  }),
  // ...
})
```

Motion uses the Web Animations API (WAAPI) which runs animations on the compositor thread when possible.

---

## Swapping Drivers

Tamagui supports several ways to use different drivers: at build time per platform, at runtime in specific parts of your app, or dynamically loaded after initial render.

### Per-Platform with File Extensions

Use `.native.ts` and `.ts` file extensions to bundle different drivers per platform:

```tsx fileName="animations.ts"
// web
import { createAnimations } from '@tamagui/animations-motion'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

```tsx fileName="animations.native.ts"
// native
import { createAnimations } from '@tamagui/animations-reanimated'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

```tsx fileName="tamagui.config.ts"
import { animations } from './animations'

export default createTamagui({
  animations,
  // ...
})
```

### Dynamic with Configuration

Use the `<Configuration>` component to swap the animation driver for a subtree. This is useful for lazy loading heavier drivers only when needed. For example, you can keep initial page load fast with CSS animations, then upgrade to Motion for authenticated users:

```tsx fileName="app/_layout.tsx"
import { Configuration, Slot } from 'tamagui'
import { createAnimations } from '@tamagui/animations-motion'

const motionDriver = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})

export function AuthenticatedLayout() {
  return (
    <Configuration animationDriver={motionDriver}>
      <Slot />
    </Configuration>
  )
}
```

This pattern works well with route-based code splitting, because the Motion driver is only loaded when the user navigates to an authenticated route.

### Multiple Drivers with animatedBy

Configure multiple drivers at the root and select per-component:

```tsx fileName="tamagui.config.ts"
import { createAnimations as createCSS } from '@tamagui/animations-css'
import { createAnimations as createSpring } from '@tamagui/animations-motion'

export default createTamagui({
  animations: {
    default: createCSS({ bouncy: 'ease-in 200ms' }),
    spring: createSpring({ bouncy: { duration: 400, bounce: 0.5 } }),
  },
})
```

```tsx
<Square transition="bouncy" />                    {/* uses default (CSS) */}
<Square animatedBy="spring" transition="bouncy" /> {/* uses spring (Motion) */}
```

### Runtime Loading with loadAnimationDriver

Add drivers at runtime after app initialization:

```tsx
import { loadAnimationDriver } from 'tamagui'
import { createAnimations } from '@tamagui/animations-motion'

// call this after some condition (user auth, route change, etc.)
const driver = createAnimations({ bouncy: { duration: 400, bounce: 0.5 } })
loadAnimationDriver('spring', driver)

// now components can use animatedBy="spring"
```

---

## See also

- [Animations Overview](/docs/core/animations)
- [AnimatePresence](/docs/core/animate-presence)
- [Config v6](/docs/core/config-v6#animations)


## core/animations-css

---
title: CSS Driver
description: Lightweight CSS transition-based animations
---

<IntroParagraph>
  The `@tamagui/animations-css` package provides lightweight, typed animations
  through CSS transitions on web.
</IntroParagraph>

## Installation

```bash
yarn add @tamagui/animations-css
```

## Configuration

Add it to your [Tamagui config](/docs/core/configuration):

```tsx
import { createAnimations } from '@tamagui/animations-css'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 150, bounce: 0.2 },
    medium: { duration: 300, bounce: 0.15 },
    slow: 'ease-in 450ms',
  }),
  // ...
})
```

The config format is the same for all four drivers, so a name means the same
motion whichever driver renders it. See
[Animations](/docs/core/animations#presets) for the shipped table.

The root entry contains CSS component transitions only. If your app uses
`useAnimatedNumber`, `useAnimatedNumberStyle`, `useAnimatedNumbersStyle`, or
`useAnimatedNumberReaction`, import the same factory from the extras entry:

```tsx
import { createAnimations } from '@tamagui/animations-css/extras'
```

`Sheet` uses animated numbers for its position and `Toast` uses them for swipe
gestures, so apps using either component with the CSS driver need the extras
entry. The root entry keeps apps that only use CSS transitions from shipping
the JavaScript spring and linked-style runtime.

## How it works

At runtime, the plugin does very little except to set the `transition` property
in CSS. At compile-time, the compiler does the same, ensuring you get all the
benefits of prop removal and view flattening even when using animations.

## Animation configuration

A config entry is a spring, written as `{ duration, bounce }`:

```tsx
createAnimations({
  quick: { duration: 220, bounce: 0.3 },
  bouncy: { duration: 400, bounce: 0.5 },
})
```

Springs work under this driver: they compile to a `linear()` easing that traces
the real spring curve, overshoot included, with no JavaScript running.

An entry can also be a plain CSS timing string, in `<easing-function>
<duration>` order or the CSS order:

```tsx
createAnimations({
  quick: 'ease-out 100ms',
  slow: 'ease-in-out 500ms',
})
```

### Delay

```tsx
<Square transition={{ preset: 'quick', delay: 200 }} />
```

The delay (in milliseconds) is applied as CSS `transition-delay`. A CSS
transition string spells it the CSS way, `transition="200ms ease-out 100ms"`.

### Supported easing functions

- `ease`: default easing (equivalent to `cubic-bezier(0.25, 0.1, 0.25, 1)`)
- `linear`: no easing, constant speed
- `ease-in`: slow start
- `ease-out`: slow end
- `ease-in-out`: slow start and end
- `cubic-bezier(x1, y1, x2, y2)`: custom cubic bezier curve

## When to use

**Advantages:**

- **Smallest bundle size**: minimal JavaScript overhead
- **Broad compatibility**: works everywhere CSS works
- **Compiler optimizations**: benefits from static extraction

**Limitations:**

- Springs are sampled into a `linear()` easing up front, so they can't react to
  an interruption mid-flight the way a running JS spring can
- Limited to CSS animatable properties
- Less control over animation lifecycle

## Example

```tsx
import { createAnimations } from '@tamagui/animations-css'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  quick: { duration: 220, bounce: 0.3 },
  bouncy: { duration: 400, bounce: 0.5 },
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="quick"
    scale="hover:1.1"
  />
)
```

## See also

- [Animations Introduction](/docs/core/animations)
- [React Native Driver](/docs/core/animations-react-native)
- [Motion Driver](/docs/core/animations-motion)
- [Reanimated Driver](/docs/core/animations-reanimated)


## core/create-styled-context

---
title: createStyledContext()
description: Share variant props across compound components
---

<IntroParagraph>
  `createStyledContext()` passes variant props through every styled component in
  a compound component tree.
</IntroParagraph>

Compound component APIs let related elements coordinate their props:

```tsx
export default () => (
  <Button size="lg">
    <Button.Text>Lorem ipsum</Button.Text>
  </Button>
)
```

Setting `size="lg"` on the outer Button frame should pass down to the Text so the frame and text sizes stay aligned, without requiring explicit size props on every child component.

`createStyledContext()` provides this coordination for styled components, sharing variant props through React context.

You can set it up as follows:

```tsx
import {
  View,
  Text,
  createStyledContext,
  styled,
  withStaticProperties,
} from '@tamagui/core'

export const ButtonContext = createStyledContext<{
  size?: 'sm' | 'md' | 'lg'
}>({
  size: 'md',
})

export const ButtonFrame = styled(View, {
  displayName: 'Button',
  context: ButtonContext,

  variants: {
    size: {
      sm: { paddingInline: '3', paddingBlock: '1.5' },
      md: { paddingInline: '4', paddingBlock: '2' },
      lg: { paddingInline: '6', paddingBlock: '2' },
    },
  } as const,

  defaultVariants: {
    size: 'md',
  },
})

export const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  context: ButtonContext,

  variants: {
    size: {
      sm: { fontSize: 'sm' },
      md: { fontSize: 'sm' },
      lg: { fontSize: 'base' },
    },
  } as const,
})

export const Button = withStaticProperties(ButtonFrame, {
  Props: ButtonContext.Provider,
  Text: ButtonText,
})
```

A few things to note here:

- ButtonContext should only be typed and given properties that work across both components. Since both define a `size` variant, this works, even though the frame and text read different token scales.
- You can use `<Button.Props size="lg"><Button /></Button.Props>` now to set default props for a Button from above.
- The context pattern currently skips compiler flattening. Avoid using it on low-level primitives like generic Stacks or Text. For higher-level controls like Button, it works well: the compiler still extracts CSS and optimizes render logic.


## core/native

---
title: Native
description: The native style runtime and the integrations that make Tamagui feel native on iOS and Android
---

<IntroParagraph>
  Tamagui renders real native views on iOS and Android, with the same components,
  tokens, and themes you use on web. Nothing extra is required to get started. The
  runtime and integrations below make it faster and more native once you need them.
</IntroParagraph>

Configure Tamagui with the same [provider](/docs/core/configuration) on native
and web.

## Native runtime

The native runtime is in beta. It needs React Native 0.82 or newer with the New
Architecture (Fabric).

By default, a theme change or a style update re-renders the React components that
use it. `@tamagui/native-registry` moves that work into a small C++ registry. It
links eligible native views to the registry and applies theme and style updates
directly through Fabric, so the components don't re-render.

On the iOS uniwind-benchmarks app, Tamagui 3.0.6 rendered 2,003 views in 39.5 ms
and switched themes in 3.5 ms, faster than every other themed library. See the
[benchmarks](/docs/intro/benchmarks#native-uniwind-benchmarks).

Install it along with Nitro Modules, then rebuild your iOS and Android binaries:

```bash
npm install @tamagui/native-registry react-native-nitro-modules
```

Turn on the compiler output in `tamagui.build.ts`:

```ts
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  experimental: {
    nativeFastPath: true,
  },
} satisfies TamaguiBuildOptions
```

Register the style engine once at startup, before your app tree mounts:

```ts
import * as nativeRegistry from '@tamagui/native-registry'
import { setNativeStyleEngine } from 'tamagui'

if (nativeRegistry.isAvailable()) {
  setNativeStyleEngine(nativeRegistry)
}
```

If the native module isn't available on a platform, components render the normal
React way, so the same code is safe everywhere.

## Integrations

`@tamagui/native` connects Tamagui to popular React Native libraries. Each
integration is opt-in: install the library, then import its setup module at your
app entry point, before any Tamagui imports.

```bash
npm install @tamagui/native
```

| Integration                                   | Library                             | What you get                                             |
| --------------------------------------------- | ----------------------------------- | -------------------------------------------------------- |
| [Gesture Handler](#gesture-handler)           | `react-native-gesture-handler`      | Correct nested presses, native Sheet drag and scroll     |
| [Portals](#portals)                           | `react-native-teleport`             | Portaled content that keeps your React context           |
| [Reanimated](#reanimated)                     | `react-native-reanimated`           | Animations on the UI thread                              |
| [Keyboard Controller](#keyboard-controller)   | `react-native-keyboard-controller`  | Sheets that track the keyboard frame by frame            |
| [Safe Area](#safe-area)                       | `react-native-safe-area-context`    | The `safe` style value and safe area aware sheets        |
| [Menus](#menus)                               | `@expo/ui` or `zeego`               | Platform menus and context menus                         |
| [Toast](#toast)                               | `burnt`                             | System toasts and indicators                             |

A typical entry file with several integrations looks like this:

```tsx
// index.js, before any tamagui imports
import '@tamagui/native/setup-gesture-handler'
import '@tamagui/native/setup-teleport'
import '@tamagui/native/setup-keyboard-controller'
import '@tamagui/native/setup-safe-area'
```

In a monorepo, install the native libraries in the app package, since native
modules are linked from there.

### Gesture Handler

With React Native Gesture Handler, `onPress` works the way React Native
`Pressable` does: when pressables are nested, only the innermost one fires. Sheet
also uses it to hand off smoothly between dragging the sheet and scrolling its
content.

```bash
npm install react-native-gesture-handler
```

```tsx
import '@tamagui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* your app */}</GestureHandlerRootView>
  )
}
```

To use it for only one of the two, call `setupGestureHandler` instead:

```tsx
import { setupGestureHandler } from '@tamagui/native/setup-gesture-handler'

// presses only, Sheet keeps its default gestures
setupGestureHandler({ pressEvents: true, sheet: false })
```

With press events enabled, `onPress` calls `stopPropagation()` on web as well, so
nested pressables behave the same on both platforms. Use `onClick` on web when you
want normal DOM bubbling.

#### PressBoundary

Tamagui pressables coordinate with each other automatically. A React Native
`Pressable` or a custom native wrapper doesn't take part in that, so tapping it can
also fire a Tamagui pressable around it. Wrap it in `PressBoundary` to stop that:

```tsx
import { PressBoundary } from '@tamagui/native/gesture-handler'
import { Pressable } from 'react-native'

export function AvatarLink() {
  return (
    <PressBoundary debugName="AvatarLink">
      <Pressable onPress={() => {}}>{/* your content */}</Pressable>
    </PressBoundary>
  )
}
```

`PressBoundary` only affects Tamagui pressables. It doesn't change how React
Native events bubble in general. Native `Menu.Trigger` and `ContextMenu.Trigger`
already do this for you.

### Portals

On native, Tamagui's default portal re-mounts content at the root, which cuts it
off from the React context it was declared in. With `react-native-teleport`,
content inside Sheet, Dialog, Popover, and other portaled components keeps your
contexts, such as navigation and app state.

```bash
npm install react-native-teleport
```

```tsx
import '@tamagui/native/setup-teleport'
```

In a [One](https://onestack.dev) app, One's native portals do the same job without
another native library:

```tsx
import '@tamagui/native/setup-one-portal'
```

Use one of the two setups, not both.

See [Portal](/ui/portal) for details.

### Reanimated

Reanimated runs animations on the UI thread, so they stay smooth while JavaScript
is busy. It plugs in as an animation driver, so it needs no setup import:

```bash
npm install @tamagui/animations-reanimated react-native-reanimated
```

```tsx
import { createAnimations } from '@tamagui/animations-reanimated'
```

See the [Reanimated driver](/docs/core/animations-reanimated) for configuration,
and [animation drivers](/docs/core/animation-drivers) to use it on native with a
lighter driver on web.

### Keyboard Controller

With `react-native-keyboard-controller`, Sheet follows the keyboard frame by frame
as it opens and closes, and dragging the sheet can dismiss the keyboard
interactively.

```bash
npm install react-native-keyboard-controller
```

```tsx
import '@tamagui/native/setup-keyboard-controller'
import { KeyboardProvider } from 'react-native-keyboard-controller'

export default function App() {
  return <KeyboardProvider>{/* your app */}</KeyboardProvider>
}
```

### Safe Area

This setup lets styles use the device safe area insets, and Sheet uses it to stay
clear of the notch and home indicator.

```bash
npm install react-native-safe-area-context
```

```tsx
import '@tamagui/native/setup-safe-area'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { TamaguiProvider } from 'tamagui'

export default function App() {
  return (
    <SafeAreaProvider>
      <TamaguiProvider config={config}>{/* your app */}</TamaguiProvider>
    </SafeAreaProvider>
  )
}
```

`SafeAreaProvider` has to wrap `TamaguiProvider`. Then pass `safe` to any padding
or margin prop, or to `top`, `bottom`, `left`, `right`, and `inset`:

```tsx
<View pt="safe" pb="safe" />
```

On web, `safe` becomes the CSS `env(safe-area-inset-*)` value, so the same code
works in the browser without this setup.

### Menus

`Menu` and `ContextMenu` can render the platform's own menus, with system haptics
and blur, when you pass the `native` prop.

```bash
npm install @expo/ui
```

```tsx
import '@tamagui/native/setup-expo-ui-menu'
```

```tsx
<Menu native>{/* menu content */}</Menu>
```

The Zeego adapter is still available for apps on React Native versions it
supports:

```bash
npm install zeego @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities sf-symbols-typescript
```

```tsx
import '@tamagui/native/setup-zeego'
```

See [Menu](/ui/menu) and [ContextMenu](/ui/context-menu).

### Toast

With `burnt`, toasts use the system UI: SPIndicator on iOS, `ToastAndroid` on
Android, and the Notification API on web.

```bash
npm install burnt
```

```tsx
import '@tamagui/native/setup-burnt'
```

```tsx
<Toast.Provider native>{/* your app */}</Toast.Provider>
```

See [Toast](/ui/toast).



## core/styled

---
title: styled()
description: Extend and build custom and optimizable components
---

<IntroParagraph>
  `styled()` extends a component with base styles and typed variants while
  preserving Tamagui's compiler optimizations.
</IntroParagraph>

For the full list of accepted style properties, see the
[Styles page](/docs/intro/styles).

Start from `View` or `Text` for new components. `styled()` adds base styles and
typed variants, and the compiler still optimizes the result:

```tsx
import { GetProps, styled, View } from '@tamagui/core'

export const RoundedSquare = styled(View, {
  borderRadius: 20,
})

// helper to get props for any TamaguiComponent
export type RoundedSquareProps = GetProps<typeof RoundedSquare>
```

`styled()` wraps any Tamagui component, including the
[HTML elements](/docs/core/html-primitives) such as `html.article`.

Usage:

```tsx
<RoundedSquare x={10} y={10} backgroundColor="red" />
```

You can pass any prop that is supported by the component you are wrapping in styled.

## Variants

With variants:

```tsx
import { type SizeTokens, View, styled } from '@tamagui/core'

export const RoundedSquare = styled(View, {
  borderRadius: 20,

  variants: {
    pin: {
      top: {
        position: 'absolute',
        top: 0,
      },
    },

    centered: {
      true: {
        alignItems: 'center',
        justifyContent: 'center',
      },
    },

    size: styled.dynamic<SizeTokens | number>((size, { tokens }) => ({
      width: tokens.size[size] ?? size,
      height: tokens.size[size] ?? size,
    })),
  } as const,
})
```

<Notice theme="blue">
  Please use `as const` for the variants definition until Typescript gains the ability to
  infer generics as const.
</Notice>

Usage:

```tsx
<RoundedSquare pin="top" centered size="4" />
```

To learn more, [see the docs on variants](/docs/core/variants).

### Non-working React Native views

React Native utility views like Pressable and TouchableOpacity are not supported targets for `styled()`. Their event handling logic conflicts with Tamagui. Tamagui components provide press handling and interaction states internally, or you can render `Pressable` directly when needed.

## Using on the web

The `styled()` function supports Tamagui views, React Native views, and any other React component that accepts a `style` prop. If you wrap an external component that Tamagui doesn't recognize, Tamagui will assume it only supports the `style` prop and not optimize it.

If it does accept `className`, you can opt-in to className, CSS media queries, and compile-time optimization by adding `acceptsClassName`:

```tsx
import { SomeCustomComponent } from 'some-library'
import { styled } from 'tamagui' // or '@tamagui/core'

export const TamaguiCustomComponent = styled(SomeCustomComponent, {
  acceptsClassName: true,
})
```

## render

The `render` prop lets you control which element or component is rendered. It accepts three forms:

### String (HTML element)

Render as a specific HTML element on web while maintaining native View on mobile:

```tsx
const Button = styled(View, {
  render: 'button',
  padding: '4',
  backgroundColor: 'background',
})

const Anchor = styled(Text, {
  render: 'a',
  color: 'blue-500',
})

const Nav = styled(View, {
  render: 'nav',
})
```

This is the recommended approach for semantic HTML and accessibility. String render props are optimized by the Tamagui compiler.

### JSX element

Pass a JSX element to clone with Tamagui's computed props:

```tsx
<View
  render={<a href="/about" target="_blank" />}
  padding="4"
  backgroundColor="background"
>
  About Page
</View>
```

The JSX element's props are merged with Tamagui's computed styles, classNames, and event handlers. This is useful when you need to pass element-specific props like `href` or `target`.

<Notice theme="yellow">
  JSX element render props are not optimized by the compiler and will cause a deopt.
</Notice>

### Function

For full control, pass a render function that receives props and component state:

```tsx
import { TamaguiComponentState } from '@tamagui/core'

<View
  render={(props, state: TamaguiComponentState) => (
    <CustomButton {...props} isHovered={state.hover} isPressed={state.press} />
  )}
  padding="4"
  backgroundColor="hover:blue-200"
>
  Custom Button
</View>
```

The state object includes:

- `hover`: true when hovered (web)
- `press`: true when pressed
- `focus`: true when focused
- `disabled`: true when disabled

<Notice theme="yellow">
  Function render props are not optimized by the compiler and will cause a deopt.
</Notice>

### Runtime override

You can also override the render prop at runtime:

```tsx
const Box = styled(View, {
  padding: '4',
})

// Use as a button
<Box render="button">Click me</Box>

// Use as a link
<Box render="a" href="/about">About</Box>
```

## createStyledHOC

If a functional component that renders a Tamagui-styled component should itself accept `styled()`, wrap it with `createStyledHOC`. Example:

```tsx
// 1. you create a `styled` component as usual:
const StyledText = styled(Text)

// 2. you create a wrapper component that adds some logic
//    but still returns a styled component that receives the props:
const HigherOrderStyledText = (props) => <StyledText {...props} />

// 3. you want that wrapper component itself to be able to use with `styled`:
const StyledHigherOrderStyledText = styled(HigherOrderStyledText, {
  variants: {
    // oops, variants will merge incorrectly
  },
})
```

Without the wrapper, Tamagui resolves the style props before passing them down, so the inner component merges variants differently than you'd expect.

The way to fix this is to wrap your `HigherOrderStyledText` with `createStyledHOC`. You'll also want to forward the ref, which is forwarded for you:

```tsx
const StyledText = styled(Text)

// note the createStyledHOC wrapper here:
const HigherOrderStyledText = createStyledHOC(StyledText, (props, ref) => (
  <StyledText ref={ref} {...props} />
))

const StyledHigherOrderStyledText = styled(HigherOrderStyledText, {
  variants: {
    // variants now merge correctly
  },
})
```

Now your component will handle everything properly, even if a theme is changed on `HigherOrderStyledText`, it will be applied.

Pass all Tamagui style props given to `HigherOrderStyledText` down to a single `StyledText` for everything to work correctly.

And if you'd like to add new props on top of the existing props, annotate the render function's props parameter. The annotated props merge over the wrapped component's props:

```tsx
import { createStyledHOC, View, ViewProps } from '@tamagui/core'

type ExtraProps = {
  someCustomProp: boolean
}

export type CustomProps = ViewProps & ExtraProps

const Custom = createStyledHOC(View, (props: ExtraProps) => {
  // ...
  return null
})
```

---

## Component resolvers (.resolve)

The `.resolve` method attaches a dynamic style resolver to a styled component. It receives the component's complete resolved props and the style environment:

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const AlertBox = styled(View, {
  backgroundColor: 'background',
  padding: '4',

  variants: {
    tone: styled.dynamic<'neutral' | 'critical'>(),
    disabled: {
      true: { opacity: 0.5 },
    },
  } as const,
}).resolve((props, env) => ({
  backgroundColor: props.tone === 'critical' ? env.theme['red-10'] : undefined,
  borderColor: props.tone === 'critical' ? env.theme['red-8'] : undefined,
}))
```

### Complete props and environment

The resolver callback receives two arguments:
1. `props`: the complete styled component prop type, including base props and all declared variants.
2. `env`: an object containing `{ theme, tokens, fonts, font, fontFamily }`.

Because `props` includes the component's full prop types, `.resolve` replaces compound variants and sibling-prop inspection logic.

### Immutable chaining

Calling `.resolve` returns a new component. It never mutates the original component:

```tsx
const Original = styled(View, {})
const Resolved = Original.resolve(() => ({ opacity: 0.5 }))

// Original is unchanged; Resolved has the resolver attached
```

Each styled layer may attach one resolver. When extending a component with `styled()`, child components inherit their parent's resolver chain.

### Parent-first execution

The resolver chain executes in parent-first order. The child resolver runs after its parent resolver and overrides conflicting keys:

```tsx
const Parent = styled(View, {
  variants: {
    tone: styled.dynamic<'neutral' | 'critical'>(),
  },
}).resolve((props, env) => ({
  backgroundColor: props.tone === 'critical' ? env.theme['red-10'] : undefined,
  width: 100,
}))

const Child = styled(Parent, {}).resolve((props) => ({
  width: props.tone === 'critical' ? 200 : undefined,
}))
```

For `<Child tone="critical" />`, `width` is `200` (child resolver wins) and `backgroundColor` is `env.theme['red-10']` (parent resolver lands).

### Precedence tiers

Component resolvers sit at layer 2 in Tamagui's precedence hierarchy:

```
0 base styles < 1 variants < 2 component resolvers < 3 callsite style props < 4 style prop
```

Rules for resolution:
- A resolver beats base styles and variants for the same property.
- A callsite style prop (such as `<AlertBox width={50} />`) beats the resolver.
- The `style` prop beats everything.
- Setting a property to `undefined` in resolver output means absent. The value falls through to lower tiers (variants or base styles).

### Static shape rule

For compiler extraction, write resolver return objects with static keys and scalar expressions. Return `undefined` for inactive branches instead of spreading objects into the return literal:

```tsx
// good: static keys, undefined for inactive branch
const Box = styled(View, {
  variants: {
    tone: styled.dynamic<'neutral' | 'critical'>(),
  },
}).resolve((props, env) => ({
  backgroundColor: props.tone === 'critical' ? env.theme['red-10'] : undefined,
  opacity: props.disabled ? 0.5 : undefined,
}))

// avoid: spreads and computed keys deopt compiler extraction
const DeoptBox = styled(View, {
  variants: {
    tone: styled.dynamic<'neutral' | 'critical'>(),
  },
}).resolve((props) => ({
  ...(props.tone === 'critical' && { backgroundColor: 'red' }),
}))
```


## core/animations-motion

---
title: Motion Driver
description: High-performance web animations with WAAPI
---

<IntroParagraph>
  [Motion](https://motion.dev) combines JavaScript animation controls with the
  Web Animations API for smooth, browser-native animation.
</IntroParagraph>

## Installation

```bash
yarn add @tamagui/animations-motion motion
```

## Configuration

Add your animations to your [Tamagui config](/docs/core/configuration):

```tsx
import { createAnimations } from '@tamagui/animations-motion'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    quick: { duration: 220, bounce: 0.3 },
    bouncy: { duration: 400, bounce: 0.5 },
    superBouncy: { duration: 400, bounce: 0.75 },
  }),
  // ...
})
```

The config format is the same for all four drivers, so a name means the same
motion whichever driver renders it. There is no need for `'200ms'`-style entries
any more: a duration is CSS, so `transition="200ms"` works with nothing
configured.

## How it works

At runtime, the Motion driver uses the `useAnimate()` hook from the Motion
library to batch style changes and animate only what changed. It runs through
the Web Animations API (WAAPI), which animates on the compositor thread when
possible, keeping animations smooth even when the main thread is busy.

## Animation configuration

Motion animations support both spring and timing animations:

### Spring animations

```tsx
{
  duration: 400,  // the spring's undamped period, in milliseconds
  bounce: 0.5,    // 0 is critically damped, toward 1 is loose, negative is sluggish
}
```

`stiffness`, `damping`, and `mass` still work for a config already tuned against
them, and `velocity`, `overshootClamping`, and the rest thresholds pass through.

### Timing animations

```tsx
{
  type: 'timing',
  duration: 200,      // Duration in milliseconds
  easing: 'ease-out', // any css timing function
}
```

A plain CSS string means the same thing: `'200ms ease-out'`.

### Delay

```tsx
<Square transition={{ preset: 'bouncy', delay: 200 }} />
```

The delay is specified in milliseconds and is converted to seconds for Motion
internally.

## Highlights

### Zero re-renders

The Motion driver bypasses internal style recalculations and hands off updates directly to Motion.

### WAAPI performance

Off-thread performance comparable to Reanimated, but for web-only applications.

## Platform-specific configuration

For cross-platform apps, use Motion on web and Reanimated on native:

```tsx
// animations.ts (web)
import { createAnimations } from '@tamagui/animations-motion'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

```tsx
// animations.native.ts
import { createAnimations } from '@tamagui/animations-reanimated'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

Then import without the extension:

```tsx
import { animations } from './animations'
```

Your bundler will automatically pick the right file based on the platform.

## See also

- [Animations Introduction](/docs/core/animations)
- [CSS Driver](/docs/core/animations-css)
- [React Native Driver](/docs/core/animations-react-native)
- [Reanimated Driver](/docs/core/animations-reanimated)
- [Motion Documentation](https://motion.dev)


## core/tokens

---
title: Tokens
description: Named design values for space, size, radius, color, and z-index
---

<IntroParagraph>
  Tokens give style props typed names for shared design values such as space,
  size, radius, color, and z-index.
</IntroParagraph>

Create them with `createTokens`, then pass them to `createTamagui` as part of
the [configuration](/docs/core/configuration) object.

## Getting tokens

For example, if you define some tokens:

```tsx
const tokens = createTokens({
  size: {
    small: 10,
  },
})
```

After you pass that into `createTamagui`, you can access your tokens from anywhere using `getTokens`:

```tsx
import { getTokens } from '@tamagui/core'

getTokens().size.small
```

or

```tsx
getTokens().size['small']
```

`getTokens` takes no options in v3. Tokens are keyed by their unprefixed name,
so `size.small` is the only spelling you need. The `prefixed` option that used to
return a `$`-keyed copy is removed.

`getTokens()` returns `Variable` objects, which Tamagui uses to manage values and CSS variable names:

```tsx
getTokens().size.small.val // returns 10
getTokens().size.small.variable // returns something like (--size-small), which matches the CSS rule inserted
```

Tamagui has some helpers that make working with variables easier, which are documented in [Exports](/docs/core/exports), namely [`getVariable`](/docs/core/exports#getvariable) which will return the CSS variable on web, but raw value on native, and `getVariableValue` which always returns the raw value.

## v3 token behavior

The default v3 configs do not export `true` token keys. Component defaults still
resolve to the default size, and that default size is `4`.

```tsx
// before v3
<Button size="$true" />

// v3
<Button size="4" />
```

`@tamagui/get-token` also no longer performs runtime token stepping. `getSize`,
`getSpace`, and `getRadius` resolve the same key you pass in. The old
`stepTokenUpOrDown`, `getTokenRelative`, and options such as `shift`, `bounds`,
and `excludeHalfSteps` are removed.

```tsx
// before v3
const padding = getSize(size, { shift: -2 })

// v3
const padding = getVariableValue(getSize(size)) * 0.6
```

If you need a smaller or larger named token, choose that token explicitly. If
you need proportional sizing, multiply the resolved numeric value.

### Color tokens as fallback values for themes

Color tokens are available as fallback values when you access a theme. So when you `useTheme()` and then access a value that isn't in the theme, it will check for a `tokens.color` with the matching name.

Think of it this way:

- Tokens are static and are your base values.
- Themes are dynamic, they can change in your React tree, and live above tokens.

You can skip themes at first and build with style props and tokens alone, adding `light` and `dark` themes only when you need them. Avoid nested themes until you need them.

## Using tokens with components

When using `styled` or any Tamagui component like `View`, you can access tokens directly. Just like with `useTheme`, it will first look for a theme value that matches, and if not it will fall back to a token.

Tokens apply automatically to matching properties. `size` tokens apply to width and height, `radius` to borderRadius:

<PropsTable
  title="How tokens apply to attributes"
  data={[
    {
      name: 'Size',
      description: 'width, height, minWidth, minHeight, maxWidth, maxHeight',
    },
    {
      name: 'zIndex',
      description: 'zIndex',
    },
    {
      name: 'Radius',
      description:
        'borderRadius, borderTopLeftRadius, borderTopRightRadius, borderBottomLeftRadius, borderBottomRightRadius',
    },
    {
      name: 'Color',
      description:
        'color, backgroundColor, borderColor, borderBottomColor, borderTopColor, borderLeftColor, borderRightColor',
    },
    {
      name: 'Space',
      description: 'All properties not matched by the above.',
    },
  ]}
/>

## Specific tokens

You can also define custom token categories of your own:

```tsx
const tokens = createTokens({
  // ...other tokens
  icon: {
    small: 16,
    medium: 24,
    large: 32,
  },
})
```

And then access them using the "specific tokens" syntax:

```tsx
export default () => (
  <html.div
    // access with the category first:
    width="icon.small"
  />
)
```

This, like all token values, works the same with `styled`:

```tsx
import { styled, View } from '@tamagui/core'

export const MyView = styled(View, {
  width: 'icon.small',
})
```

When creating custom tokens, you can use the `px` helper to ensure values get proper pixel units on web while remaining as raw numbers on native:

```tsx
import { createTokens, px } from '@tamagui/core'

const tokens = createTokens({
  customSize: {
    small: px(100), // → "100px" on web, 100 on native
    medium: px(200),
    large: px(300),
  },
  opacity: {
    low: 0.25, // → 0.25 (unitless on both platforms)
    medium: 0.5,
    high: 0.75,
  },
})
```

The predefined token categories like `size`, `space`, and `radius` automatically add
pixel units where appropriate, so you don't need to use the `px` helper for them.


## core/use-media

---
title: useMedia
description: Respond to different screen sizes
---

<IntroParagraph>
  `useMedia` reads the same named media rules that style props use for
  responsive conditions.
</IntroParagraph>

Define those rules in the media object of your `tamagui.config.ts`:

```tsx line=2-6
export default createTamagui({
  media: {
    xs: { maxWidth: 660 },
    gtXs: { minWidth: 660 + 1 },
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    md: { maxWidth: 980 },
    gtMd: { minWidth: 980 + 1 },
    lg: { maxWidth: 1120 },
    gtLg: { minWidth: 1120 + 1 },
    short: { maxHeight: 820 },
    tall: { minHeight: 820 },
    hoverNone: { hover: 'none' },
    touch: { pointer: 'coarse' },
  },
})
```

Name them as you like. We use `sm`, `md`, `lg`, and `gtSm`, where `gt` means
"greater than".

Order matters: items defined further down override items before them. Here
`xs` is the weakest and each entry overrides the ones above it.

Tamagui converts each entry to a media query, turning camelCase into
hyphen-case and wrapping it in `@media()`.

### Inline props

Use media names as typed object keys or string modifiers on the style prop:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
import { useState } from 'react'
import { Button, XStack } from 'tamagui' // note: design system can use @tamagui/core

export default () => {
  const [x, setX] = useState(0)
  return (
    <XStack
      backgroundColor={{
        default: 'red',
        gtSm: 'blue',
        gtMd: x > 0.5 ? 'green' : 'yellow',
      }}
    >
      <Button onPress={() => setX(Math.random())}>Hello</Button>
    </XStack>
  )
}
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
import { useState } from 'react'
import { Button, XStack } from 'tamagui' // note: design system can use @tamagui/core

export default () => {
  const [x, setX] = useState(0)
  return (
    <XStack
      backgroundColor={`red gtSm:blue gtMd:${x > 0.5 ? 'green' : 'yellow'}`}
    >
      <Button onPress={() => setX(Math.random())}>Hello</Button>
    </XStack>
  )
}
```

</MDXTabs.Content>
</MDXTabs>

In this example we are doing mobile-first design, where clauses override the base as the viewport gets wider. The ternary payload in `gtMd:` is extractable with Tamagui and still outputs simple CSS.

### Hooks

```tsx
import { Button, XStack, useMedia } from 'tamagui' // note: design system can use @tamagui/core

export default () => {
  const media = useMedia()

  return (
    <XStack
      // can be used as a ternary
      backgroundColor={media.sm ? 'red' : 'blue'}
      // can be used as a spread
      {...(media.lg && {
        x: 10,
        y: 10,
      })}
    >
      <Button>Hello</Button>
    </XStack>
  )
}
```

As long as **all** of your usages of useMedia are extractable, Tamagui will actually generate your CSS and then fully remove the hook from the output code. You can check this by adding `// debug` to the top of your component.

You can also use `useMedia` for logic outside of styles. If an expression
cannot be extracted, Tamagui falls back to runtime execution.

Tamagui tracks which keys are accessed, and only updates if the media query matching that key changes.

#### Limitations

The `useMedia` hook uses proxies so it can track which keys you are accessing and only re-render components that need re-rendering based on those keys. The Tamagui compiler also understands straightforward uses of the hook during compile-time and can remove it entirely when targeting the web, in favor of CSS.

- The proxied object returned by `useMedia` is not iterable, and does not support `in` checks or `Object.keys`.
- Write `const media = useMedia()` and access keys directly, like `media.sm`, for best results with the compiler. The compiler supports destructuring without renaming.


## core/server-rendering

---
title: Server Rendering
description: Advanced SSR, hydration, and client-only rendering in Tamagui
---

<IntroParagraph>
  Tamagui renders responsive styles and animation state on the server so the
  first client frame can hydrate without flickering.
</IntroParagraph>

## How it works

Tamagui renders in three phases:

1. **Server**: Renders with proper CSS media queries for everything, including components using spring animation drivers (which normally require hard-coded values)
2. **Client (first render)**: Renders with CSS to match the server output perfectly
3. **Client (after hydration)**: Seamlessly swaps to springs and animations

Hydration matches the server output without flickering, even for responsive layouts with animations.

## Opting out

You can opt out of SSR entirely or for specific parts of your app.

### Wholesale: disableSSR

For single-page applications that don't need SSR, disable it entirely in your config:

```tsx
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  // ... other config
  settings: {
    disableSSR: true, // Automatically wraps app with <ClientOnly enabled>
  },
})
```

When `disableSSR` is true:

- Media queries immediately use actual values
- No double render occurs
- Your entire app is wrapped with `<ClientOnly enabled>`

### Partial: ClientOnly component

For fine-grained control, wrap specific parts of your tree:

```tsx
import { ClientOnly } from '@tamagui/use-did-finish-ssr'

function MyComponent() {
  return (
    <YStack>
      {/* Server-rendered for SEO */}
      <ProductInfo />

      {/* Client-only for complex interactions */}
      <ClientOnly enabled>
        <InteractiveChart />
      </ClientOnly>
    </YStack>
  )
}
```

## Configuration component

The `Configuration` component is essentially a shorthand for `ClientOnly`. It accepts [configuration settings](/docs/core/configuration) like `disableSSR`:

```tsx
import { Configuration } from 'tamagui'

function MyApp() {
  return (
    <Configuration disableSSR>
      {/* Everything here renders client-only */}
      <ComplexComponent />
    </Configuration>
  )
}
```

## useMedia and SSR

The `useMedia` hook automatically leverages Tamagui's smart SSR rendering. During server render, it returns appropriate defaults that match CSS media queries, then updates after hydration without flickering.

```tsx
import { useMedia } from 'tamagui'

function ResponsiveComponent() {
  const media = useMedia() // Automatically handles SSR correctly

  return media.gtSm ? <DesktopView /> : <MobileView />
}
```

## SSR hooks

### useDidFinishSSR

Returns `true` when hydration is complete:

```tsx
import { useDidFinishSSR } from '@tamagui/use-did-finish-ssr'

function MyComponent() {
  const isClient = useDidFinishSSR()

  return isClient ? <BrowserFeature /> : <Placeholder />
}
```

**Behavior:**

- Server/before hydration: `false`
- After hydration: `true`
- Inside `<ClientOnly enabled>`: always `true`

### useIsClientOnly

Checks if you're in a client-only context:

```tsx
import { useIsClientOnly } from '@tamagui/use-did-finish-ssr'

function MyComponent() {
  const isClientOnly = useIsClientOnly()

  if (isClientOnly) {
    // Safe to use browser APIs
    return <ComponentWithBrowserAPIs />
  }

  return <SSRSafeComponent />
}
```

### useClientValue

Returns `undefined` during SSR, your value after hydration:

```tsx
import { useClientValue } from '@tamagui/use-did-finish-ssr'

function WindowInfo() {
  const width = useClientValue(() => window.innerWidth)

  return <html.span>{width ? `${width}px` : 'Loading...'}</html.span>
}
```

## Best practices

### When to use disableSSR

**Use it for:**

- Single-page applications
- Client-only web apps
- Maximum performance without SSR overhead

**Avoid for:**

- SEO-critical content
- Server-rendered frameworks (Next.js SSR/SSG)
- Fast initial page loads

### When to use ClientOnly

**Use it for:**

- Expensive client-only components (charts, editors)
- Browser API dependencies
- Non-critical UI that can load after initial render

**Example:**

```tsx
function ProductPage({ product }) {
  return (
    <YStack>
      {/* SEO-critical content */}
      <ProductHeader product={product} />

      {/* Defer complex UI */}
      <ClientOnly enabled>
        <InteractiveGallery />
      </ClientOnly>
    </YStack>
  )
}
```

### When to use hooks

- `useDidFinishSSR`: Conditional rendering based on hydration state
- `useIsClientOnly`: Checking client-only context for browser APIs
- `useClientValue`: Shorthand for client-only values

## Package reference

```tsx
import {
  ClientOnly, // Component for client-only subtrees
  useDidFinishSSR, // Hook for hydration state
  useIsClientOnly, // Hook for client-only context
  useClientValue, // Hook for client-only values
} from '@tamagui/use-did-finish-ssr'
```

## See also

- [Configuration](/docs/core/configuration): learn more about settings
- [useMedia](/docs/core/use-media): responsive media queries
- [Themes](/docs/intro/themes): theme system and context


## core/animations-react-native

---
title: React Native Driver
description: Spring-based animations using React Native Animated
---

<IntroParagraph>
  This native-only driver connects Tamagui to [React Native's Animated
  library](https://reactnative.dev/docs/animated).
</IntroParagraph>

Web applications should use the CSS, Motion, or Reanimated driver.

## Installation

```bash
yarn add @tamagui/animations-react-native
```

## Configuration

Add it to your [Tamagui config](/docs/core/configuration):

```tsx
import { createAnimations } from '@tamagui/animations-react-native'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 160, bounce: 0.25 },
    medium: { duration: 300, bounce: 0.15 },
    slow: { duration: 450, bounce: 0.1 },
  }),
  // ...
})
```

The config format is the same for all four drivers, so a name means the same
motion whichever driver renders it.

## Animation configuration

React Native animations are springs, written as a duration and a bounce:

### Spring parameters

- **`duration`**: the spring's undamped period in milliseconds, defining how fast the animation feels. It is not a fixed cutoff: a bouncy spring continues oscillating past it.
- **`bounce`**: 0 is critically damped, values toward 1 oscillate, and negative values produce an overdamped spring.

```tsx
createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
  quick: { duration: 220, bounce: 0.3 },
})
```

`stiffness`, `damping`, and `mass` still work for a config already tuned against
them, and `velocity`, `overshootClamping`, and the rest thresholds pass through
to `Animated.spring`.

### Delay

```tsx
<Square transition={{ preset: 'bouncy', delay: 200 }} />
```

The delay is specified in milliseconds and uses `Animated.delay()` internally to
sequence animations.

## When to use

**Advantages on native:**

- **Built-in**: no additional external animation library needed
- **Spring physics**: natural, physics-based motion
- **Reliable**: uses core React Native Animated

**Limitations:**

- Less advanced than Reanimated
- Not available on web

## Platform-specific configuration

You can use different drivers on web vs native using platform-specific file
extensions:

```tsx
// animations.ts (web)
import { createAnimations } from '@tamagui/animations-css'

export const animations = createAnimations({
  quick: { duration: 220, bounce: 0.3 },
})
```

```tsx
// animations.native.ts (native)
import { createAnimations } from '@tamagui/animations-react-native'

export const animations = createAnimations({
  quick: { duration: 220, bounce: 0.3 },
})
```

Then import without the extension:

```tsx
import { animations } from './animations'
```

Your bundler will automatically pick the right file based on the platform.

## Example

```tsx
import { createAnimations } from '@tamagui/animations-react-native'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
  quick: { duration: 220, bounce: 0.3 },
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="bouncy"
    opacity="enter:0"
    scale="enter:0.9"
  />
)
```

## See also

- [Animations Introduction](/docs/core/animations)
- [CSS Driver](/docs/core/animations-css)
- [Motion Driver](/docs/core/animations-motion)
- [Reanimated Driver](/docs/core/animations-reanimated)


## core/fonts

---
title: Fonts
description: Define font families with createFont and load custom fonts on native.
---

<IntroParagraph>
  Fonts are the one token category with structure. Each family carries its own
  size, line height, weight, and letter spacing scales.
</IntroParagraph>

Create one with `createFont` and pass it to `createTamagui` under `fonts`:

```tsx fileName="tamagui.config.ts"
import { createFont, createTamagui, isWeb } from 'tamagui'

const interFont = createFont({
  family: isWeb ? 'Inter, Helvetica, Arial, sans-serif' : 'Inter',
  size: {
    1: 12,
    2: 14,
    3: 15,
    // ...
  },
  lineHeight: {
    1: 17,
    2: 22,
    3: 25,
    // ...
  },
  weight: {
    4: '300',
    6: '600',
  },
  letterSpacing: {
    4: 0,
    8: -1,
  },

  // android needs the weight mapped to the font file's family name
  // find it with: otfinfo --family Inter.ttf
  face: {
    400: { normal: 'Inter', italic: 'Inter-Italic' },
    500: { normal: 'InterBold', italic: 'InterBold-Italic' },
  },
})

export const config = createTamagui({
  fonts: {
    heading: interFont,
    body: interFont,
  },
  // ...
})
```

Keys can be any string. The `tamagui` components expect number keys `1` through `10`
on `size`, so [headings](/ui/headings) and sized text resolve automatically.

`createFont` fills gaps for you. When `lineHeight`, `weight`, or `letterSpacing`
define fewer keys than `size`, each missing key carries the previous value forward,
and keys before the first one you define take that first value:

```tsx
const systemFont = createFont({
  family: isWeb ? 'Helvetica, Arial, sans-serif' : 'System',
  size: { 1: 12, 2: 14, 3: 15 },
  lineHeight: { 2: 22 }, // 1 becomes 22
  weight: { 1: '300', 3: '600' }, // 2 becomes 300
  letterSpacing: { 1: 0, 2: -1 }, // 3 becomes -1
})
```

Set `settings.defaultFont` to the key of the family that text should use when no
`fontFamily` is given. See [Settings](/docs/core/settings).

## Face

On Android, React Native picks a font file by name and ignores `fontWeight`. The
`face` map tells Tamagui which file name to use for each weight and style. Without
it, every weight renders with the same file. iOS and web ignore `face`.

## Loading fonts on native

React Native has to load custom font files before it can use them. Tamagui does not
handle loading. With Expo, use `useFonts` from `expo-font` and gate rendering on the
result. The [Expo guide](/docs/guides/expo#loading-fonts) walks through both
`@tamagui/font-inter` and `@expo-google-fonts`. Without Expo, follow the React Native
docs for linking font assets.

The name you load must match the name used in `family` and in `face`:

```tsx fileName="App.tsx"
import { useFonts } from 'expo-font'

function App() {
  const [loaded] = useFonts({
    Inter: require('@tamagui/font-inter/otf/Inter-Medium.otf'),
    InterBold: require('@tamagui/font-inter/otf/Inter-Bold.otf'),
  })

  if (!loaded) {
    return null
  }

  return <MyApp />
}
```

## Using font tokens

Text components read a family with `fontFamily`. Style props such as `fontSize`
and `lineHeight` accept a key from that family's scale. `SizableText`, `Paragraph`,
and the headings take a `size` prop that picks `fontSize`, `lineHeight`, `weight`,
and `letterSpacing` from the family together:

```tsx
<Text fontFamily="body" fontSize="3" lineHeight="3">
  Hello world
</Text>

<SizableText fontFamily="heading" size="3">
  Hello world
</SizableText>
```

## Per-language fonts

A font name with a `_` suffix is a language variant of the base family. Define
`body_cn` next to `body` and load both font files:

```tsx
import { createFont, createTamagui } from 'tamagui'

export default createTamagui({
  fonts: {
    body: createFont({
      family: 'Inter, Helvetica, Arial, sans-serif',
      // ...
    }),
    body_cn: createFont({
      family: 'Inter-CN',
      // ...
    }),
  },
})
```

`FontLanguage` then switches a family for a whole subtree. Every component
reading `fontFamily="body"` inside it picks up the variant, with no prop
changes on the text itself:

```tsx
import { FontLanguage, html } from 'tamagui'

export default () => (
  <FontLanguage body="cn">
    <html.span fontFamily="body">你好</html.span>
  </FontLanguage>
)
```

The suffix name is yours to choose. The reserved value `default` resets a
family to its base font:

```tsx
<FontLanguage body="cn">
  <html.span fontFamily="body">你好</html.span>
  <FontLanguage body="default">
    <html.span fontFamily="body">Hello</html.span>
  </FontLanguage>
</FontLanguage>
```

On web, `FontLanguage` swaps a CSS variable, so changing language does not
re-render the text.


## core/variants

---
title: Variants
description: Simple typed prop styles through styled()
---

<IntroParagraph>
  Variants turn a small set of typed component props into reusable groups of
  styles.
</IntroParagraph>

Variants expand a single prop into a group of styles. Example:

```tsx
import { type SizeTokens, View, styled } from 'tamagui' // or '@tamagui/core'

export const Circle = styled(View, {
  borderRadius: 100_000_000,

  variants: {
    pin: {
      top: {
        position: 'absolute',
        top: 0,
      },
    },

    centered: {
      true: {
        alignItems: 'center',
        justifyContent: 'center',
      },
    },

    size: styled.dynamic<SizeTokens | number>((size, { tokens }) => ({
      width: tokens.size[size] ?? size,
      height: tokens.size[size] ?? size,
    })),
  } as const,
})
```

<Notice theme="blue">
  Notice the `as const` on the variant definition object. This is necessary to please
  TypeScript until it gains the ability to infer constant objects. If left out, your types
  may break.
</Notice>

Usage:

```tsx
<Circle pin="top" centered size="4" />
```

This component uses a few different types of variants, expanded on below.

## Why variants?

Sharing plain style objects means typing props by hand and gluing them together
with arbitrary logic inside a functional component. The types may not map to
the actual output, and a compiler cannot optimize what it cannot see.

Variants force you out of the React render function, which means no hooks and a
much clearer contract: a dynamic takes one value and the style environment, and
outputs a statically-shaped group of styles. Sibling-prop logic belongs in a
component `.resolve` callback.

Because variants work with the styled function, they nest without adding depth
to your render tree. `styled(styled())` is a single React component that the
compiler can optimize and flatten.

## Variants

### Typed variants

#### `true` or `false`

The special keys `true` and `false` will map to a boolean. So the `centered`
prop will be typed to accept true or false, and when true it will apply its
styles.

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const MyView = styled(View, {
  variants: {
    selectable: {
      true: {
        userSelect: 'auto',
      },
      false: {
        userSelect: 'none',
      },
    },
  } as const,
})
```

#### String, boolean, and number domains

For an open-ended value domain, declare the prop type on `styled.dynamic`.
There is no runtime type-key lookup:

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const ColorfulView = styled(View, {
  variants: {
    color: styled.dynamic<string>((color) => ({
      color,
      borderColor: color,
    })),
  } as const,
})
```

Use an exact-key object when the domain is finite, or one dynamic when it is
parametric. A key such as `string`, `number`, or `Size` is otherwise just an
exact literal key.

### Dynamic token variants

When you write variants, you have to be explicit so TypeScript and the runtime
know exactly which props you accept. This can be especially cumbersome when you
want to "gather" all the values of a specific token scale. For example, without
a dynamic, if you wanted to have a `pad` property that accepted all the
keys from `tokens.size`, you'd have to write this:

```tsx
// in your tamagui.config.ts:
const tokens = createTokens({
  size: {
    sm: 10,
    md: 15,
    lg: 25,
    // ...
  }
  // ... see configuration docs for required tokens
})

export default createTamagui({
  tokens
})

// somewhere in your app:
const MyButton = styled(View, {
  variants: {
    pad: {
      sm: {
        padding: tokens.size.sm,
      },
      md: {
        padding: tokens.size.md,
      },
      lg: {
        padding: tokens.size.lg,
      },
      // ...
    }
  } as const
})

// now you can
<MyButton pad="lg" />
```

This is verbose, and every token change means updating every component. With a
dynamic instead:

```tsx
// in your tamagui.config.ts:
const tokens = createTokens({
  size: {
    sm: 10,
    md: 15,
    lg: 25,
    // ...
  }
  // ... see configuration docs for required tokens
})

export default createTamagui({
  tokens
})

// somewhere in your app:
const MyButton = styled(View, {
  variants: {
    pad: styled.dynamic<SizeTokens>((val, { tokens }) => ({
      padding: tokens.size[val]
    }))
  } as const
})

// now you can
<MyButton pad="lg" />
```

Dynamic variants save you from hardcoding every token key. The generic
parameter is the accepted prop type, so one callback can cover a token scale,
raw values, or a union without runtime type-key matching:

```tsx
const Square = styled(View, {
  variants: {
    size: styled.dynamic<SizeTokens | number>((val, { tokens }) => {
      const value = tokens.size[val] ?? val
      return { width: value, height: value }
    }),
  } as const,
})

// both work:
<Square size="4" />
<Square size={100} />
```

#### Environment passed to dynamic variants

The second argument contains the current tokens, theme, and fonts. It never
contains component props. Use `.resolve((props, env) => ...)` when styles depend
on sibling props.

```tsx
const SizableText = styled(Text, {
  variants: {
    size: styled.dynamic<SizeTokens>((size, { tokens, font }) => ({
      fontSize: font?.size[size],
      lineHeight: font?.lineHeight[size],
      height: tokens.size[size] ?? size,
    })),
  } as const,
})
```

Usage:

```tsx
<SizableText size="4">Hello world</SizableText>
```

The second argument is always
`{ theme, tokens, fonts, font, fontFamily }`.

<PropsTable
  data={[
    {
      name: 'theme',
      type: 'ThemeParsed',
      description: `A proxy to your theme that lets you access active theme values using normal keys.`,
    },
    {
      name: 'tokens',
      type: 'TokensParsed',
      description: `All tokens parsed from your configuration, accessible with bare keys (e.g. tokens.size[val]).`,
    },
    {
      name: 'font',
      type: 'Font',
      description: `Maybe undefined. A single resolved Font object from your font configuration.`,
    },
    {
      name: 'fontFamily',
      type: 'string',
      description: `Maybe undefined. The name of the current fontFamily.`,
    },
    {
      name: 'fonts',
      type: 'GenericFonts',
      description: `All fonts parsed from your configuration.`,
    },
  ]}
/>

#### Bare dynamic declarations

When variant styles depend on sibling props, declare the prop type with bare `styled.dynamic<T>()` and apply the styles in a component `.resolve` callback:

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const AlertBox = styled(View, {
  variants: {
    tone: styled.dynamic<'neutral' | 'critical'>(),
  },
}).resolve((props, env) => ({
  backgroundColor: props.tone === 'critical' ? env.theme['red-10'] : undefined,
  opacity: props.disabled ? 0.5 : undefined,
}))
```

Bare dynamic variants declare the accepted prop type and mark the prop as consumed. It is not forwarded to the underlying DOM element or native view.

#### Dynamic value domains

Use the dynamic's generic parameter to declare the whole accepted domain, then
branch on the value inside the callback when needed:

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const ColorfulView = styled(View, {
  variants: {
    colorful: styled.dynamic<true | string>((val) => ({
      color: val === true ? 'red' : val,
    })),
  } as const,
})
```

#### Dynamic variants

If you need more complex types, use `styled.dynamic` to brand the value-to-style
function and declare the prop type:

```tsx
import { View, styled } from 'tamagui' // or '@tamagui/core'

export const MyView = styled(View, {
  variants: {
    doubleMargin: styled.dynamic<number>((val) => ({
      margin: val * 2,
    })),
  } as const,
})
```

The callback is invoked once per active flat-clause payload, so responsive and
stateful values keep the same behavior as exact variants.

### defaultVariants

Sometimes you'd like to set a default value for a variant you've just set on
your styled() component. Due to the way Typescript types parse from left to
right, we can't properly type variants directly on the object you define them
on.

The `defaultVariants` option allows you to set these, properly typed:

```tsx
const Square = styled(View, {
  variants: {
    size: styled.dynamic<SizeTokens>((size, { tokens }) => ({
      // size === 'lg'
      // tokens.size.lg === 25
      width: tokens.size[size] ?? size,
      height: tokens.size[size] ?? size,
    })),
  } as const,

  // <Square /> will get size '10' from size tokens automatically
  defaultVariants: {
    size: '10',
  },
})
```

### Variants and flat clauses

Variant branches can use the same state and media clauses as any other style value,
in string or object form:

```tsx
const SizedText = styled(Text, {
  variants: {
    size: {
      sm: { fontSize: 'sm' },
      md: {
        fontSize: 'sm md:base xl:lg',
        // equivalent:
        // fontSize: { default: 'sm', md: 'base', xl: 'lg' },
      },
    },
  } as const,
})
```

The variant prop itself accepts conditions too, so a variant can change per
state or breakpoint:

```tsx
<SizedText size="sm md:md" />
<SizedText size={{ default: 'sm', md: 'md' }} />
```

### Variants and parent variants

Styled components can access their parent components variants, even in their
variants:

```tsx
const ColorfulText = styled(Text, {
  variants: {
    colored: {
      true: {
        color: 'color',
      },
    },

    large: {
      true: {
        fontSize: '8',
      },
    },
  } as const,
})

const MyParagraph = styled(ColorfulText, {
  colored: true,

  variants: {
    hero: {
      true: {
        large: true,
      },
    },
  } as const,
})
```


## core/cli

---
title: Tamagui CLI
description: Command-line tools for building, checking, and managing Tamagui projects
---

<IntroParagraph>
  The Tamagui CLI provides a suite of command-line tools for optimizing components,
  managing dependencies, adding fonts and icons, and more.
</IntroParagraph>

**Just starting out?** Skim this section, the CLI is not necessary to get going.

## Installation

Install the CLI as a development dependency:

```bash
yarn add -D @tamagui/cli
```

## Commands

### build

Pre-compile Tamagui components in-place for production builds. This is useful
for bundlers that don't have a Tamagui plugin yet (like Turbopack) or when you
want a simple setup that works with any bundler.

```bash
# Build all components in a directory (web + native by default)
npx tamagui build ./src

# Build for web only
npx tamagui build --target web ./src

# Build for native only
npx tamagui build --target native ./src

# Build a specific file
npx tamagui build ./src/components/MyComponent.tsx

# Include/exclude patterns
npx tamagui build --include "components/**" --exclude "**/*.test.tsx" ./src

# Output to a separate directory (source files unchanged)
npx tamagui build --output ./dist ./src

# Create platform-specific files next to source files (.web.tsx or .native.tsx)
npx tamagui build --target native --output-around ./src

# Preview changes without writing files
npx tamagui build --dry-run ./src
```

**Flags:**

- `--target <platform>`: Target platform: `web`, `native`, or `both` (default: `both`)
- `--include <pattern>`: Glob pattern to include files
- `--exclude <pattern>`: Glob pattern to exclude files
- `--output <path>`: Output directory for optimized files (preserves directory structure). When specified, source files are not modified
- `--output-around`: Create platform-specific files (`.web.tsx` or `.native.tsx`) next to source files instead of modifying them. Errors if the file already exists
- `--expect-optimizations <number>`: Fail if fewer than this many components are optimized (useful for CI)
- `--dry-run`: Preview what would be optimized without writing any files
- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

**Platform-Specific File Handling:**

The CLI automatically handles platform-specific files:

- Files with `.web.tsx` or `.ios.tsx` extensions are optimized for web only
- Files with `.native.tsx` or `.android.tsx` extensions are optimized for native
  only
- Base files (`.tsx`) without platform-specific versions are optimized for all
  platforms
- If both `.web.tsx` and `.native.tsx` exist, the base `.tsx` file is skipped

**Configuration:**

Create a `tamagui.build.ts` config file in your project root:

```ts
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  importsWhitelist: ['constants.js', 'colors.js'],
  outputCSS: './public/tamagui.generated.css',
} satisfies TamaguiBuildOptions
```

**Integration Examples:**

The CLI can wrap your build command using `--`, which optimizes files beforehand
and automatically restores them after:

```json
{
  "scripts": {
    "build": "tamagui build --target web ./src -- next build"
  }
}
```

The `--` separator tells the CLI to run `next build` after optimization, then
restore your source files automatically. This is the recommended approach as it
keeps your source files unchanged.

Alternatively, run `tamagui build` separately (files will remain modified):

```json
{
  "scripts": {
    "build": "tamagui build --target web ./src && next build"
  }
}
```

**Important:** Without the `--` wrapper, files are modified in-place and not
restored. Only use this approach if you're building in a CI environment where
the files are discarded anyway.

Alternatively, use `--output` to write optimized files to a separate directory:

```json
{
  "scripts": {
    "build": "tamagui build --target web --output ./dist ./src && next build"
  }
}
```

With `--output`, source files are never modified and no restoration is needed.

For more details, see the
[Compiler Installation guide](/docs/intro/compiler-install#cli-based-in-place-compilation).

### check

Check flat style values, inconsistent versions, duplicate installs, lockfile
issues, and missing config:

```bash
npx tamagui check
```

**Flags:**

- `--strict`: Validate conditional style payloads against the project config too
- `--styles-only`: Skip the dependency checks
- `--deps-only`: Skip the style checks
- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

The command exits non-zero when it finds diagnostics, so it works as a CI gate.

### generate

Build your entire Tamagui configuration and output CSS. This is useful for
pre-generating your design system's CSS and validating your configuration.

```bash
npx tamagui generate
```

**Flags:**

- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

**What it does:**

1. Loads and validates your Tamagui configuration
2. Generates CSS for all your tokens, themes, and components
3. Outputs to the `.tamagui` directory
4. Also generates an LLM-friendly prompt file at `.tamagui/prompt.md`

### generate-css

Generate the `tamagui.generated.css` file from your configuration. Useful for build
pipelines or when you need to regenerate CSS without running a full build.

```bash
npx tamagui generate-css
```

**Flags:**

- `--output <path>`: Custom output path (default: `tamagui.generated.css`)
- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

**Example:**

```bash
npx tamagui generate-css --output ./public/styles/tamagui.generated.css
```

### generate-themes

Pre-build your theme configuration for faster runtime performance. This
generates optimized theme objects from your theme definitions.

```bash
npx tamagui generate-themes <input-path> <output-path>
```

**Example:**

```bash
npx tamagui generate-themes ./themes/input.ts ./themes/generated.ts
```

**Flags:**

- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

**Use case:** If you have complex theme generation logic, this command
pre-computes your themes at build time rather than runtime.

### icons

Generate typed, themed SVG icon components for only the icons you use. Each
icon becomes one file, and `index.ts` in the output folder exports all of them.
Running it again adds to the folder and rewrites the index.

```bash
# lucide (the default source)
npx @tamagui/cli icons add Search ChevronDown X

# phosphor, with a weight: regular, bold, duotone, fill, light, thin
npx @tamagui/cli icons add Copy --from phosphor --weight bold

# heroicons, with a variant: outline, solid, mini, micro
npx @tamagui/cli icons add Clipboard --from heroicons --variant solid

# your own svg files, looked up as <kebab-name>.svg
npx @tamagui/cli icons add Logo --from ./assets/icons
```

**Flags:**

- `--from`: `lucide` (default), `heroicons`, `phosphor`, or a folder of svg files
- `--weight`: Phosphor weight
- `--variant`: Heroicons variant
- `--out`: Output folder (default: `components/icons`)

Names are PascalCase (`ChevronDown`) or the source's kebab-case file name
(`chevron-down`). `Name=source-name` keeps your component name while drawing a
different source icon, so a set can move between libraries without changing
its imports: `icons add Search=magnifying-glass --from phosphor`. Library versions are pinned per CLI release. The generated
components need `react-native-svg` and `@tamagui/helpers-icon`. See
[Lucide Icons](/ui/lucide-icons) for usage.

### add

<Notice theme="green">
  **Tamagui Pro**: This command is available exclusively to Tamagui Pro members.
</Notice>

Add pre-configured fonts and icons from Tamagui's curated collections. This
includes Google Fonts and Iconify icon packs.

```bash
# Add a font
npx tamagui add font [packages-path]

# Add an icon pack
npx tamagui add icon [packages-path]
```

**Flags:**

- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output

**Interactive selection:**

The command will present an interactive menu where you can search and select
from available fonts or icons:

- **Fonts**: Browse Google Fonts with weight, style, and subset information
- **Icons**: Browse Iconify collections with icon counts and license information

**Default path:** If you don't provide a path, packages are installed to
`./packages` in your current directory.

**Requirements:** This feature requires
[Tamagui Pro](https://tamagui.dev/takeout) membership for access to the font and
icon repositories.

### migrate

Print an agent brief for migrating an existing app to v3.

```bash
npx tamagui migrate --from v2
npx tamagui migrate --from v1
```

`--from v1` sequences the v1-to-v2 pass ahead of the v2-to-v3 one. The brief is
the checklist of record for the upgrade: dependency updates, the config and theme
moves, the flat-values codemod, the Sheet codemod, and every deprecated API with
its before and after. The prose version is the
[upgrade guide](/docs/guides/how-to-upgrade).

### setup

Print an agent brief for adding Tamagui to a project that does not use it yet.

```bash
npx tamagui setup
```

It covers the version baseline, a pinned install, the config and provider, the
right bundler adapter, and the flat-value style grammar, and it ends by making
the agent verify with `tamagui check` and a real run rather than a typecheck.

Pair it with [migrate](#migrate) for projects already on v1 or v2, or copy the setup prompt directly:

<CopyAgentSetupButton my="2" />

### upgrade

Upgrade all Tamagui packages in your workspace to the latest version:

```bash
npx tamagui upgrade
```

**Flags:**

- `--from <version>`: Lower bound of the upgrade range
- `--to <version>`: Upper bound of the upgrade range
- `--dry-run`: Preview changes without writing files
- `--changelog-only`: Print the changelog without changing files
- `--debug`: Enable debug output

### to-tailwind

Convert Tamagui JSX props in files or globs to Tailwind `className` syntax:

```bash
npx tamagui to-tailwind ./src
```

**Flags:**

- `--write`: Write changes to files (default prints a diff)
- `--config <path>`: Resolve tokens against your Tamagui config (required with `--write`, or pass `--use-default-config`)
- `--rename-dom`: Rename `View` to `div` and other DOM equivalents

### generate-prompt

Generate an LLM-friendly markdown file documenting your design system for AI
assistants.

```bash
npx tamagui generate-prompt
```

**Flags:**

- `--output <path>`: Custom output path (default: `.tamagui/prompt.md`)
- `--debug`: Enable debug output

**What it includes:**

- All your tokens (colors, sizes, space, etc.)
- Theme definitions and variants
- Component configurations
- Font families and configurations
- Media queries and breakpoints

**Use case:** Share this file with AI assistants like Claude or ChatGPT to get
better suggestions that align with your design system.

## Global flags

All commands support these flags:

- `--help`: Show help for the command
- `--version`: Show CLI version
- `--debug`: Enable debug output
- `--verbose`: Enable verbose debug output (more detailed than `--debug`)

## Examples

### Production build pipeline

```json
{
  "scripts": {
    "build": "tamagui check && tamagui build --target web ./src -- next build"
  }
}
```

### CI with optimization verification

```json
{
  "scripts": {
    "build": "tamagui build --target web --expect-optimizations 10 ./src -- next build"
  }
}
```

This fails the build if fewer than 10 components are optimized, helping catch
configuration issues in CI.

### Cross-platform mobile app

```json
{
  "scripts": {
    "build:ios": "tamagui build --target native ./src -- eas build --platform ios",
    "build:android": "tamagui build --target native ./src -- eas build --platform android",
    "build:web": "tamagui build --target web ./src -- vite build"
  }
}
```

## Troubleshooting

### Build command fails with "cannot find module"

Make sure you have a `tamagui.build.ts` config file that correctly points to
your configuration:

```ts
export default {
  config: './tamagui.config.ts', // Verify this path is correct
  components: ['tamagui'],
}
```

### Check command reports false positives

The check command is strict about version consistency. If you have a specific
reason for version mismatches (like testing), you can document them in your
README.

### Add command shows "Repository not found"

The `add` command requires Tamagui Takeout access. Visit
[tamagui.dev/takeout](https://tamagui.dev/takeout) to learn more.


## core/configuration

---
title: Configuration
description: Set up tokens, themes, fonts, media queries, shorthands, settings, and sizing.
---

<IntroParagraph>
  Configuration connects your tokens, themes, media queries, animations,
  shorthands, settings, and sizing to every Tamagui component.
</IntroParagraph>

Start with [`@tamagui/config/v6`](/docs/core/config-v6) for default tokens,
Tailwind-aligned shorthands, and themes.

Create a `tamagui.config.ts` file:

```bash
npm install @tamagui/config
```

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  media: {
    ...defaultConfig.media,
    // add your own media queries here, if wanted
  },
})

type OurConfig = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends OurConfig {}
}
```

Pass the `config` export to a [`TamaguiProvider`](/docs/core/tamagui-provider) at
the root of your app:

```tsx
import { TamaguiProvider, html } from 'tamagui'
import { config } from './tamagui.config.ts'

export default () => (
  <TamaguiProvider config={config}>
    <html.div margin="4" />
  </TamaguiProvider>
)
```

That is a working setup. Import `tamagui.config.ts` once, near the root. Other files
reach the config through style props and hooks like `useMedia` and `useTheme`.

This guide imports from `tamagui`. If you only use the style library, swap the
imports for `@tamagui/core`, which is a strict subset.

## The shape of createTamagui

`createTamagui` takes one object. Every key is optional. Here is a complete config
written from scratch, without the v6 preset, to show each concern in one place:

```tsx fileName="tamagui.config.ts"
import { createFont, createTamagui, createTokens, isWeb } from 'tamagui'

// fonts group size, lineHeight, weight, and letterSpacing per family.
// createFont fills any keys you leave out of lineHeight, weight, or letterSpacing.
const systemFont = createFont({
  family: isWeb ? 'Helvetica, Arial, sans-serif' : 'System',
  size: {
    1: 12,
    2: 14,
    3: 15,
  },
  lineHeight: {
    // numeric config values are absolute pixels, so 1 resolves to 22
    2: 22,
  },
  weight: {
    1: '300',
    3: '600',
  },
  letterSpacing: {
    1: 0,
    2: -1,
  },
  // native only: picks the font file by weight and style
  face: {
    300: { normal: 'InterLight', italic: 'InterItalic' },
    600: { normal: 'InterBold' },
  },
})

// tokens work like CSS variables: set once, available everywhere.
// keys can be anything. the tamagui components expect 1 through 10.
const size = {
  0: 0,
  1: 5,
  2: 10,
  // ...
}

export const tokens = createTokens({
  size,
  space: { ...size, '-1': -5, '-2': -10 },
  radius: { 0: 0, 1: 3 },
  zIndex: { 0: 0, 1: 100, 2: 200 },
  color: {
    white: '#fff',
    black: '#000',
  },
})

const config = createTamagui({
  fonts: {
    heading: systemFont,
    body: systemFont,
  },

  tokens,

  // themes can change anywhere in the tree with <Theme name="dark" />.
  // dark_blue is a sub-theme of dark, reached with <Theme name="blue" /> inside it.
  themes: {
    light: {
      bg: '#f2f2f2',
      color: tokens.color.black,
    },
    dark: {
      bg: '#111',
      color: tokens.color.white,
    },
    dark_blue: {
      bg: 'darkblue',
      color: tokens.color.white,
    },
  },

  // media queries become style prop keys, useMedia keys, and group style keys
  media: {
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    short: { maxHeight: 820 },
    hoverable: { hover: 'hover' },
    touchable: { pointer: 'coarse' },
  },

  // <html.div m={10} /> becomes <html.div margin={10} />
  // as const keeps the keys literal for onlyAllowShorthands
  shorthands: {
    px: 'paddingHorizontal',
    f: 'flex',
    m: 'margin',
    w: 'width',
  } as const,

  settings: {
    disableSSR: true,
    allowedStyleValues: 'somewhat-strict-web',
  },
})

type AppConfig = typeof config

// if you publish your own design system, put its package name here instead of tamagui
declare module 'tamagui' {
  interface TamaguiCustomConfig extends AppConfig {}

  // optional: types for named group styling modifiers such as group-hover/card:
  interface TypeOverride {
    groupNames(): 'card' | 'header' | 'sidebar'
  }
}

export default config
```

If using the compiler, your tamagui.config.ts is parsed at build-time. For this reason,
we recommend keeping it relatively simple. Avoid importing heavy dependencies.

## Where each concern lives

Each key of `createTamagui` has its own page. The sections below say what the key
does and where to read more.

### TamaguiProvider

`TamaguiProvider` mounts the config at the root of your app. It also owns how the
generated CSS reaches the page in production, and the option to drop theme JS from
the client bundle. See [TamaguiProvider](/docs/core/tamagui-provider).

### Tokens

Tokens are static values with a name. They compile to CSS variables on web and are
available to every style prop. Create them with `createTokens` and pass them under
`tokens`. The categories `size`, `space`, `radius`, `zIndex`, and `color` map to
specific style properties, and you can add any category of your own. See
[Tokens](/docs/core/tokens) for how tokens resolve, custom categories, and the `px`
helper.

#### Font tokens

Fonts are tokens with structure. Each family carries its own size, line height,
weight, and letter spacing scales, created with `createFont`. Android needs the
`face` map to select font files by weight. See [Fonts](/docs/core/fonts).

### Themes

Themes sit one level above tokens. They hold values that change per subtree, most
often colors, and components read them by key. Sub-themes such as `dark_blue` fall
back to their parent. Custom `variables` merge into every base theme and can be
redefined for any subtree. See [Defining themes](/docs/core/theme#defining-themes)
for the config shape, [Themes](/docs/intro/themes) for usage, and
[Creating themes](/docs/guides/theme-builder) for generating full theme suites.

### Media

The `media` object defines named media queries. Each name becomes a style prop key,
a `useMedia` key, and a group style key. Order matters. Later entries override
earlier ones. See [useMedia](/docs/core/use-media).

### Animations

Tamagui ships four animation drivers: CSS, React Native Animated, Reanimated, and
Motion. Pick one per platform and pass it under `animations`. See
[Animations](/docs/core/animations) for the API and
[Choosing an animation driver](/docs/core/animation-drivers) for setup and
per-platform swapping.

### Shorthands

Shorthands map short prop names to style properties, so `px` can mean
`paddingHorizontal`. Config v6 ships Tailwind-aligned names. See
[Shorthands](/docs/core/shorthands).

### Settings

Settings control type strictness, SSR behavior, theme class placement, and
performance tradeoffs. A few more behaviors are set with environment variables. See
[Settings](/docs/core/settings).

### Sizing

Sizing is the shared control ladder: named rungs from `xs` to `xl` that every
sized control reads, with geometry derived from your font and space scales.
Spread `defaultSizing` and add rungs to grow the ladder. See
[Sizing](/docs/core/sizing).


## core/config-v6

---
title: 'Config v6'
description: The v3 default config with Tailwind-aligned scales and recipe-tree themes
---

<IntroParagraph>
  Config v6 is the default configuration for Tamagui v3. Its spacing, sizing,
  radius, and type scales align with Tailwind CSS, while its themes use adaptive
  11-shade ramps and composable relative levels.
</IntroParagraph>

```bash
npm install @tamagui/config
```

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui(defaultConfig)
```

## Defaults

- `space` and `size` use Tailwind's 4px scale: `1` is 4, `4` is 16, and `8`
  is 32. Half steps, `px`, negative space tokens, and the larger Tailwind keys
  are included.
- Radius tokens include Tailwind names from `xs` through `4xl` and `full`.
- Font size and line height include Tailwind names from `xs` through `9xl`.
  Their existing numeric font-config line heights remain absolute pixels.
- `w` and `h` are width and height shorthands.
- `tokens.color` contains the full Tailwind palette with names such as
  `blue-500` and `slate-200`.
- Themes provide adaptive `color-1` through `color-11`, semantic generics,
  relative `level2` through `level4`, `inverse`, `accent`, `brand`, `red`,
  `yellow`, and `green`.
- Adaptive ramp numbers are steps relative to the active theme's own scheme.
  They are not Tailwind's absolute `50` through `950` shades. Only the spelling
  changed when these keys became hyphenated.
- Shadows are per-theme values named `shadow-1` through `shadow-7`, as in v5.
  Dark themes use stronger shadows than light themes, and
  `boxShadow="0 8px 24px shadow-4"` reads `shadow-4` from the active theme.
- Z-index has no configured token scale. Bare values resolve a matching token
  only when an application adds one. Otherwise, the literal unitless value is
  preserved.

The config does not choose a global component size. Each styled control owns
its own `size` variant inline and defaults to its `md` row.

This font-config behavior is distinct from v3 style authoring. A numeric
Tamagui `lineHeight` prop is a ratio on web and native. Font configuration uses
a numeric string such as `"1.5"` for a ratio and `"24px"` for an explicit
absolute length. No value changes meaning based on its magnitude.

## Package entries

- `@tamagui/config/v6` contains the complete static default config.
- `@tamagui/config/v6-base` exports the color-independent scales, fonts, media,
  settings, and `createV6Config(colors)`.
- `@tamagui/config/v6-builder` re-exports the recipe authoring API from
  `@tamagui/themes/builder`.

The static `v6` entry imports generated themes. It does not run theme generation
in the browser.

## Animations

No animation driver is bundled. Import exactly one driver from its neutral
entry and add it to the config:

```tsx fileName="tamagui.config.ts"
import { animationsCSS } from '@tamagui/config/animations-css'
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations: animationsCSS,
})
```

The other entries are `animations-rn`, `animations-reanimated`, and
`animations-motion`. See [Choosing an Animation Driver](/docs/core/animation-drivers)
for their trade-offs.

## Tailwind frontend

Use the separate Tailwind component frontend when you want `className`
authoring:

```tsx
import { Text, View, styled } from '@tamagui/tailwind'

export function Notice() {
  return <View className="rounded-lg bg-blue-500 p-4" />
}
```

Regular components imported from `tamagui` continue to use Tamagui style props.
The shared v6 color tokens make absolute utilities such as `bg-blue-500`
resolve to the same values on web and native.

Tailwind leading utilities preserve the same distinction on both platforms.
Spacing-scale leading and px arbitraries stay absolute, while unitless
arbitraries are ratios:

```tsx
<Text className="leading-8" />       {/* 32px */}
<Text className="leading-[24px]" />  {/* 24px */}
<Text className="leading-[1.25]" />  {/* 1.25 times the font size */}
```

Read [v6 Colors](/docs/core/config-v6-colors) to customize the palette and
[Creating Themes](/docs/guides/theme-builder) to customize the tree and scales.


## core/style-pieces

---
title: style()
description: Statically-shaped style fragments created with style()
---

<IntroParagraph>
  `style()` creates statically shaped style fragments for the `style` prop and
  piece-typed component props.
</IntroParagraph>

```tsx
import { html, style } from 'tamagui' // or '@tamagui/core'

// define at module scope
const cardActive = style({
  backgroundColor: 'background-press',
  borderColor: 'border-color-hover',
  opacity: 0.9,
})

export function Card({ active }: { active?: boolean }) {
  return <html.div style={[cardActive, active && { opacity: 1 }]} />
}
```

## Module-scope definition

Call `style()` at module scope so its CSS rules are resolved and inserted once during module evaluation.

If `style()` is called during a component render, Tamagui emits a development warning:

```
[tamagui] style() was called during render. Define style pieces at module scope so their rules compile once.
```

For dynamic styles that depend on props, use `styled.dynamic` or a component `.resolve` callback instead.

## The style prop

Tamagui's `style` prop accepts a `StylePiece`, a plain style object, or an array containing both:

```tsx
const baseStyle = style({ padding: 16, borderRadius: 8 })
const activeStyle = style({ backgroundColor: 'background-press' })

// single piece
<html.div style={baseStyle} />

// array with conditional overrides (last wins)
<html.div style={[baseStyle, isActive && activeStyle, { opacity: 0.8 }]} />
```

Array elements evaluate in order. Later pieces or style objects override earlier ones per property, following Tamagui's standard style precedence.

## Static shape rule

The object passed to `style()` must have statically known property keys:

```tsx
// good: static keys, scalar values, and flat clauses
const goodPiece = style({
  backgroundColor: 'background',
  padding: 16,
  opacity: '1 hover:0.8',
  shadowOffset: { width: 0, height: 2 },
})

// avoid: spreads and computed keys
const dynamicKey = 'padding'
const badPiece = style({
  [dynamicKey]: 16,
  ...someObject,
})
```

Rules for `style()` definitions:
- Static property keys only.
- No object spreads into the definition literal.
- No computed keys.
- Structured leaf values (such as `shadowOffset`) are allowed.
- Flat clause strings (such as `'1 hover:0.8'`) are allowed.

Non-conforming pieces with dynamic spreads or computed keys deopt compiler extraction for that piece. The runtime remains unaffected and interprets the styles in JavaScript.

## Native resolution

On web, `style()` compiles each property to atomic CSS classes at module evaluation.

On React Native and JavaScript drivers, the piece preserves its underlying style object. When rendered, Tamagui resolves the style object against the active theme and caches the resolved styles per `(piece, theme)` pair.

## Piece-typed component props

Several Tamagui components accept a `StylePiece` on dedicated style props:

- `activeStyle` on `Checkbox`, `Toggle`, `ToggleGroup.Item`, and `Tabs.Tab`.
- `contentContainerStyle` on `ScrollView`.

```tsx
import { Checkbox, ScrollView, style } from 'tamagui'

const activeCheckboxStyle = style({
  backgroundColor: 'background-press',
  borderColor: 'border-color',
})

const scrollContainer = style({
  padding: 20,
  gap: 12,
})

export function Example() {
  return (
    <ScrollView contentContainerStyle={scrollContainer}>
      <Checkbox activeStyle={activeCheckboxStyle} />
    </ScrollView>
  )
}
```

These props replace the legacy `accept: 'style'` configuration option. Components forward the piece directly into their frame's `style` prop or resolve it against the active theme on native.


## core/animate-presence

---
title: AnimatePresence
description: Animate components as they mount and unmount
---

<IntroParagraph>
  AnimatePresence animates direct children before they unmount. It works with
  every animation driver in Tamagui.
</IntroParagraph>

It is inspired by and forked from
[Framer Motion](https://github.com/framer/motion).

To use with `@tamagui/core`, install and import `@tamagui/animate-presence`. It's already bundled and exported from `tamagui`.

## Basic usage

Use `enter` and `exit` object keys or string clauses to define how each
property animates in and out:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
import { AnimatePresence, html } from 'tamagui'

export const MyComponent = ({ isVisible }) => (
  <AnimatePresence>
    {isVisible && (
      <html.div
        key="my-square"
        transition="bouncy"
        backgroundColor="green"
        size={50}
        opacity={{ enter: 0, exit: 0 }}
        y={{ enter: 10, exit: -10 }}
        scale={{ enter: 0.9, exit: 0.9 }}
      />
    )}
  </AnimatePresence>
)
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
import { AnimatePresence, html } from 'tamagui'

export const MyComponent = ({ isVisible }) => (
  <AnimatePresence>
    {isVisible && (
      <html.div
        key="my-square"
        transition="bouncy"
        backgroundColor="green"
        size={50}
        opacity="enter:0 exit:0"
        y="enter:10px exit:-10px"
        scale="enter:0.9 exit:0.9"
      />
    )}
  </AnimatePresence>
)
```

</MDXTabs.Content>
</MDXTabs>

Note you don't even need to set `opacity` on the base style. Tamagui knows to normalize
styles like opacity and scale to 1 (and y to 0) if it's not defined on the base styles
but has an `enter:` or `exit:` clause.

<Notice theme="blue">
  Animated child components must each have a unique key prop so AnimatePresence can track
  their presence in the tree.
</Notice>

## Enter/exit transitions

Set `enter` and `exit` transitions when mount and unmount should differ:

```tsx
import { AnimatePresence, html } from 'tamagui'

export default ({ show }) => (
  <AnimatePresence>
    {show && (
      <html.div
        key="panel"
        transition={{ enter: 'lazy', exit: 'quick' }}
        opacity="enter:0 exit:0"
        y="enter:20px exit:-20px"
      />
    )}
  </AnimatePresence>
)
```

`enter` and `exit` each take a whole transition value, so they accept a preset
name, a CSS transition string, or an object. The rest of the transition is what
property changes use while the element is mounted:

```tsx
// enter slowly, exit quickly, property changes use bouncy
<html.div
  transition={{ preset: 'bouncy', enter: 'lazy', exit: 'quick' }}
  opacity="enter:0 exit:0"
/>
```

Because they are whole transition values, they can carry a delay and their own
per-property entries:

```tsx
// enter with lazy but move x slowly, exit with quick after 200ms
<html.div
  transition={{
    preset: 'bouncy',
    enter: { preset: 'lazy', x: 'slow' },
    exit: { preset: 'quick', delay: 200 },
  }}
  opacity="enter:0 exit:0"
  x="enter:-100px exit:100px"
/>
```

An `enter` or `exit` value replaces the base while it applies rather than
merging into it, the same way a later CSS `transition` declaration replaces an
earlier one.

This works with all four animation drivers (CSS, React Native, Reanimated, Motion).

## The `custom` prop

<HeroContainer noPad>
  <AnimationsPresenceDemo />
</HeroContainer>

```tsx hero template=AnimationsPresence

```

The `custom` prop updates a child's variant before its exit animation runs, so it can leave in a different direction than it entered:

```tsx
import { AnimatePresence } from '@tamagui/animate-presence'
import { ArrowLeft, ArrowRight } from './components/icons' // your generated icons, see Lucide Icons
import { useState } from 'react'
import { Button, Image, XStack, YStack, styled } from 'tamagui'

const GalleryItem = styled(YStack, {
  zIndex: 1,
  x: 0,
  opacity: 1,
  position: 'absolute',
  inset: 0,

  variants: {
    // 1 = right, 0 = nowhere, -1 = left
    going: styled.dynamic<number>((going) => ({
        x: `0 enter:${going > 0 ? '1000px' : '-1000px'} exit:${
          going < 0 ? '1000px' : '-1000px'
        }`,
        opacity: '1 enter:0 exit:0',
        zIndex: '1 exit:0',
      })),
  } as const,
})

const photos = [
  'https://picsum.photos/500/300',
  'https://picsum.photos/501/300',
  'https://picsum.photos/502/300',
]

const wrap = (min: number, max: number, v: number) => {
  const rangeSize = max - min
  return ((((v - min) % rangeSize) + rangeSize) % rangeSize) + min
}

export function Demo() {
  const [[page, going], setPage] = useState([0, 0])

  const imageIndex = wrap(0, photos.length, page)
  const paginate = (going: number) => {
    setPage([page + going, going])
  }

  return (
    <XStack
      overflow="hidden"
      backgroundColor="#000"
      position="relative"
      height={300}
      width="100%"
      alignItems="center"
    >
      <AnimatePresence initial={false} custom={{ going }}>
        <GalleryItem key={page} transition="slowest" going={going}>
          <Image src={photos[imageIndex]} width={500} height={300} />
        </GalleryItem>
      </AnimatePresence>

      <Button
        aria-label="Carousel left"
        icon={ArrowLeft}
        size="5"
        position="absolute"
        left="4"
        circular
        boxShadow="0 0 10px rgba(0,0,0,0.5)"
        onPress={() => paginate(-1)}
        zIndex={100}
      />
      <Button
        aria-label="Carousel right"
        icon={ArrowRight}
        size="5"
        position="absolute"
        right="4"
        circular
        boxShadow="0 0 10px rgba(0,0,0,0.5)"
        onPress={() => paginate(1)}
        zIndex={100}
      />
    </XStack>
  )
}
```

## API reference

### AnimatePresence Props

- **`children`**: one or more Tamagui components with unique `key` props
- **`initial`**: if `false`, children entering on initial mount will not animate (default: `true`)
- **`custom`**: pass data to children's variants for dynamic exit animations
- **`mode`**: determines how entering and exiting children render. Use `"wait"` to render one child at a time.
- **`onExitComplete`**: callback fired when all exiting children have finished animating

### Component Props

When used inside AnimatePresence:

- **`enter:` clauses**: values to animate from when mounting
- **`exit:` clauses**: values to animate to when unmounting
- **`transition`**: animation configuration (supports `{ enter, exit }` syntax)
- **`key`**: required unique identifier for AnimatePresence tracking

## See also

- [Animations Overview](/docs/core/animations)
- [Animation Drivers](/docs/core/animation-drivers)


## core/animations-reanimated

---
title: Reanimated Driver
description: Advanced off-thread animations with Reanimated
---

<IntroParagraph>
  [Reanimated](https://docs.swmansion.com/react-native-reanimated/) provides
  spring and timing animations for React Native and React Native Web, with
  off-thread execution on native.
</IntroParagraph>

## Installation

```bash
yarn add @tamagui/animations-reanimated react-native-reanimated
```

Follow the
[Reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)
to complete setup for your platform.

## Configuration

Add your animations to your [Tamagui config](/docs/core/configuration):

```tsx
import { createAnimations } from '@tamagui/animations-reanimated'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    fast: { duration: 160, bounce: 0.25 },
    medium: { duration: 300, bounce: 0.15 },
    slow: { duration: 450, bounce: 0.1 },
  }),
  // ...
})
```

The config format is the same for all four drivers, so a name means the same
motion whichever driver renders it.

## How it works

At runtime, this driver parses animatable style properties and hands them over
to Reanimated using worklets. Animations run on the UI thread for smooth 60fps
performance.

## Animation configuration

Reanimated animations support both spring and timing (tween) animations:

### Spring animations

```tsx
{
  duration: 400,  // the spring's undamped period, in milliseconds
  bounce: 0.5,    // 0 is critically damped, toward 1 is loose, negative is sluggish
}
```

`stiffness`, `damping`, and `mass` still work for a config already tuned against
them, and Reanimated's `velocity`, `overshootClamping`, and rest thresholds pass
through.

### Timing animations

```tsx
{
  type: 'timing',
  duration: 300,      // Duration in milliseconds
  easing: 'ease-out', // any css timing function
}
```

A plain CSS string means the same thing: `'300ms ease-out'`.

### Delay

```tsx
<Square transition={{ preset: 'bouncy', delay: 200 }} />
```

The delay is specified in milliseconds.

## When to use

**Advantages:**

- **Off-thread animations**: runs on UI thread for 60fps performance
- **Cross-platform**: works on web and React Native
- **Advanced features**: worklets, gesture integration, shared values
- **React Native optimized**: highest performance on native platforms

**Considerations:**

- Larger bundle size
- Requires Reanimated setup and configuration
- More complex than simpler drivers
- Web-only apps might prefer Motion or CSS drivers

## Platform-specific configuration

You can use Reanimated on native and a lighter driver on web:

```tsx
// animations.native.ts
import { createAnimations } from '@tamagui/animations-reanimated'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

```tsx
// animations.ts (web)
import { createAnimations } from '@tamagui/animations-motion'

export const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
})
```

Then import without the extension:

```tsx
import { animations } from './animations'
```

## Example

```tsx
import { createAnimations } from '@tamagui/animations-reanimated'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  bouncy: { duration: 400, bounce: 0.5 },
  quick: { duration: 220, bounce: 0.3 },
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="bouncy"
    opacity="enter:0"
    scale="enter:0.9"
  />
)
```

## Zero re-renders

The Reanimated driver works with Tamagui to bypass all internal style changes
and hand off directly to Reanimated worklets.

## Advanced features

Reanimated provides advanced features:

- **Gesture integration**: animate based on gesture values
- **Shared values**: share animated values between components
- **Worklets**: JavaScript functions that run on the UI thread
- **Custom animations**: full control over animation curves

See the
[Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/)
for more details.

## See also

- [Animations Introduction](/docs/core/animations)
- [CSS Driver](/docs/core/animations-css)
- [React Native Driver](/docs/core/animations-react-native)
- [Motion Driver](/docs/core/animations-motion)
- [Reanimated Documentation](https://docs.swmansion.com/react-native-reanimated/)


## core/shorthands

---
title: Shorthands
description: Map short prop names to any style property.
---

<IntroParagraph>
  Shorthands give frequently used style props shorter names, such as `px` for
  `paddingHorizontal`.
</IntroParagraph>

Define them on `createTamagui` under `shorthands`. Each key maps to one style
property:

```tsx fileName="tamagui.config.ts"
// as const keeps the keys literal so types flow through
const shorthands = {
  ac: 'alignContent',
  ai: 'alignItems',
  als: 'alignSelf',
  bg: 'backgroundColor',
  br: 'borderRadius',
  f: 'flex',
  m: 'margin',
  px: 'paddingHorizontal',
  w: 'width',
  // ...
} as const

export const config = createTamagui({
  shorthands,
  // ...
})
```

Shorthands work everywhere a style prop works: inline props, `styled`, variants,
media and pseudo clauses, and the compiler flattens them the same way it flattens
the long form.

```tsx
<html.div br="lg" bg="background" px="4" />
```

[`@tamagui/config/v6`](/docs/core/config-v6) ships with Tailwind-aligned names such
as `w`, `h`, `p`, `m`, `px`, `rounded`, `items`, and `justify`. Spread
`defaultConfig.shorthands` to extend them.

## Only allowing shorthands

Set `settings.onlyAllowShorthands` to remove the long-form prop types for every
property that has a shorthand. Autocomplete then shows one spelling per property:

```tsx fileName="tamagui.config.ts"
export const config = createTamagui({
  shorthands,
  settings: {
    onlyAllowShorthands: true,
  },
})
```

This is type-level only. The runtime still accepts the long form.

### Upgrading to 3.1

Version 3.1 repairs declarations that could allow long-form props through styled
components, compound components, and wrappers even when `onlyAllowShorthands` was
enabled. Code that relied on that regression can now report a type error. Use the
configured shorthand instead:

```tsx
// before, with an items shorthand configured for alignItems
<YStack alignItems="center" />

// after
<YStack items="center" />
```

Setting `onlyAllowShorthands: false` continues to allow both forms. Plain style
objects such as `contentContainerStyle` use React Native style property names,
for example `paddingBottom`, rather than Tamagui shorthands.


## core/config-v6-colors

---
title: Colors
description: Use the default Tailwind colors or generate v3 themes from your own palette
---

<IntroParagraph>
  Config v6 keeps layout scales separate from color. The default color pack is
  static and Tailwind-based. A custom pack is a `tokens.color` record and themes
  generated from the same token names.
</IntroParagraph>

## Default colors

`@tamagui/config/v6` includes Tailwind's `50` through `950` shades as absolute
tokens and recipe-generated adaptive themes:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui(defaultConfig)
```

```tsx
<html.div backgroundColor="blue-500" borderColor="slate-200" />
<Theme name="red">
  <html.div backgroundColor="color-2" color="color-11" />
</Theme>
```

`blue-500` is absolute. `color-2` and `color-11` adapt to the active scheme and
palette. The adaptive ramp is `color-1` through `color-11`, and a scale added
through `scales` gives twelve. Either way the number is a step relative to the
active theme's own scheme, not a Tailwind shade such as `50` or `950`. Only the
spelling changed when the ramp became hyphenated.

## Color packs

`createV6Config` composes the aligned config with any color pack:

```tsx
type V6Colors = {
  themes: Record<string, Record<string, string>>
  colorTokens?: Record<string, string>
}
```

```tsx fileName="tamagui.config.ts"
import { createV6Config } from '@tamagui/config/v6-base'
import { createTamagui } from 'tamagui'
import { themes, tokens } from './themes'

export const config = createTamagui(
  createV6Config({ themes, colorTokens: tokens.color })
)
```

## Add color scales

The `scales` option adds 12-step scales to the base `light` and `dark` themes.
Each entry gives 12 light values and 12 dark values, faintest to strongest, and
becomes theme keys `name-1` through `name-12` that adapt to the active scheme.
Subthemes reach them through parent fallback.

`@tamagui/themes/v5-color-scales` packs the classic v5 scales (`gray`, `blue`,
`red`, `yellow`, `green`, `orange`, `pink`, `purple`, `teal`, `neutral`,
`black`, `white`), so keeping the old colors while moving to v6 is two lines:

```tsx fileName="tamagui.config.ts"
import { colors, createV6Config } from '@tamagui/config/v6'
import { v5ColorScales } from '@tamagui/themes/v5-color-scales'
import { createTamagui } from 'tamagui'

export const config = createTamagui(
  createV6Config({
    ...colors,
    scales: {
      ...v5ColorScales,
      brand: {
        light: ['#f0f9ff', /* ... */ '#082f49'],
        dark: ['#082f49', /* ... */ '#f0f9ff'],
      },
    },
  })
)
```

```tsx
<html.div backgroundColor="red-10" />
<html.span color="brand-11" />
```

These are theme values, so they also resolve inside flat values like
`backgroundImage="linear-gradient(90deg, red-10, orange-11)"` and take opacity
suffixes (`red-10/50`).

## Shadows

Shadows are theme values again, as they were in v5. Each theme owns `shadow-1`
through `shadow-7`, so dark themes can use stronger shadows than light themes.
`boxShadow="0 8px 24px shadow-4"` resolves `shadow-4` from the active theme
instead of reading an absolute color token, and `shadow-color` is the theme's
`shadow-3`.

## Add a custom palette

This example keeps all default tokens and scales, then adds an `ocean` palette
and child theme:

```tsx fileName="themes.ts"
import {
  createThemes,
  fromShades,
  levels,
  ramp,
  scales,
  shades,
  tokens as defaultTokens,
  type GetThemeContext,
  type Level,
  type Scheme,
  type Treatment,
} from '@tamagui/themes/builder'

const ocean = [
  '#effcff', '#dff8ff', '#b8efff', '#7cdef9', '#35c4ed', '#0ba6d1',
  '#0784aa', '#086a89', '#0b576f', '#0b495e', '#07303f',
] as const

export const tokens = {
  color: {
    ...defaultTokens.color,
    ...Object.fromEntries(
      shades.map((shade, index) => [`ocean-${shade}`, ocean[index]])
    ),
  },
}

type Recipe = {
  scheme: Scheme
  palette: string
  treatment?: Treatment
  level?: Level
}

export const tree = {
  light: { scheme: 'light', palette: 'gray' },
  dark: { scheme: 'dark', palette: 'gray' },
  children: {
    ...levels(),
    ocean: {
      palette: 'ocean',
      treatment: 'tint',
      children: levels(),
    },
  },
} as const

function getTheme({ recipe }: GetThemeContext<typeof tokens, Recipe>) {
  const scale =
    scales[recipe.treatment ?? 'normal'][recipe.scheme][recipe.level ?? 1]

  return {
    ...ramp(recipe.palette, recipe.scheme, scale),
    ...fromShades(recipe.palette, scale),
  }
}

export const themes = createThemes(tokens, tree, { getTheme })
```

Now `theme="ocean"` uses the custom palette, and nested `theme="level2"`
keeps that palette while raising its semantic background and border values.

## Replace the default scales

The default `normal`, `bold`, and `tint` scales are plain objects. Copy or extend
them when your palette needs different contrast:

```tsx
const scales = {
  normal: myNormalScales,
  bold: myBoldScales,
  tint: myTintScales,
  outline: myOutlineScales,
}
```

The generator only sees the recipe fields and the record returned by your
resolver. Treatment names and shade choices are entirely yours.

## Generate once for production

Export the runtime result from an input file:

```tsx fileName="themes.input.ts"
export { themes } from './themes'
```

Then emit a flat module:

```bash
npx tamagui generate-themes ./themes.input.ts ./src/themes.generated.ts
```

Import `themes.generated.ts` from the config. The generated module retains the
full inferred theme name and key types without shipping the authoring tree.

The visual [Theme Studio](/theme) exports this same v3 scales-and-tree format.
For the complete API, read [Creating Themes](/docs/guides/theme-builder).


## core/sizing

---
title: Sizing
description: The shared control size ladder, from named rungs to custom sizes
---

<IntroParagraph>
  Every control that takes `size` reads from one shared ladder: five named
  rungs (`xs` through `xl`) in your config's `sizing` key. A rung is token
  keys plus geometry derived from them, so retuning your type or space scale
  moves every control together.
</IntroParagraph>

## A rung

Each entry of `sizing.sizes` is a `SizeRecipe`: six token keys, never pixels.

<PropsTable
  data={[
    {
      name: 'fontSize',
      required: true,
      type: 'string',
      description: `Font size key for the rung's text. The line height resolves from the same key.`,
    },
    {
      name: 'controlFontSize',
      required: true,
      type: 'string',
      description: `Type-scale key the square controls (checkbox, radio, switch) size from. Usually the rung's own name, but text deliberately steps down at md/lg so buttons are not chunky while the squares stay on-scale.`,
    },
    {
      name: 'paddingInline',
      required: true,
      type: 'string',
      description: `Space key for horizontal padding.`,
    },
    {
      name: 'paddingBlock',
      required: true,
      type: 'string',
      description: `Space key for vertical padding.`,
    },
    {
      name: 'gap',
      required: true,
      type: 'string',
      description: `Space key for the gap between a control's parts.`,
    },
    {
      name: 'radius',
      required: true,
      type: 'string',
      description: `Radius key for the control frame.`,
    },
    {
      name: 'px',
      required: false,
      type: '{ height: number; icon: number; square: number }',
      description: `Explicit rung geometry, skipping derivation. For scales whose keys cannot derive the ladder: v5's numeric scales pin their heights here.`,
    },
  ]}
/>

## Derived values

`resolveSizing` turns a rung into style-ready values: the six keys pass
through to the style system, and three px numbers derive from the active font
and the space scale.

- `height`: the text line box plus vertical padding, before any border. A
  button frame adds its 1px border on each side.
- `icon`: the icon px for the rung: the font size rounded up to a multiple
  of 4.
- `square`: the checkbox box, radio circle, and switch track height: 1.4
  times the control font size, rounded.

## Custom sizes

Spread `defaultSizing` and add rungs. New names are accepted everywhere a
size is, typed as `ComponentSize`, with no component changes.

```tsx fileName="tamagui.config.ts"
import { defaultConfig, defaultSizing } from '@tamagui/config/v6'

export const config = createTamagui({
  ...defaultConfig,
  sizing: {
    ...defaultSizing,
    sizes: {
      ...defaultSizing.sizes,
      xxl: {
        fontSize: 'xl',
        controlFontSize: '2xl',
        paddingInline: '10',
        paddingBlock: '3',
        gap: '3',
        radius: 'xl',
      },
    },
  },
})
```

`sizing.default` names the rung `true` (and an absent size) resolves to.

## Missing tokens

A rung that names a token your config does not have throws in development,
naming the size and the missing reference:

```text
size "xxl" references a missing token (fontSize "xl", controlFontSize "2xl", paddingBlock "3")
```

An unknown size name throws with the valid names listed. In production both
degrade to the default rung. Prefer the error: it means a rung points at a
scale your config never defined.


## core/compiler-tiers

---
title: Compiler tiers
description: How Tamagui moves from runtime components to extracted host output
---

<IntroParagraph>
  Tamagui compilation is a ladder. An app can keep the full runtime, move
  configuration-static CSS into a build artifact, or enforce a web entry with
  no Tamagui component runtime.
</IntroParagraph>

Inside an ordinary compiled app, each component is handled independently. One
dynamic component does not turn extraction off for the rest of the file.

## The build ladder

| Tier | What the build emits | What remains at runtime |
| --- | --- | --- |
| Ordinary compiled Tamagui | Extracted CSS and flattened host elements wherever analysis succeeds | Provider, config, style engine, theme and media state, animation driver, and component runtime for residual sites |
| Compiled global CSS | Ordinary compiled output plus the `outputCSS` artifact owned by the integration | Residual components and dynamic theme or media behavior remain, while configuration-static CSS generation is removed |
| Strict zero-runtime | Lowered React host JSX plus one generated CSS artifact | No Tamagui renderer, provider, style engine, config parser, theme state, media state, or component animation runtime in the zero entry |

The compiler is optional for ordinary Tamagui. Without it, components use the
runtime path. Strict zero-runtime is an experimental web-only contract and
turns every residual Tamagui site into a build error. See
[Zero-runtime mode](/docs/guides/zero-runtime).

## Candidate outcomes

The compiler records five counters for every module:

| Counter | Meaning |
| --- | --- |
| `found` | A JSX or component-call candidate resolved to a compiler-known component |
| `lowered` | The compiler safely committed edits and any extracted CSS for that candidate |
| `flattened` | A lowered candidate became a platform host element |
| `styled` | A successfully lowered candidate came from an app-local `styled()` definition |
| `bailed` | The candidate stayed on its runtime path because analysis or the component contract prevented lowering |

`styled` describes where a lowered candidate came from, so it is not a separate
result alongside `flattened`. A partially lowered candidate is `lowered` without
being `flattened`.

### Flattened

A component can flatten when its static contract accepts `className`, it is not
a behavior HOC marked `neverFlatten`, and it does not provide a styled context.
The compiler can then replace it with one host element. On web the output may
contain extracted classes plus an inline `style` object for values that must
stay dynamic.

```tsx
const tone = selected ? 'red' : 'blue'

// static layout and spacing can extract while the dynamic color remains a
// narrow host style value
<html.div display="flex" padding="4" color={tone} />
```

Conditional expressions whose branches are both static can also lower as
conditional classes. The JavaScript condition remains, while both style
branches are compiled.

### Partially lowered

Partial extraction lets safe static work leave the runtime even when one style
value remains dynamic. Only properties the host can receive directly qualify.
If a dynamic value needs Tamagui theme, media, interaction, event, or component
behavior, the candidate stays on the runtime path.

Set `disablePartialExtraction: true` in `tamagui.build.ts` when you need dynamic
candidates to remain completely runtime-owned:

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  disablePartialExtraction: true,
} satisfies TamaguiBuildOptions
```

### Runtime bailout

A candidate bails out when the compiler cannot prove a complete, safe rewrite.
Common causes include an unresolved component target, a dynamic style spread,
runtime event mapping, overlapping source edits, or a component whose static
contract requires its runtime wrapper.

A bailout is valid in ordinary compiled Tamagui. The component renders through
the same runtime that an uncompiled app uses. In strict zero-runtime, the same
residual site is a contract violation because that entry has no component
runtime to receive it.

## What you control

Authoring and build configuration influence the result:

- Put packages whose components should be evaluated in `components`.
- Keep component targets literal and style values statically analyzable when
  you want flattening.
- Use flat CSS conditions for theme, media, interaction, group, and container
  behavior that should extract.
- Set `disableOptimization` on one element to keep that element on the runtime
  path.
- Set `disableExtraction` for a file set or the whole build to use runtime
  components, commonly during development.
- Set `disablePartialExtraction` to prevent the compiler from splitting a
  dynamic candidate between extracted and host-owned styles.
- Set `outputCSS` and load that artifact to enter the compiled-global-CSS tier.
- Set `experimental.zeroRuntime` to audit or enforce the strict tier.

There is no per-component switch that forces a component to flatten. The
component's static contract and the actual authored values decide whether a
safe host replacement exists.

## Inspect the result

The Vite integration can print the compiler counters and bailout codes:

```bash
TAMAGUI_COMPILER_STATS=1 vite build
```

Use verbose mode for per-module counters:

```bash
TAMAGUI_COMPILER_STATS=verbose vite build
```

Write the same report as JSON by setting a project-relative output path:

```bash
TAMAGUI_COMPILER_STATS_FILE=.tamagui/compiler-stats.json vite build
```

The report includes totals, partial and flattened counts, bailout codes,
grouped reasons, and per-module diagnostics. These counters describe compiler
handling. They do not by themselves measure bundle size or runtime speed.

For one element, set `debug="verbose"`. In development, the existing verbose
console group includes a `receipt` with the element's `lowered`, `flattened`,
`styled`, or `bailed` tiers, each authored style prop, and the reason it was
emitted, resolved at runtime, or dropped. A fully flattened element prints the
same receipt when it renders. Receipt code is omitted from production output.


## core/style-props

---
title: Style props
description: Every style property Tamagui accepts, and how each renders per platform
---

<IntroParagraph>
  Every styled Tamagui component accepts a universal, web-aligned style API
  with cross-platform additions that render cleanly on both web and native.
</IntroParagraph>

The full types are exported as `ViewStyle` and `TextStyle`. For the base set,
see the React Native docs (v3 targets React Native 0.82):

- [React Native View style props](https://reactnative.dev/docs/view-style-props)
- [React Native Text style props](https://reactnative.dev/docs/text-style-props)

Every value may also be a token, a theme key, or a
[conditional value](/docs/intro/styles#conditional-values).

## Cross-platform additions

These render on web and native.

| Prop | Value | Notes |
| --- | --- | --- |
| `boxShadow` | string, object, or array | Accepts theme colors inside the string, such as `"0 0 10px shadow-color"`. |
| `filter` | CSS filter string | `brightness` and `opacity` work everywhere, while `blur`, `contrast`, and the rest need Android 12+. |
| `backgroundImage` | `linear-gradient()` or `radial-gradient()` | Accepts tokens and theme colors. `url()` is web only. Use `ImageBackground` on native. |
| `border` | `"1px solid border-color"` | Expands to width, style, and color per side on native. Native supports one border for all sides. |
| `outline` | `"2px solid outline-color"` | Expands to `outlineWidth`, `outlineStyle`, and `outlineColor` on native. |
| `outlineColor`, `outlineWidth`, `outlineOffset`, `outlineStyle` | color, space, space, `solid`, `dotted`, or `dashed` | |
| `textShadow` | `"2px 2px 4px shadow-color"` | Multiple shadows are web only. |
| `cursor` | CSS cursor | Web, and iOS 17+ for trackpad, stylus, and gaze. |
| `position` | `absolute`, `relative`, `fixed`, `static`, `sticky` | `fixed` becomes `absolute` on native. |
| `display` | `flex`, `none`, `contents`, and the CSS values | |
| `mixBlendMode` | `normal`, `multiply`, `screen`, `overlay`, and the rest | |
| `isolation` | `auto` or `isolate` | |
| `boxSizing` | `border-box` or `content-box` | |

### Flat transforms

Each of these is a top-level prop that folds into the `transform` array:

| Prop | Value |
| --- | --- |
| `x`, `y` | number |
| `scale`, `scaleX`, `scaleY` | number |
| `rotate`, `rotateX`, `rotateY`, `rotateZ` | string such as `"45deg"` |
| `skewX`, `skewY` | string |
| `perspective` | number |
| `matrix` | number array |

## Web-only props

These are typed and accepted everywhere, and render only on web:

| Group | Props |
| --- | --- |
| Background | `background`, `backgroundAttachment`, `backgroundBlendMode`, `backgroundClip`, `backgroundOrigin`, `backgroundPosition`, `backgroundRepeat`, `backgroundSize` |
| Borders | `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderImage` |
| Masks | `mask`, `maskImage`, `maskBorder`, `maskBorderMode`, `maskBorderOutset`, `maskBorderRepeat`, `maskBorderSlice`, `maskBorderSource`, `maskBorderWidth`, `maskClip`, `maskComposite`, `maskMode`, `maskOrigin`, `maskPosition`, `maskRepeat`, `maskSize`, `maskType` |
| Layout | `float`, `overflowBlock`, `overflowInline`, `contain`, `transformStyle` |
| Effects | `backdropFilter`, `clipPath` |
| Text and input | `caretColor`, `textEmphasis`, `touchAction` |

## Text props

Text components accept the view props above plus the React Native text
styles: `color`, `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`,
`letterSpacing`, `lineHeight`, `textAlign`, `textDecorationColor`,
`textDecorationLine`, `textDecorationStyle`, `textShadowColor`,
`textShadowOffset`, `textShadowRadius`, and `textTransform`.

### Font size values

v3 separates raw numbers from exact pixel strings:

```tsx
<html.span fontSize={17}>Platform line height</html.span>
<html.span fontSize="17px">Exact px size</html.span>
```

`fontSize={17}` is a platform value and keeps the platform-default line
height. `fontSize="17px"` passes through as CSS on web and parses to a number
on native. The v5 config pins its font `size` and `lineHeight` scales to px
strings so v2 output is preserved.

## Variables inside shorthand strings

`boxShadow`, `backgroundImage`, `filter`, `border`, `outline`, and
`textShadow` resolve tokens and theme keys inside the string on both platforms.
`borderTop` and friends and `background` do the same on web only.

```tsx
<html.div boxShadow="0 0 10px shadow-color" />
<html.div boxShadow="0 0 5px shadow-color, 0 0 15px color" />
<html.div backgroundImage="linear-gradient(to bottom, background, color)" />
<html.div filter="blur(7px)" />

// web: boxShadow: "0 0 10px var(--t-shadow-shadow-color)"
// native: boxShadow: "0 0 10px rgba(0,0,0,0.2)"
```

### border

```tsx
<html.div border="1px solid border-color" />
<html.div border="2px dashed red" />
<html.div border="none" />
```

On web the shorthand passes straight through. On native it expands to
`borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`,
`borderStyle`, and the four `border*Color` props. Native supports a single
border for all sides, so use the per-side props for anything else.

### outline

```tsx
<html.div outline="2px solid outline-color" />
<html.div outline="1px dashed red" />
<html.div outline="none" />
```

On native this expands to `outlineWidth`, `outlineStyle`, and `outlineColor`.

### backgroundImage

```tsx
<html.div backgroundImage="linear-gradient(to bottom, background, color)" />
<html.div backgroundImage="radial-gradient(circle, white, black)" />
```

`linear-gradient()` and `radial-gradient()` work on both platforms. `url()`
is web only, so use `ImageBackground` for images on native.

### textShadow

```tsx
<html.span textShadow="2px 2px 4px shadow-color">Shadowed</html.span>

// multiple shadows, web only
<html.span textShadow="1px 1px 2px shadow-color, 0 0 8px color">Glowing</html.span>
```

The individual `textShadowColor`, `textShadowOffset`, and `textShadowRadius`
props also work. Native renders one text shadow.

## rem units

`rem` works on both platforms. Browsers handle it natively, and native
converts it to pixels using `PixelRatio.getFontScale()`, so it follows the
user's font size preference:

```tsx
<html.div padding="1rem" />
<html.span fontSize="1.5rem" />
```

The base font size defaults to 16 and is set with
`settings.remBaseFontSize`. On native, `1rem` with a base of 16 equals
`16 * PixelRatio.getFontScale()` pixels.


## core/surfaces

---
title: Surfaces & Levels
description: Re-bind semantic theme values relative to the current subtree
---

<IntroParagraph>
  Surfaces group UI elements into visual containers, and levels adjust the
  contrast of semantic color tokens relative to their parent container.
</IntroParagraph>

## What they are

A **surface** is a container in your layout, such as a panel, card, dialog, or
toolbar, with its own background and border.

A **level** is a relative theme step (`level2`, `level3`, `level4`). It shifts
semantic values like `background`, `border-color`, and `color` one or more
steps from the surrounding theme. In v3, levels are how surfaces get their
contrast. There is no separate surface theme system.

Use a level when a container should stand out from what's around it. Components
inside it read the shifted values, so they adapt without extra color props:

```tsx
import { Button, Text, Theme, YStack } from 'tamagui'

export function Card() {
  return (
    <Theme name="level2">
      <YStack
        backgroundColor="background"
        borderColor="border-color"
        borderWidth={1}
        padding="4"
        borderRadius="4"
      >
        <Text color="color">Level 2 card content</Text>
        <Button>Save</Button>
      </YStack>
    </Theme>
  )
}
```

The card resolves `background` and `border-color` at level 2. `Button` reads its
colors relative to that, so it still stands out against the card.

## Two color vocabularies

Keep adaptive scale values and semantic styling values separate:

- `color-1` through `color-11` are the scheme-relative palette ramp. These are
  theme steps rather than absolute color shades.
- `background`, `background-hover`, `background-press`, `border-color`,
  `color`, and other generics describe a component's role.

Component skins should normally use the generics. A level re-binds those keys once for the whole subtree, so every skin below it responds without needing its own color calculations.

## Levels are relative sub-themes

Use `level2`, `level3`, or `level4` to raise a subtree from its current level:

```tsx
<Theme name="level2">
  <YStack backgroundColor="background" borderColor="border-color">
    <Button>Raised again by the Button skin</Button>
  </YStack>
</Theme>
```

The level name represents an operation rather than an absolute destination. From the root, `theme="level2"` resolves to absolute level 2. Inside that subtree, another `theme="level2"` resolves to absolute level 3. `theme="level3"` moves two steps from the current context. Values clamp at level 4.

The generated path records the nesting, such as `light_level2_level2`. Saturated paths are aliases of an existing map, so they do not duplicate CSS declarations.

Color themes keep their palette while levels compose:

```tsx
<Theme name="red">
  <YStack backgroundColor="background">
    <Theme name="level2">
      <Button>Still red</Button>
    </Theme>
  </YStack>
</Theme>
```

## Surface is a copied panel fixture

For layout surfaces, copy the [Surface](/ui/surface) fixture. It is a `YStack`
with a level prop and composable `filled`, `outlined`, `elevated`, `rounded`,
and `interactive` facets. Nothing is enabled by default:

```tsx
<Surface level={2} filled outlined rounded interactive />
```

The `level={2}` prop creates a `level2` theme boundary. The facets read the
semantic generics, so changing the level or surrounding color theme restyles
them together.

Component skins do not extend Surface. Card, Select content, ListItem, and other
skins use the same generic values and choose their own default level.

## Inline theme values for one-off overrides

Set the value with [`ThemeUpdate`](/docs/core/theme#theme-updates) when a patch belongs in exactly one place:

```tsx
<ThemeUpdate background-hover="blue-400">
  <YStack>{/* this subtree receives the patch */}</YStack>
</ThemeUpdate>
```

Create a named theme when the same patch appears in multiple places. Set it
inline with `ThemeUpdate` when it is local to one component.

## Custom levels

The defaults are ordinary data in `@tamagui/themes/builder`. Change a level by
editing or replacing its scale:

```tsx
import { raise, scales } from '@tamagui/themes/builder'

const level3 = {
  ...raise(scales.normal.light[1], 2),
  'border-color': 400,
}
```

`levels(max)` creates the recursive tree definitions. It works with custom
recipes because it only reads and updates the optional `level` field.

## V2 surface migration

In Tamagui v2, surface names represented fixed templates. Replace them with relative levels in v3:

| V2 theme | V3 theme |
| --- | --- |
| `surface1` | `level2` |
| `surface2` | `level3` |
| `surface3` | `level4` |
| `surface4` | `level4` |

`surface4` clamps because the default v3 scale has four absolute levels. If the old contrast was important, add another level to your own scale and tree.

## Summary

- Style reusable skins against semantic generics.
- Use `theme="level2"` for the common one-step relative boundary.
- Nest levels freely because the recipe tree tracks the current absolute level.
- Set the value on `ThemeUpdate` for a one-off patch.
- Use the copied Surface fixture for layout chrome.
- Customize scales and `levels()` in normal application code.


## core/tailwind

---
title: Tamagui Tailwind
description: Tailwind CSS utility authoring for Tamagui web and native
---

<IntroParagraph>
  Tamagui Tailwind brings utility classes in `className` to web, iOS, and
  Android through the Tamagui compiler.
</IntroParagraph>

Tailwind CSS is a trademark of Tailwind Labs Inc. Tamagui is not affiliated with or endorsed by Tailwind Labs.

## Installation

Install `@tamagui/tailwind` and `@tamagui/config`:

```bash
npm install @tamagui/tailwind @tamagui/config
```

## Basic usage

Import components directly from `@tamagui/tailwind`:

```tsx
import { Text, View } from '@tamagui/tailwind'

export function Card() {
  return (
    <View className="flex flex-row items-center gap-3 p-4 rounded-lg bg-slate-100 dark:bg-slate-800">
      <View className="w-10 h-10 rounded-full bg-blue-500" />
      <Text className="text-base font-semibold text-slate-900 dark:text-slate-100">
        Tamagui Tailwind
      </Text>
    </View>
  )
}
```

The styling frontend is selected by import path. There is no global configuration toggle.

## Semantic elements

`@tamagui/tailwind` also exports `html`, the same set of semantic elements as `html` from `tamagui`, built on the Tailwind frontend. Same tags, same element defaults, and a class string rather than style props as the styling input:

```tsx
import { html } from '@tamagui/tailwind'

export function Cta() {
  return (
    <html.button className="px-4 py-2 rounded-lg bg-blue-500 hover:bg-blue-600">
      <html.span className="text-white">Ship it</html.span>
    </html.button>
  )
}
```

Every tag renders a real element on web and its React Native equivalent on native, exactly as the `tamagui` `html` does. It composes with `styled()` too:

```tsx
import { html, styled } from '@tamagui/tailwind'

export const Button = styled(html.button, 'px-4 py-2 rounded-lg', {
  variants: {
    tone: {
      solid: 'bg-blue-500 hover:bg-blue-600',
      ghost: 'hover:bg-blue-50',
    },
  },
})
```

## Vite integration

Applications authoring with `@tamagui/tailwind` use the Vite plugin from `@tamagui/tailwind/vite`:

```ts
// vite.config.ts
import { tamaguiPlugin } from '@tamagui/tailwind/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    tamaguiPlugin({
      config: './tamagui.config.ts',
      components: ['@tamagui/tailwind'],
    }),
  ],
})
```

The plugin wraps the core Tamagui compiler and scans JSX sources for utility candidates.

## Web and native resolution

Tamagui Tailwind components render through the same core engine as standard Tamagui components:

- **On web:** The compiler extracts claimed utilities into atomic CSS classes at build time.
- **On native:** The shared renderer resolves the utility classes into React Native styles at runtime.

Both platforms share the same config, design tokens, themes, media queries, accessibility props, and animation drivers.

## Modifiers

Tamagui Tailwind supports standard modifiers:

### Pseudo states

```tsx
<View className="bg-blue-500 hover:bg-blue-600 press:bg-blue-700" />
```

Supported state modifiers include `hover:`, `press:`, `focus:`, `focus-visible:`, and `disabled:`.

### Breakpoints

```tsx
<View className="p-4 sm:p-6 md:p-8 lg:p-10" />
```

Breakpoint prefixes (e.g. `sm:`, `md:`, `lg:`, `xl:`, `max-sm:`) map to the media query definitions in your Tamagui config.

### Platform modifiers

```tsx
<View className="p-4 web:cursor-pointer native:opacity-90" />
```

Use `web:`, `native:`, `ios:`, and `android:` to apply platform-specific utilities.

### Group and container queries

```tsx
<View className="group" container="card">
  <View className="group-hover:bg-blue-600 @sm/card:flex-row" />
</View>
```

Mark ancestors with `group` or `@container` / `container`, then apply `group-hover:` or `@sm:` on children.

## Arbitrary values

Pass arbitrary values inside square brackets:

```tsx
<View className="p-[18px] w-[100px] bg-[#3b82f6] rotate-[-8deg] top-[10px]" />
```

Tamagui normalizes arbitrary values for cross-platform safety:
- Unitless numbers (such as `z-[400]`) and pixel lengths (such as `p-[18px]`, `text-[14px]`) resolve to numeric values on native. React Native requires numbers for layout and typography props.
- CSS units and functions (such as `%`, `rem`, `calc()`, `var()`, hex colors) stay strings.

## Tokens and color opacity

Utilities for color, radius, size, and spacing resolve against your Tamagui config tokens:

- `bg-blue-500` resolves to the `blue-500` color token.
- `rounded-lg` resolves to the `lg` radius token.
- `p-4` resolves to the `4` space token.

Color utilities support opacity modifiers:

```tsx
<View className="bg-blue-500/50 border-slate-300/80" />
```

The opacity suffix lowers to CSS `color-mix` on web and RGBA colors on native.

## Class-first styled()

Use `styled()` from `@tamagui/tailwind` to create reusable components with class-based variants:

```tsx
import { View, styled } from '@tamagui/tailwind'

export const Button = styled(View, 'px-4 py-2 rounded-md font-medium', {
  variants: {
    variant: {
      primary: 'bg-blue-500 hover:bg-blue-600 text-white',
      secondary: 'bg-slate-200 hover:bg-slate-300 text-slate-800',
    },
    size: {
      small: 'text-sm py-1 px-2',
      large: 'text-lg py-3 px-6',
    },
  },
  defaultVariants: {
    variant: 'primary',
  },
})
```

Variant values are class strings. The resulting component accepts `className` and its declared variant props.

## Mixing with Tamagui components

You can mix `@tamagui/tailwind` components and standard `tamagui` components within the same application:

```tsx
import { View as TamaguiView } from 'tamagui'
import { Text as TailwindText, View as TailwindView } from '@tamagui/tailwind'

export function MixedTree() {
  return (
    <TamaguiView padding="4" backgroundColor="background">
      <TailwindView className="flex flex-row items-center gap-2 p-2 rounded bg-blue-50">
        <TailwindText className="text-blue-700 font-bold">Mixed Tree</TailwindText>
      </TailwindView>
    </TamaguiView>
  )
}
```

Each component retains its authoring syntax. Both resolve through the same runtime and theme context.

## Utility coverage

Claimed utilities are parsed by `@tamagui/style-grammar`. They compile to atomic CSS on web and resolve to React Native styles on iOS and Android.

### Claimed cross-platform utilities

- **Sizing:** `w-*`, `h-*`, `size-*` (width and height), `min-w-*`, `max-w-*`, `min-h-*`, `max-h-*`, fractions (`w-1/2`), keywords (`full`, `auto`, `screen`, `min`, `max`, `fit`).
- **Spacing:** `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`, `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `gap-*`, `gap-x-*`, `gap-y-*`.
- **Flex and Alignment:** `flex`, `flex-1`, `flex-auto`, `flex-initial`, `flex-none`, `flex-row`, `flex-col`, `flex-wrap`, `flex-wrap-reverse`, `grow`, `shrink`, `items-*`, `justify-*`, `content-*`, `self-*`.
- **Typography:** `text-sm` (font size tokens), `text-white` (palette and theme colors), `text-center`/`left`/`right`/`justify`/`start`/`end` (alignment), `text-[14px]` (arbitrary size), `text-[#fff]` (arbitrary color), `font-bold` and named weights, `font-sans`/`serif`/`mono` and configured font families, `leading-*` (line height), `tracking-*` (letter spacing), `italic`/`not-italic`, `uppercase`/`lowercase`/`capitalize`/`normal-case`, `underline`/`line-through`/`no-underline`.
- **Color:** `bg-*`, `color-*`, `text-*` (colors), `border-*` (color), opacity suffix `/50` (such as `bg-blue-500/50`).
- **Radius:** `rounded-*`, `rounded-t/r/b/l-*`, `rounded-tl/tr/bl/br-*` (including `xl`, `lg`, `full`).
- **Borders:** `border` (1px default), `border-4`, `border-t/r/b/l-*`, `border-x`/`border-y` (width and color).
- **Positioning:** `relative`, `absolute`, `fixed`, `sticky`, `inset-*`, `inset-x-*`, `inset-y-*`, `top-*`, `right-*`, `bottom-*`, `left-*`, `z-*`.
- **Transforms & Effects:** `opacity-*`, `overflow-*`, `object-fit`, `pointer-events-*`, `rotate-*`, `scale-*`, `translate-x-*`, `translate-y-*`, `aspect-*`, `shadow-[…]` (arbitrary shadow), group and container markers (`group`, `container="card"`, `@container`).

`text-*` utilities resolve in strict order: configured `fontSize` token first, then alignment keywords, then configured palette color.

### Web-only passthrough

Classes that do not have a React Native style equivalent pass through to `className` on web. On native, unrecognized classes are dropped:

- **CSS Grid & Columns:** `grid-*`, `col-*`, `row-*`, `auto-cols-*`, `auto-rows-*`, `columns-*`, `break-*`
- **Filters & Blurs:** `backdrop-*`, `blur-*`, `brightness-*`, `contrast-*`, `grayscale-*`, `drop-shadow-*`
- **Gradients & Blends:** `from-*`, `via-*`, `to-*`, `bg-gradient-*`, `mix-blend-*`
- **Child & Sibling Selectors:** `space-x-*`, `space-y-*`, `divide-x-*`, `divide-y-*`
- **Rings & Outlines:** `ring-*`, `ring-offset-*`, `outline-*` (use `shadow-[…]` for cross-platform shadow)
- **Web Chrome & Pseudo Elements:** `cursor-*`, `select-*`, `appearance-*`, `resize-*`, `placeholder-*`, `caret-*`
- **Arbitrary Selectors:** `peer-*`, `has-*`, `data-*`, `aria-*`, `[&>*]`
- **Keyframe Animations:** `animate-*` (use Tamagui's `transition` prop instead)


## core/view-and-text

---
title: View & Text
description: View and Text with the full Tamagui style API
---

<IntroParagraph>
  Tamagui's `View` and `Text` match the React Native primitives and accept the
  full set of Tamagui style props.
</IntroParagraph>

They are the default building blocks. `View` is a flex column on every platform,
so a layout looks the same on web and native. On web they render a `div` and a
`span`. For semantic tags, set [`render`](/docs/core/styled#render), or see the
[HTML elements](/docs/core/html-primitives), which are in early development.

## Usage

You can use them directly:

```tsx
import { View, Text } from 'tamagui' // or '@tamagui/core'

export default () => (
  <View margin={10}>
    <Text color="color">Hello</Text>
  </View>
)
```

Inline styles and [shorthands](/docs/core/shorthands) compile away, so prefer them for one-off styles:

```tsx
import { View, Text } from 'tamagui' // or '@tamagui/core'

export default () => (
  <View mx="4" scale={1.2}>
    <Text color="color">Hello</Text>
  </View>
)
```

## With styled()

You can also use them [with styled](/docs/core/styled) to create your own lower level views that are meant to be re-usable:

```tsx
import { type SizeTokens, View, styled } from 'tamagui' // or '@tamagui/core'

export const Circle = styled(View, {
  borderRadius: 100_000_000,

  variants: {
    pin: {
      top: {
        position: 'absolute',
        top: 0,
      },
    },

    centered: {
      true: {
        alignItems: 'center',
        justifyContent: 'center',
      },
    },

    size: styled.dynamic<SizeTokens | number>((size, { tokens }) => ({
      width: tokens.size[size] ?? size,
      height: tokens.size[size] ?? size,
    })),
  } as const,
})
```

Both inline styles and `styled()` are compiler-optimized, so pick per use case.

## Props

Tamagui supports a superset of the React Native props. Start with:

- [View](https://reactnative.dev/docs/view-style-props), or
- [Text](https://reactnative.dev/docs/text-style-props)

From there, we add [style props](/docs/intro/styles) directly onto the same
object.

Finally, there are a few non-style props Tamagui adds:

### Event props

All Tamagui View-based components have Pressable-like functionality built in. You don't need to wrap in `Pressable` or `TouchableOpacity` - add event handlers directly:

```tsx
<html.div
  onPress={() => console.log('pressed')}
  onPointerEnter={() => console.log('hovered')}
  opacity="press:0.8"
  backgroundColor="hover:background-hover"
/>
```

<PropsTable
  data={[
    {
      name: 'onPress',
      required: false,
      type: '(e: GestureResponderEvent) => void',
      description: (
        <span>Called when a press is released. Works on both web and native.</span>
      ),
    },
    {
      name: 'onPressIn',
      required: false,
      type: '(e: GestureResponderEvent) => void',
      description: <span>Called immediately when a press starts.</span>,
    },
    {
      name: 'onPressOut',
      required: false,
      type: '(e: GestureResponderEvent) => void',
      description: <span>Called when a press is released or cancelled.</span>,
    },
    {
      name: 'onLongPress',
      required: false,
      type: '(e: GestureResponderEvent) => void',
      description: (
        <span>
          Called when a press is held for longer than <code>delayLongPress</code> (default
          500ms).
        </span>
      ),
    },
    {
      name: 'onFocus',
      required: false,
      type: '(e: FocusEvent) => void',
      description: <span>Called when the element receives focus.</span>,
    },
    {
      name: 'onBlur',
      required: false,
      type: '(e: FocusEvent) => void',
      description: <span>Called when the element loses focus.</span>,
    },
    {
      name: 'delayPressIn',
      required: false,
      type: 'number',
      description: (
        <span>
          Duration in ms to wait before calling <code>onPressIn</code>.
        </span>
      ),
    },
    {
      name: 'delayPressOut',
      required: false,
      type: 'number',
      description: (
        <span>
          Duration in ms to wait before calling <code>onPressOut</code> after press is
          released.
        </span>
      ),
    },
    {
      name: 'delayLongPress',
      required: false,
      type: 'number',
      description: (
        <span>
          Duration in ms to wait before calling <code>onLongPress</code>. Default is
          500ms.
        </span>
      ),
    },
    {
      name: 'minPressDuration',
      required: false,
      type: 'number',
      description: (
        <span>
          Minimum duration in ms that a press must be held before <code>onPressOut</code>{' '}
          is called.
        </span>
      ),
    },
    {
      name: 'cancelable',
      required: false,
      type: 'boolean',
      description: (
        <span>
          When true, allows the press to be cancelled by scrolling or other gestures.
        </span>
      ),
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: <span>Disables all press and hover interactions on the element.</span>,
    },
    {
      name: 'hitSlop',
      required: false,
      type: `number | Insets`,
      description: (
        <span>
          Extends the pressable area beyond the element bounds. Accepts a number (applies
          to all sides) or an object with <code>top</code>, <code>bottom</code>,{' '}
          <code>left</code>, <code>right</code>.
        </span>
      ),
    },
  ]}
/>

Use these events alongside `press:`, `hover:`, and `focus:` clauses to create interactive components. See the [Style API](/docs/intro/styles) for interaction styling.

### Other props

<PropsTable
  data={[
    {
      name: 'render',
      required: false,
      type: `string | JSX.Element | ((props, state) => JSX.Element)`,
      description: (
        <span>
          Control which element or component is rendered. Accepts an HTML tag name (e.g., <code>"button"</code>, <code>"a"</code>),
          a JSX element, or a render function receiving props and component state. String render props are compiler-optimized.
          See <a href="/docs/core/styled#render">styled() render documentation</a> for details.
        </span>
      ),
    },

    {
      name: 'transition',
      required: false,
      type: 'string | object',
      description: (
        <span>
          A CSS transition string (<code>"200ms ease-out"</code>), a preset name from your
          createTamagui configuration (<code>"bouncy"</code>), or an object for per-property
          control (<code>{`{ preset: 'bouncy', opacity: '100ms' }`}</code>). See the{' '}
          <a href="/docs/core/animations">Animations documentation</a>.
        </span>
      ),
    },

    {
      name: 'theme',
      required: false,
      type: 'string',
      description: (
        <span>
          Apply a theme or sub-theme, such as <code>theme="inverse"</code>, to
          this component and the components below it.
        </span>
      ),
    },

    {
      name: 'themeShallow',
      required: false,
      type: 'boolean',
      description: (
        <span>
          Used in combination with the theme prop, it prevents the theme from passing to children.
        </span>
      ),
    },

    {
      name: 'forceStyle',
      required: false,
      type: `'hover' | 'press' | 'focus' | 'focusVisible' | 'focusWithin'`,
      description: (
        <span>
          Forces the pseudo style state to be on.
        </span>
      ),
    },

    {
      name: 'group',
      required: false,
      type: `boolean | string`,
      description: (
        <span>
          Marks this component as a group for use in styling children based on parents named group.
        </span>
      ),
    },

    {
      name: 'className',
      required: false,
      type: 'string',
      description: (
        <span>
          Adds a className. In Tailwind mode, supported utility classes compile to
          Tamagui styles on web and native. Unknown classes pass through on web.
        </span>
      ),
    },

    {
      name: 'disableClassName',
      required: false,
      type: 'boolean',
      description: (
        <span>
          <strong>Web Only</strong>: Disables className output of styles, instead using only inline styles.
        </span>
      ),
    },

    {
      name: 'debug',
      required: false,
      type: `boolean | 'verbose' | 'break'`,
      description: (
        <span>
          When set Tamagui will output a variety of helpful information on how it parsed and
          applied styling. Verbose will output more information, and break will hit a debugger at
          the start of render in development mode.
        </span>
      ),
    },

    {
      name: 'untilMeasured',
      required: false,
      type: `'hide' | 'show'`,
      description: (
        <span>
          Works only alongside group, when children of the group are using container based sizing on native you can hide them until parent is measured.
        </span>
      ),
    },
    {

      name: 'disableOptimization',
      required: false,
      type: 'boolean',
      description: (
        <span>
          Disable all compiler optimization.
        </span>
      ),
    },

    {
      name: 'tabIndex',
      required: false,
      type: `string | number`,
      description: (
        <span>
          Used for controlling keyboard and assistive device focus. This replaces the old <code>focusable</code> prop.
        </span>
      ),
    },

    {
      name: 'role',
      required: false,
      type: 'Role',
      description: (
        <span>
          Indicates to accessibility services to treat UI component like a specific role.
        </span>
      ),
    },

    {
      name: 'asChild',
      required: false,
      type: `boolean | 'except-style' | 'except-style-web' | 'web'`,
      description: (
        <span>
          When true, Tamagui expects a single child element. Instead of rendering its own element, it will pass all props to that child, merging together any event handling props. When "except-style", the same behavior except Tamagui won't pass styles down from the parent, only non-style props.
        </span>
      ),
    },

    {
      name: 'passThrough',
      required: false,
      type: 'boolean',
      description: (
        <span>
          Advanced use only. React will "re-parent" components when it's internal tree structure changes.
          When making UI that adapts to another look, for better performance and avoiding losing user state (like focus, or uncontrolled text input), you can use passThrough rather than conditionally rendering a wrapping component.
        </span>
      ),
    },

]} />

## Event handlers

Tamagui supports all React Native events on all platforms. On web, all standard DOM event handlers work too:

### Cross-platform events

- `onPress`, `onLongPress`, `onPressIn`, `onPressOut` - Touch/press events that work on both native and web

**Pointer Events** - Modern events that unify mouse, touch, and pen input. On native, these are mapped to touch events with a normalized event shape including `clientX/Y`, `pointerId`, and `pointerType`:

- `onPointerDown`, `onPointerUp`, `onPointerMove`
- `onPointerEnter`, `onPointerLeave`, `onPointerCancel`

On native, `e.target.setPointerCapture(pointerId)` and `releasePointerCapture(pointerId)` are supported for drag scenarios where you need to receive move events outside the element bounds.

### Web-only events

The following events are available on web and automatically ignored on native:

**Mouse events**

- `onClick`, `onDoubleClick`, `onContextMenu`
- `onMouseEnter`, `onMouseLeave`, `onMouseMove`, `onMouseOver`, `onMouseOut`
- `onMouseDown`, `onMouseUp`
- `onWheel`

**Keyboard events**

- `onKeyDown`, `onKeyUp`, `onKeyPress`

**Drag and drop**

- `onDrag`, `onDragStart`, `onDragEnd`
- `onDragEnter`, `onDragLeave`, `onDragOver`
- `onDrop`

**Input events**

- `onChange`, `onInput`, `onBeforeInput`

**Scroll events**

- `onScroll`

**Clipboard events**

- `onCopy`, `onCut`, `onPaste`

**Focus events**

- `onFocus`, `onBlur`

All event handlers receive the standard React synthetic event as their argument.


## core/config-v5

---
title: 'Config v5 compatibility'
description: Preserve Tamagui v2 token and theme values while migrating to v3
---

<IntroParagraph>
  Config v5 preserves Tamagui v2 design values while an app adopts the v3 APIs
  and runtime.
</IntroParagraph>

<Notice theme="yellow">
  Tamagui v3 defaults to Config v6. Use this frozen compatibility pack when an
  existing application's layout and visual design still depend on v5 values.
  The dynamic v5 theme builders are not included in v3.
</Notice>

The v5 entry preserves the familiar independent size and space scales, the
12-step adaptive color ramp, surface theme names, component themes, fonts, and
shorthands:

```tsx fileName="tamagui.config.ts"
import { animationsCSS } from '@tamagui/config/animations-css'
import { defaultConfig } from '@tamagui/config/v5'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations: animationsCSS,
})
```

The subtle pack exports its muted generated themes separately, matching its v2
API:

```tsx fileName="tamagui.config.ts"
import { animationsCSS } from '@tamagui/config/animations-css'
import { defaultConfig, themes } from '@tamagui/config/v5-subtle'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  themes,
  animations: animationsCSS,
})
```

The static theme data is also available from `@tamagui/themes/v5`,
`@tamagui/themes/v5-subtle`, and `@tamagui/themes/v5-tokens`. Legacy animation
imports at `@tamagui/config/v5-css`, `/v5-rn`, `/v5-reanimated`, and `/v5-motion`
remain aliases to their maintained unversioned entries.

The compatibility lane does not restore `@tamagui/theme-builder`,
`@tamagui/themes/v5-builder`, or `@tamagui/themes/v5-subtle-builder`. Those
builders carried a second theme-generation architecture. New custom themes
should use [`@tamagui/themes/builder`](/docs/guides/theme-builder).

Read the [v3 upgrade guide](/docs/guides/how-to-upgrade#theme-migration) when
you are ready to move to the v6 11-step color ramp and level-based surfaces.


## core/animations

---
title: Animations
description: Swap out animation drivers per-platform or at runtime
---

<IntroParagraph>
  Tamagui animates style props through swappable drivers, with the same
  component API across web and native.
</IntroParagraph>

<HeroContainer>
  <AnimationsDemo />
</HeroContainer>

```tsx hero template=Animations

```

<Highlights
  disableLinks
  features={[
    `Animate any style prop with animation config per-prop.`,
    `Can animate across all states (media queries, hover, etc).`,
    `Multiple drivers you can swap out with type safety.`,
    `SSR safe mount animations.`,
    `Enter and exit animations with AnimatePresence.`,
  ]}
/>

Add animations to Tamagui with an animation driver. Animation drivers are designed to be swappable, so you can use lightweight CSS animations or web-focused libraries on the web, while using Reanimated on native, without changing component code outside of configuration.

For this guide, we'll use the React Native driver as an example, but you can choose from several [Animation Drivers](/docs/core/animation-drivers). For mount and unmount animations, see [AnimatePresence](/docs/core/animate-presence).

## Installation

```bash
yarn add @tamagui/animations-react-native
```

Then add it to your [Tamagui config](/docs/core/configuration):

```tsx
import { createAnimations } from '@tamagui/animations-react-native'
import { createTamagui } from 'tamagui'

export default createTamagui({
  animations: createAnimations({
    bouncy: { duration: 400, bounce: 0.5 },
    lazy: { duration: 500, bounce: -0.2 },
    quick: { duration: 220, bounce: 0.3 },
  }),
  // ...
})
```

A config entry is `{ duration, bounce }`, a CSS timing string, or
`{ type: 'timing', duration, easing }`. `stiffness`, `damping`, and `mass` still
work for a config already tuned against them. The same config resolves
to the same motion on all four drivers, so you can swap drivers without
retuning.

`@tamagui/config` ships this table for every driver, so you only need
`createAnimations` when you want names of your own:

```tsx
import { animationsCSS } from '@tamagui/config/animations-css'
```

## Usage

The `transition` prop accepts the name of an animation you've configured. By default, animations will
apply to all animatable styles, similar to setting `all` in a CSS `transition`.

Use a `hover` object key or a `hover:` string clause to animate a state value:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div transition="quick" scale={{ default: 1, hover: 1.1 }} />
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div transition="quick" scale="1 hover:1.1" />
```

</MDXTabs.Content>
</MDXTabs>

Here is an interactive example:

<HeroContainer>
  <AnimationsHoverDemo />
</HeroContainer>

```tsx hero template=AnimationsHover

```

### The transition prop rules

If you add a `transition` prop, you must always keep the prop. If you need the animation to be disabled,
pass false, null or even undefined if it suits you.

The spring-based animation drivers have expensive hooks that would degrade runtime
performance if present on every component. As a workaround, the animation hooks
are called conditionally based on whether the `transition` key is present in the props object.

So, `<Square transition={isActive ? 'bouncy' : null} />` rather than
`<Square {...isActive && { transition: 'bouncy' }} />`.

If you'd like to remove or add a transition prop after a component has already rendered, you'd have
to change the key.

### Enter clauses

Setting an `enter` object key or an `enter:` string clause tells a property to
start at that value, then animate to its base value after mount:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div transition="quick" opacity={{ default: 1, enter: 0 }} />
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div transition="quick" opacity="1 enter:0" />
```

</MDXTabs.Content>
</MDXTabs>

<HeroContainer>
  <AnimationsEnterDemo />
</HeroContainer>

```tsx hero template=AnimationsEnter

```

### The transition value

`transition` takes a CSS transition string or an object. Both forms mean the
same thing:

```tsx
// a css transition, exactly as css writes it
<html.div transition="200ms" />
<html.div transition="200ms ease-out" />
<html.div transition="transform 200ms, opacity 100ms 50ms" />

// a configured preset name, anywhere a timing goes
<html.div transition="quick" />
<html.div transition="transform quick, opacity 100ms" />

// a spring, inline
<html.div transition="spring(400ms, 0.5)" />

// nothing transitions
<html.div transition="none" />
```

The object form takes the same values under names:

```tsx
<html.div
  transition={{
    preset: 'quick',
    delay: 100,
    properties: 'transform, opacity',
    // any key that is not a transition setting is a style property
    opacity: '150ms ease-out',
  }}
/>
```

The settings are `preset`, `duration`, `bounce`, `easing`, `delay`, `behavior`,
`properties`, `spring`, `enter`, and `exit`. Every other key names a style
property and gets its own timing. An unrecognized key is an error rather than a
silent no-op.

### Granular animations

A per-property key wins for that property, the same way a later entry wins in a
CSS transition list. These two are the same transition:

```tsx
<html.div transition="all 200ms, opacity 100ms" />
<html.div transition={{ duration: 200, opacity: 100 }} />
```

Per-property values take a preset name, a CSS timing, or an object:

```tsx
<html.div
  transition={{
    preset: 'bouncy',
    // a preset name
    x: 'lazy',
    // a css timing
    opacity: '150ms ease-out',
    // or its own settings, including the low-level spring escape hatch
    y: { preset: 'bouncy', spring: { overshootClamping: true } },
  }}
/>
```

Entries do not inherit from the base. `{ duration: 200, opacity: {} }` gives
`opacity` no timing of its own, the same as `transition: all 200ms, opacity` in
CSS. Name what you want on each entry, or use `preset` for a shared starting
point.

### Springs

A spring is `duration` plus `bounce`:

```tsx
<html.div transition={{ duration: 400, bounce: 0.5 }} />
<html.div transition="spring(400ms, 0.5)" />
```

`duration` is the spring's period, which is what "how fast does this feel"
means. It is not a stopwatch: a bouncy spring keeps ringing past it, which is
the point of a bouncy spring. `bounce` is `0` for critically damped (fast, no
overshoot), goes up toward `1` for loose and oscillating, and goes negative for
sluggish. A value outside `-1` to `1` is an error.

On the web this compiles to a `linear()` easing that traces the real spring
curve, overshoot included, with no JavaScript running.

When you need the physics directly, `spring` is the escape hatch:

```tsx
<html.div transition={{ spring: { stiffness: 250, damping: 20, mass: 1.2 } }} />
```

It takes `stiffness`, `damping`, `mass`, `velocity`, `overshootClamping`,
`restDisplacementThreshold`, and `restSpeedThreshold`. Tamagui derives the
`duration`/`bounce` pair from `stiffness` and `mass`, so the same motion reaches
the CSS driver too. It is a projection of duration and bounce, not a second API.

### Presets

A preset is a name from your config's `animations`. Any name works where a
timing goes, and `preset` in the object form takes overrides:

```tsx
<html.div transition={{ preset: 'bouncy', duration: 250 }} />
```

Overriding `duration` or `bounce` re-solves the spring, so the preset keeps
whichever of the two you did not name and drops the `stiffness`/`damping` it was
written with, since those are what you just replaced. `mass` carries over: it
describes the object rather than the curve. Naming `stiffness` or `damping`
yourself still wins outright, and a preset used without a `duration` or `bounce`
override runs exactly the numbers your config gave it.

The shipped presets are the same springs on every driver: `quickest`, `quicker`,
`quick`, `medium`, `slow`, `slowest`, `lazy`, `superLazy`, `bouncy`,
`superBouncy`, plus `quickestLessBouncy`, `quickerLessBouncy`, and
`quickLessBouncy`. Keep your own table small. A duration is CSS now, so
`transition="200ms"` needs nothing configured, and a name is worth having only
when it means something a duration cannot say.

### Delay

`delay` is the second time in the CSS string, or the `delay` key:

```tsx
import { Square, XStack } from 'tamagui'

export default () => (
  <XStack gap="2">
    {[0, 1, 2, 3].map((i) => (
      <Square
        key={i}
        transition={{ preset: 'bouncy', delay: i * 100 }}
        opacity="enter:0"
        scale="enter:0.5"
        y="enter:20px"
        size={50}
        bg="color-10"
      />
    ))}
  </XStack>
)
```

Each square starts 100ms after the previous one, on enter, exit, and updates.

### Enter/exit transitions

`enter` and `exit` set the transition to use while mounting and unmounting.
Set them when elements should enter slowly and leave quickly:

```tsx
import { AnimatePresence, html } from 'tamagui'

export default ({ show }) => (
  <AnimatePresence>
    {show && (
      <html.div
        key="panel"
        transition={{ enter: 'lazy', exit: 'quick' }}
        opacity="enter:0 exit:0"
        y="enter:20px exit:-20px"
      />
    )}
  </AnimatePresence>
)
```

Each takes a whole transition value, so they can carry their own properties and
per-property timings, and the base still applies to changes while mounted:

```tsx
// enter slowly, exit quickly, changes while mounted use 200ms
<html.div
  transition={{
    duration: 200,
    enter: { preset: 'lazy', delay: 100 },
    exit: 'quick',
  }}
  opacity="enter:0 exit:0"
/>
```

An `enter` or `exit` list replaces the base while it applies rather than merging
into it, because the two never run at the same time.

This works with all four animation drivers (CSS, React Native, Reanimated,
Motion).

### Pseudo-style transitions

Specify different transitions for entering and exiting pseudo states like
hover, press, and focus. Entering a state uses that state's transition, and
exiting uses the base transition:

```tsx
import { Square } from 'tamagui'

export default () => (
  <Square
    size={100}
    bg="color-5 hover:color-10"
    transition="1000ms hover:200ms"
  />
)
```

In this example:
- **Hover enter**: Uses the 200ms transition (snaps quickly to hover state)
- **Hover exit**: Uses the 1000ms base transition (fades slowly back)

This works with all pseudo styles:

```tsx
<html.div
  transition="slow hover:quick press:bouncy focus:quick"
  scale="hover:1.1 press:0.95"
  borderColor="focus:blue-500"
/>
```

And with group pseudo states:

```tsx
<html.div group="card">
  <Square
    size={50}
    bg="color-5 group-hover/card:color-10"
    transition="1000ms group-hover/card:200ms"
  />
</html.div>
```

Priority follows CSS specificity intuition: press > hover > focus. This works with all animation drivers.

### Limiting which properties transition

Name the properties in the transition itself, the same way CSS does. In string
form the property leads the value, and in object form it is the `properties` key:

```tsx
// only transform transitions, everything else jumps
<Square transition="transform 200ms ease" />
<Square transition={{ preset: 'quick', properties: 'transform, opacity' }} />

// nothing transitions
<Square transition="none" />
```

This replaces v2's `animateOnly` prop, which was the same idea spelled as a
separate array. `properties` reaches every driver, so a list means the same
thing on CSS, Motion, React Native, and Reanimated.

Naming `transform` covers every transform part, so `x`, `y`, `scale`,
`scaleX`/`scaleY`, `rotate` and the rest all transition together. Naming one
part covers only that part:

```tsx
// x, scale and rotate all transition
<Square transition="transform 200ms" x={10} scale={1.1} rotate="5deg" />

// only x transitions; scale jumps
<Square transition="x 200ms" x={10} scale={1.1} />
```

## The onTransition lifecycle

Every animated component accepts `onTransition`, a typed callback that fires at
the start and end of a transition. It replaces the untyped, enter-only
`onDidAnimate` from v2.

```tsx
type TransitionEvent = {
  phase: 'start' | 'end'
  cause: 'enter' | 'exit' | 'update' // update = style change while mounted
  finished?: boolean                 // on 'end': false when interrupted
}

<html.div transition="quick" onTransition={(e) => { ... }} />
```

`cause` is `enter` when the component mounts into an [AnimatePresence](/docs/core/animate-presence),
`exit` when it unmounts, and `update` for any style change while it stays
mounted. On the `end` phase, `finished` is `false` when the transition was
interrupted, for example an exit canceled by a re-enter, or an update
superseded by another before it settled.

```tsx
import { html } from 'tamagui'

export default ({ on }) => (
  <html.div
    transition="300ms"
    opacity={on ? 0.5 : 1}
    onTransition={(e) => {
      if (e.phase === 'end' && e.finished) {
        // the style change finished without being interrupted
      }
    }}
  />
)
```

A driver may coalesce a multi-property update into one start/end pair per batch,
but it never skips the end event. Exit `end` fires before or with presence
removal, so you can observe exit completion without reaching into presence
internals. There is a single callback rather than separate
`onTransitionStart`/`onTransitionEnd` props because those names collide with the
React DOM event props on web.

## Imperative animation hooks

The same animated-number primitives the drivers use internally are exported from
`tamagui` (and `@tamagui/core`). Use them to drive an effect from a value you
control instead of from style props, for example a drag-linked overlay fade.

```tsx
import {
  useAnimationDriver,        // resolved driver from config, throws helpfully on the stub
  useAnimatedNumber,         // (initial: number) => UniversalAnimatedNumber
  useAnimatedNumberStyle,    // (value, worklet getStyle) => a style object
  useAnimatedNumbersStyle,   // multiple values, one style
  useAnimatedNumberReaction, // observe the value on the JS thread
} from 'tamagui'
```

Each hook is a thin delegation to the configured driver, so first-party code and
your code exercise the same surface. They throw a helpful error if no
`animations` config is set or if the configured CSS driver came from the core
`@tamagui/animations-css` entry. Import `createAnimations` from
`@tamagui/animations-css/extras` when using these hooks, `Sheet`, or draggable
`Toast` with the CSS driver. The resolved driver must not change identity
mid-lifecycle, which is only a concern with `animatedBy` multi-driver setups.

`useAnimatedNumberStyle` takes a value and a worklet that maps it to a style
object. Spread that style onto the driver's animated view. On the CSS driver, a
plain Tamagui view with a `transition` prop interpolates the change.

```tsx
import { useRef } from 'react'
import type { Animated } from 'react-native'
import {
  Button,
  View as TamaguiView,
  YStack,
  useAnimatedNumber,
  useAnimatedNumberStyle,
  useAnimationDriver,
} from 'tamagui'

export function Toggle() {
  const driver = useAnimationDriver()
  // the driver's animated view consumes the returned style; on the css driver
  // there is no driver View, so fall back to a Tamagui view + transition prop
  const AnimatedView = (driver.View ?? TamaguiView) as typeof Animated.View

  const x = useAnimatedNumber(0)
  const openRef = useRef(false)

  const style = useAnimatedNumberStyle(x, (value: number) => {
    'worklet'
    return { transform: [{ translateX: value }] }
  })

  const toggle = () => {
    openRef.current = !openRef.current
    x.setValue(openRef.current ? 200 : 0, { type: 'spring', damping: 20, stiffness: 90 })
  }

  return (
    <YStack gap="4" padding="4">
      <Button onPress={toggle}>Toggle</Button>
      <AnimatedView
        transition="slow"
        style={[{ width: 60, height: 60, backgroundColor: 'royalblue' }, style]}
      />
    </YStack>
  )
}
```

`setValue(next, config, onFinished)` accepts an optional completion callback that
fires once, with the value settled on the target. `useAnimatedNumberReaction`
observes intermediate values on the JS thread.

`UniversalAnimatedNumber`, `AnimatedNumberStrategy`, and the hook types are
public API.

## What to know when animating

### Driver completion

Every driver reports real completion. The CSS driver drives its animated numbers
with a `requestAnimationFrame` ticker and fires completion once when the value
settles, so `onTransition` end events and `setValue` completion callbacks are
accurate on web without an estimated-duration timer. Web completion detection
uses the element's running animations rather than a guessed duration.



### Conditional animations and HMR

The animation hooks are heavy, which initially meant we either had to choose
great performance or animations. We settled on a trade-off: we track if the
`transition` prop is set, and if so, we enable the hook. If it is ever set, even
just once, then the hooks will continue to run for the remainder of the
component lifecycle. This means if you ever plan to animate a component you
should keep `transition` always set on the component props. You can disable it
like so:

```tsx
<html.div transition={condition ? 'animation-name' : null} />
```

Note that because of this constraint, adding the `transition` prop to a mounted
component during dev HMR can error. Saving again or reloading clears it.

## See also

- [AnimatePresence](/docs/core/animate-presence): mount and unmount animations
- [Animation Drivers](/docs/core/animation-drivers): choose and configure animation drivers


## core/use-theme

---
title: useTheme
description: Read the current theme as typed values
---

<IntroParagraph>
  `useTheme` reads the current theme as a typed object whose values update with
  the surrounding theme context.
</IntroParagraph>

Tamagui themes operate much like
[CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties),
so [they can nest and override each other contextually](/docs/intro/themes).

The returned object proxies up through every parent theme to your tokens, just
like CSS variables at runtime.

Example:

```tsx
import { YStack, useTheme } from 'tamagui'

const App = () => {
  const theme = useTheme()

  return <YStack backgroundColor={theme['color-1'].val} />
}
```

The `useTheme` hook returns your Theme turned into a `ThemeParsed`, which means
it turns all values into a `Variable`:

```tsx
{
  background: {
    val: '#000',
    variable: 'var(--background)',
    name: 'background',
    isVar: true,
  },
  color: {
    val: '#fff',
    variable: 'var(--color)',
    name: 'color',
    isVar: true,
  },
}
```

The `useTheme` hook adds a `.get()` helper function on each Variable for
performance. On web, `.get()` returns the `.variable` property and avoids
re-rendering on value changes, because CSS custom properties handle updates
directly in the browser. On native, `.get()` returns `.val` and re-renders on
change. When the [`fastSchemeChange` setting](/docs/core/settings)
is enabled, `get()` returns a [DynamicColorIOS](https://reactnative.dev/docs/dynamiccolorios)
value on iOS to avoid re-renders there as well. Passing `get('web')` restricts
that optimization to web.

```tsx
import { useTheme } from '@tamagui/core'
import { SomeExternalComponent } from 'some-external-component'

const App = () => {
  const theme = useTheme()

  // on the web this is something like var(--background) and will avoid re-renders
  // on native it will be something like #fff and will re-render
  const background = theme.background.get()

  // if you needed to access it in a way that always returns the raw value
  const backgroundValue = theme.background.val

  return (
    <SomeExternalComponent
      style={{
        backgroundColor: background,
      }}
    />
  )
}
```

You can mix and match `useMedia` and `useTheme`, and the compiler understands
most basic usages, even with nested logic or constants within the file or
imports [whitelisted in your build setup](/docs/intro/compiler-install):

```tsx
import { YStack, useMedia, useTheme } from 'tamagui'

const App = () => {
  const theme = useTheme()
  const media = useMedia()

  return (
    <YStack
      y={media.sm ? 10 : 0}
      backgroundColor={media.lg ? theme.red : theme.blue}
      {...(media.xl && {
        y: theme.space2,
      })}
    />
  )
}
```

This will compile on the web to:

```tsx
const _cn =
  ' _alignItems-1oszu61 _boxSizing-deolkf _display-6koalj _flexBasis-1mlwlqe _flexDirection-eqz5dr _flexShrink-1q142lx _transform-_sm_1exagq _transform-_sm0_1wpzndr _backgroundColor-_lg_no4z4g _backgroundColor-_lg0_1qoifqd _transform-_xl_gqa6p0'

import { YStack, useMedia, useTheme } from 'tamagui'

const App = () => {
  return <div className={_cn} />
}
```

And the following CSS:

```css
._alignItems-1oszu61 {
  -ms-flex-align: stretch;
  -webkit-align-items: stretch;
  -webkit-box-align: stretch;
  align-items: stretch;
}
._boxSizing-deolkf {
  box-sizing: border-box;
}
._display-6koalj {
  display: -webkit-box;
  display: -moz-box;
  display: -ms-flexbox;
  display: -webkit-flex;
  display: flex;
}
._flexBasis-1mlwlqe {
  -ms-flex-preferred-size: auto;
  -webkit-flex-basis: auto;
  flex-basis: auto;
}
._flexDirection-eqz5dr {
  -ms-flex-direction: column;
  -webkit-box-direction: normal;
  -webkit-box-orient: vertical;
  -webkit-flex-direction: column;
  flex-direction: column;
}
._flexShrink-1q142lx {
  -ms-flex-negative: 0;
  -webkit-flex-shrink: 0;
  flex-shrink: 0;
}
@media (max-width: 860px) {
  :root:root ._transform-_sm_1exagq {
    -webkit-transform: translateY(10px);
    transform: translateY(10px);
  }
}
@media not all and (max-width: 860px) {
  :root:root ._transform-_sm0_1wpzndr {
    -webkit-transform: translateY(0px);
    transform: translateY(0px);
  }
}
@media (min-width: 1120px) {
  :root:root:root ._backgroundColor-_lg_no4z4g {
    background-color: var(--red);
  }
}
@media not all and (min-width: 1120px) {
  :root:root:root ._backgroundColor-_lg0_1qoifqd {
    background-color: var(--blue);
  }
}
@media (min-width: 1280px) {
  :root:root:root:root ._transform-_xl_gqa6p0 {
    -webkit-transform: translateY(var(--space2));
    transform: translateY(var(--space2));
  }
}
```

## Using outside of styling

You can `useTheme()` (and `useMedia()`) at runtime. Like useMedia, useTheme will
only re-render when it has to, and often you can skip re-renders altogether by
either passing the values to a Tamagui styled component, or by using the helper
`getVariable`:

### getVariable

If you access `theme.bg.val` in your render function, the component will only
re-render when theme.bg changes.

```tsx
import { useTheme, html } from '@tamagui/core'

export default () => {
  const theme = useTheme()

  // access the value
  console.log(theme.bg.val)

  return <html.div backgroundColor={theme['color-1']} />
}
```

## Reading another theme

`useTheme` takes no arguments and reads the ambient theme. To read values under
a different theme, wrap the reader in `<Theme name="...">` and call `useTheme`
inside it.


## components/tamagui-image/1.0.0

---
title: Image
description: Web compatible and super light image component with Tamagui style props.
name: html
component: Image
package: image-next
demoName: WebNativeImageDemo
---

<HeroContainer noPad>
  <WebNativeImageDemo />
</HeroContainer>

```tsx hero template=WebNativeImage

```

<Highlights
  features={[
    'Web compatibility',
    'Server rendering support',
    'Native and web support',
    'No react-native-web dependency',
    'Lightweight implementation',
  ]}
/>

## Installation

Image is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/image
```

## Usage

```tsx
export default () => <Image src="https://..." width={300} height={400} />
```

## API Reference

### Image

[Tamagui props](/docs/intro/props) +
[Web img props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) +
[React Native Image props](https://necolas.github.io/react-native-web/docs/image/).

<Notice>
  All web [img](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) props are
  supported on web, and all native
  [Image](https://necolas.github.io/react-native-web/docs/image/) props are supported on
  native. on native we are still using web img APIs, but not all web img props are
  supported. like `decoding`
</Notice>

#### Some common props

<PropsTable
  data={[
    {
      name: 'src',
      required: true,
      type: 'string',
      description: `The image URL.`,
    },
    {
      name: 'alt',
      required: false,
      type: 'string',
      description: `mandatory and incredibly useful for accessibility`,
    },
    {
      name: 'objectFit',
      required: false,
      type: 'CSS.ObjectFit',
      description: `sets how the content of image is resized to fit its container. it's alternative to resizeMode prop`,
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true will remove all default styles`,
    },
    {
      name: 'onLoad',
      required: false,
      type: 'function',
      description: `Callback when image is loaded`,
    },
    {
      name: 'onError',
      required: false,
      type: 'function',
      description: `Callback when image fails to load`,
    },
  ]}
/>


## components/tamagui-image/2.0.0

---
title: Image
description: Lightweight web-compatible image with Tamagui style props
name: tamagui-image
component: Image
package: image
demoName: WebNativeImageDemo
---

<IntroParagraph>
  This lightweight Image component renders on web and native with Tamagui style
  props and no react-native-web dependency.
</IntroParagraph>

<HeroContainer noPad>
  <WebNativeImageDemo />
</HeroContainer>

```tsx hero template=WebNativeImage

```

<Highlights
  features={[
    'Web and native support',
    'Server rendering support',
    'No react-native-web dependency',
  ]}
/>

## Installation

Image is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/image
```

## Usage

```tsx
export default () => <Image src="https://..." width={300} height={400} />
```

## API reference

### Image

[Tamagui props](/docs/intro/props) +
[Web img props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) +
[React Native Image props](https://necolas.github.io/react-native-web/docs/image/).

<Notice>
  All web [img](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
  props are supported on web, and all native
  [Image](https://reactnative.dev/docs/image) props are supported on native. Not
  every web img prop (like `decoding`) is supported on native.
</Notice>

#### Some common props

<PropsTable
  data={[
    {
      name: 'src',
      required: false,
      type: 'string | number',
      description: `The image URL.`,
    },
    {
      name: 'alt',
      required: false,
      type: 'string',
      description: `Mandatory and incredibly useful for accessibility.`,
    },
    {
      name: 'objectFit',
      required: false,
      type: 'CSS.ObjectFit',
      description: `Sets how the content of the image is resized to fit its container. An alternative to the \`resizeMode\` prop.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true, removes all default styles.`,
    },
    {
      name: 'onLoad',
      required: false,
      type: 'function',
      description: `Callback when the image is loaded.`,
    },
    {
      name: 'onError',
      required: false,
      type: 'function',
      description: `Callback when the image fails to load.`,
    },
  ]}
/>


## components/sheet/1.21.0

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

### Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

### API

#### &lt;Sheet /&gt;

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
  ]}
/>

#### &lt;Overlay /&gt;

Displays behind Frame. Extends [YStack](/docs/components/stacks).

#### &lt;Frame /&gt;

Contains the content. Extends [YStack](/docs/components/stacks).

#### &lt;Handle /&gt;

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

#### &lt;Scrollview /&gt;

Allows scrolling within Sheet. Extends [Scrollview](/docs/components/scroll-view).

### Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/1.0.0

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up.</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

### Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

### API

#### &lt;Sheet /&gt;

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
  ]}
/>

#### &lt;Overlay /&gt;

Displays behind Frame. Extends [YStack](/docs/components/stacks).

#### &lt;Frame /&gt;

Contains the content. Extends [YStack](/docs/components/stacks).

#### &lt;Handle /&gt;

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

#### &lt;Scrollview /&gt;

Allows scrolling within Sheet. Extends [Scrollview](/docs/components/scroll-view).

### Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/1.116.0

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

## Snap points

By default, snap points are treated as percentages.

```tsx
<Sheet snapPoints={[85, 50]}> // 85% and 50%
```

The behavior of snap points can be changed by setting the `snapPointsMode` prop to any of these values:

- **percent** (default) - Snap points are percentages of the parent container or screen as numbers
- **constant** - Snap points are raw pixel values as numbers
- **fit** - The sheet is constrained to the content's natural height without the `snapPoints` prop
- **mixed** - Snap points can be either numbers (pixels), percentages as strings (ex: `"50%"`), or `"fit"` for fit behavior

Snap points should be ordered from largest to smallest (most visible to least visible). When using `mixed` mode with the `"fit"` as a snap point, it must be the first and largest snap point.

## Unstyled

Adding the `unstyled` prop to your Handle, Overlay or Frame will turn off the default styles allowing you to customize without having to override any of the built-in styling.

## Headless with `createSheet`

Using the `createSheet` export, you can create a fully custom sheet without using any of the default styles. This is similar to `unstyled`, but it lets you also control the `open` variant.

Here's an example:

```tsx
import { View, styled } from '@tamagui/core'
import { createSheet } from '@tamagui/sheet'

const Handle = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 0.35,
      },
      false: {
        opacity: 0.5,
      },
    },
  } as const,
})

const Overlay = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 1,
        pointerEvents: 'auto',
      },
      false: {
        opacity: 0,
        pointerEvents: 'none',
      },
    },
  } as const,
})

const Frame = styled(View, {
  backgroundColor: 'background',
  // can add open variant as well
})

export const Sheet = createSheet({
  Frame,
  Handle,
  Overlay,
})
```

## Native support

Sheets now support rendering to a native iOS sheet, while still rendering any of your React Native content inside of them.

Because Metro doesn't support conditional imports and we don't want to make `tamagui` enforce installing native dependencies in order to get started, there's an install step.

As of the time of writing, we are using the new `3.0.x` branch which is in beta. Until ready, it does require a bit more setup.

```sh
yarn add react-native-ios-modal@3.0.0-5 react-native-ios-utilities@next @dominicstop/ts-event-emitter
```

Then, rebuild your native iOS app so it picks up the new native dependencies. This is done either through Expo or plain React Native.

Finally, set it up:

```tsx
import { Sheet, setupNativeSheet } from '@tamagui/sheet'
import * as NativeModal from 'react-native-ios-modal'

setupNativeSheet('ios', NativeModal)

// now you can use the `native` prop:

export default <Sheet native>{/* ... the rest of your sheet */}</Sheet>
```

## API Reference

### Sheet

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: '(number | string)[] | undefined',
      default: `[80]`,
      description: `Array of values representing different sizes for the sheet to snap to. Not used in 'fit' mode. See docs above for usage information.`,
    },
    {
      name: 'snapPointsMode',
      type: '"percent" | "constant" | "fit" | "mixed"',
      default: '"percent"',
      description: `Alters the behavior of the 'snapPoints' prop. See docs above for usage information.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
    {
      name: 'unmountChildrenWhenHidden',
      type: 'boolean',
      default: 'false',
      description:
        'Flag to enable unmounting the children after the exit animation has completed.',
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/sheet/1.59.0#portalprovider) for more information.
</Notice>

### Sheet.Overlay

Displays behind Frame. Extends [YStack](/docs/components/stacks).

### Sheet.Frame

Contains the content. Extends [YStack](/docs/components/stacks).

<PropsTable
  data={[
    {
      name: 'disableHideBottomOverflow',
      type: 'boolean',
      description: `Disables Sheet cloning the Frame and positioning it below the frame, which helps to hide content that may appear underneath when spring animations bounce past 100%.`,
    },
  ]}
/>

### Sheet.Handle

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

### Sheet.ScrollView

Allows scrolling within Sheet. Extends [ScrollView](/docs/components/scroll-view).

#### useSheet

Use this to control the sheet programatically.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'setOpen',
      type: 'Function',
      description: `Control the open state of the sheet.`,
    },
    {
      name: 'setPosition',
      type: '(index: number) => void',
      description: `Control the position of the sheet.`,
    },
  ]}
/>

## Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/1.27.0

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

## Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

## Unstyled

Adding the `unstyled` prop to your Handle, Overlay or Frame will turn off the default styles allowing you to customize without having to override any of the built-in styling.

## Headless with `createSheet`

Using the `createSheet` export, you can create a fully custom sheet without using any of the default styles. This is similar to `unstyled`, but it lets you also control the `open` variant.

Here's an example:

```tsx
import { View, styled } from '@tamagui/core'
import { createSheet } from '@tamagui/sheet'

const Handle = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 0.35,
      },
      false: {
        opacity: 0.5,
      },
    },
  } as const,
})

const Overlay = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 1,
        pointerEvents: 'auto',
      },
      false: {
        opacity: 0,
        pointerEvents: 'none',
      },
    },
  } as const,
})

const Frame = styled(View, {
  backgroundColor: 'background',
  // can add open variant as well
})

export const Sheet = createSheet({
  Frame,
  Handle,
  Overlay,
})
```

## Native support

Sheets now support rendering to a native iOS sheet, while still rendering any of your React Native content inside of them.

Because Metro doesn't support conditional imports and we don't want to make `tamagui` enforce installing native dependencies in order to get started, there's an install step:

```sh
yarn add react-native-ios-modal
pod install
# rebuild your app (expo ios, or use react-native cli)
```

And set it up as follows:

```tsx
import { Sheet, setupNativeSheet } from '@tamagui/sheet'
import { ModalView } from 'react-native-ios-modal'

setupNativeSheet('ios', ModalView)

export default (
  <Sheet native>
    {/* The rest of your sheet views, see Anatomy, example and props API */}
  </Sheet>
)
```

## API Reference

### Sheet

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
  ]}
/>

### Sheet.Overlay

Displays behind Frame. Extends [YStack](/docs/components/stacks).

### Sheet.Frame

Contains the content. Extends [YStack](/docs/components/stacks).

<PropsTable
  data={[
    {
      name: 'disableHideBottomOverflow',
      type: 'boolean',
      description: `Disables Sheet cloning the Frame and positioning it below the frame, which helps to hide content that may appear underneath when spring animations bounce past 100%.`,
    },
  ]}
/>

### Sheet.Handle

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

### Sheet.ScrollView

Allows scrolling within Sheet. Extends [Scrollview](/docs/components/scroll-view).

#### useSheet

Use this to control the sheet programatically.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'setOpen',
      type: 'Function',
      description: `Control the open state of the sheet.`,
    },
    {
      name: 'setPosition',
      type: '(index: number) => void',
      description: `Control the position of the sheet.`,
    },
  ]}
/>

## Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/1.9.18

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up.</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

### Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

### API

#### &lt;Sheet /&gt;

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
  ]}
/>

#### &lt;Overlay /&gt;

Displays behind Frame. Extends [YStack](/docs/components/stacks).

#### &lt;Frame /&gt;

Contains the content. Extends [YStack](/docs/components/stacks).

#### &lt;Handle /&gt;

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

#### &lt;Scrollview /&gt;

Allows scrolling within Sheet. Extends [Scrollview](/docs/components/scroll-view).

### Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/1.59.0

---
title: Sheet
description: A simple sheet component
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

# Sheet

<Description>A bottom sheet that slides up</Description>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

## Snap points

By default, snap points are treated as percentages.

```tsx
<Sheet snapPoints={[85, 50]}> // 85% and 50%
```

The behavior of snap points can be changed by setting the `snapPointsMode` prop to any of these values:

- **percent** (default) - Snap points are percentages of the parent container or screen as numbers
- **constant** - Snap points are raw pixel values as numbers
- **fit** - The sheet is constrained to the content's natural height without the `snapPoints` prop
- **mixed** - Snap points can be either numbers (pixels), percentages as strings (ex: `"50%"`), or `"fit"` for fit behavior

Snap points should be ordered from largest to smallest (most visible to least visible). When using `mixed` mode with the `"fit"` as a snap point, it must be the first and largest snap point.

## Unstyled

Adding the `unstyled` prop to your Handle, Overlay or Frame will turn off the default styles allowing you to customize without having to override any of the built-in styling.

## Headless with `createSheet`

Using the `createSheet` export, you can create a fully custom sheet without using any of the default styles. This is similar to `unstyled`, but it lets you also control the `open` variant.

Here's an example:

```tsx
import { View, styled } from '@tamagui/core'
import { createSheet } from '@tamagui/sheet'

const Handle = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 0.35,
      },
      false: {
        opacity: 0.5,
      },
    },
  } as const,
})

const Overlay = styled(View, {
  variants: {
    open: {
      true: {
        opacity: 1,
        pointerEvents: 'auto',
      },
      false: {
        opacity: 0,
        pointerEvents: 'none',
      },
    },
  } as const,
})

const Frame = styled(View, {
  backgroundColor: 'background',
  // can add open variant as well
})

export const Sheet = createSheet({
  Frame,
  Handle,
  Overlay,
})
```

## Native support

Sheets now support rendering to a native iOS sheet, while still rendering any of your React Native content inside of them.

Because Metro doesn't support conditional imports and we don't want to make `tamagui` enforce installing native dependencies in order to get started, there's an install step:

```sh
yarn add react-native-ios-modal
pod install
# rebuild your app (expo ios, or use react-native cli)
```

And set it up as follows:

```tsx
import { Sheet, setupNativeSheet } from '@tamagui/sheet'
import { ModalView } from 'react-native-ios-modal'

setupNativeSheet('ios', ModalView)

export default (
  <Sheet native>
    {/* The rest of your sheet views, see Anatomy, example and props API */}
  </Sheet>
)
```

## API Reference

### Sheet

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: '(number | string)[] | undefined',
      default: `[80]`,
      description: `Array of values representing different sizes for the sheet to snap to. Not used in 'fit' mode. See docs above for usage information.`,
    },
    {
      name: 'snapPointsMode',
      type: '"percent" | "constant" | "fit" | "mixed"',
      default: '"percent"',
      description: `Alters the behavior of the 'snapPoints' prop. See docs above for usage information.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
    {
      name: 'unmountChildrenWhenHidden',
      type: 'boolean',
      default: 'false',
      description:
        'Flag to enable unmounting the children after the exit animation has completed.',
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/sheet/1.59.0#portalprovider) for more information.
</Notice>

### Sheet.Overlay

Displays behind Frame. Extends [YStack](/docs/components/stacks).

### Sheet.Frame

Contains the content. Extends [YStack](/docs/components/stacks).

<PropsTable
  data={[
    {
      name: 'disableHideBottomOverflow',
      type: 'boolean',
      description: `Disables Sheet cloning the Frame and positioning it below the frame, which helps to hide content that may appear underneath when spring animations bounce past 100%.`,
    },
  ]}
/>

### Sheet.Handle

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

### Sheet.ScrollView

Allows scrolling within Sheet. Extends [ScrollView](/docs/components/scroll-view).

#### useSheet

Use this to control the sheet programatically.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'setOpen',
      type: 'Function',
      description: `Control the open state of the sheet.`,
    },
    {
      name: 'setPosition',
      type: '(index: number) => void',
      description: `Control the position of the sheet.`,
    },
  ]}
/>

## Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.


## components/sheet/2.0.0

---
title: Sheet
description: A bottom sheet that animates
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

Sheet is a bottom panel that slides up from the bottom of the screen, commonly used for mobile-friendly dialogs and action menus. It supports drag-to-dismiss, multiple snap points, and [automatically stacks](/ui/z-index) above other content.

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/docs/components/portal#native-portal-setup-recommended) to preserve React
  context inside Sheet content.
</Notice>

## Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

## API Reference

### Sheet

Contains every component for the sheet.

<PropsTable
  data={[
    {
      name: 'open',
      type: 'boolean',
      description: `Set to use as controlled component.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      default: 'false',
      description: `Disables the RemoveScroll behavior that prevents body scrolling while sheet is open. By default, RemoveScroll is enabled when the sheet is open and modal.`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
    {
      name: 'preferAdaptParentOpenState',
      type: 'boolean',
      default: 'false',
      description: `By default Sheet will prefer the open prop over a parent component that is controlling it via Adapt. In general if you want to Adapt to a sheet, you'd leave the open prop undefined. If you'd like to have the parent override the prop you've set manually on Sheet, set this to true.`,
    },
  ]}
/>

### Sheet.Overlay

Displays behind Frame. Extends [YStack](/docs/components/stacks).

### Sheet.Frame

Contains the content. Extends [YStack](/docs/components/stacks).

<PropsTable
  data={[
    {
      name: 'disableHideBottomOverflow',
      type: 'boolean',
      description: `Disables the default cloned frame cover below the sheet. Leave it omitted or false when a spring can overshoot on open; the cover prevents page content from showing through below the sheet. If your frame uses decorative absolute layers, put the fallback background on Sheet.Frame so the cloned cover can occlude the bottom too.`,
    },
  ]}
/>

### Sheet.Handle

Shows a handle above the frame by default. On tap, it will cycle between
`snapPoints`, but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

### Sheet.ScrollView

Allows scrolling within Sheet. Extends
[ScrollView](/docs/components/scroll-view).

## Native Gesture Handler Integration

For the best gesture experience on iOS and Android, Sheet supports optional integration with `react-native-gesture-handler`. This provides:

- **Smooth scroll-to-drag handoffs** - Seamlessly transition between scrolling content and dragging the sheet
- **No gesture conflicts** - Sheet and ScrollView gestures coordinate properly
- **Native-quality feel** - Matches the behavior of system sheets

#### Setup

1. Install `react-native-gesture-handler`:

```bash
npm install react-native-gesture-handler
```

2. Add the setup import to your app entry point (before any Tamagui imports):

```tsx
// App.tsx or index.js
import '@tamagui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app */}</GestureHandlerRootView>
  )
}
```

That's it! Sheet will automatically detect and use the native gesture handler when available.

#### Using Sheet.ScrollView

When using scrollable content inside a Sheet, use `Sheet.ScrollView` for proper gesture coordination:

```tsx
<Sheet>
  <Sheet.Handle />
  <Sheet.Frame>
    <Sheet.ScrollView>{/* Scrollable content */}</Sheet.ScrollView>
  </Sheet.Frame>
</Sheet>
```

This ensures:

- Scrolling up at the top of content works naturally
- Dragging down when scroll is at top drags the sheet
- Direction changes mid-gesture work smoothly

#### Without Gesture Handler

If you don't set up `react-native-gesture-handler`, Sheet falls back to React Native's built-in `PanResponder`. This works well for basic use cases but has some limitations on iOS where scroll and pan gestures can occasionally conflict.

## Notes

For Android you need to manually re-propagate any context when using `modal`.
This is because React Native doesn't support portals yet.

## Native Support

We've deprecated the `native` prop in favor of using Adapt.


## components/sheet/3.0.0

---
title: Sheet
description: A bottom sheet that animates
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

<IntroParagraph>
  Sheet presents draggable content at configurable snap points and can host
  adaptive content from other overlay components.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

Sheet is a bottom panel for mobile-friendly dialogs and action menus. It supports drag-to-dismiss, multiple snap points, and [automatically stacks](/ui/z-index) above other content.

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/ui/portal#native-portal-setup-recommended) to preserve React
  context inside Sheet content.
</Notice>

## Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Container>
      <Sheet.Background />
      {/* ...inner contents */}
    </Sheet.Container>
  </Sheet>
)
```

## API reference

### Sheet

Contains every component for the sheet.

<PropsTable
  data={[
    {
      name: 'open',
      type: 'boolean',
      description: `Set to use as controlled component.`,
    },
    {
      name: 'scope',
      type: 'string',
      description: `Isolates this Sheet and its parts from other Sheet instances when needed.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: '(string | number)[]',
      default: `[80]`,
      description: `Array of pixels or percents the sheet moves to when dragged. The first is the topmost and default when first opened. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'transitionConfig',
      type: 'AnimatedNumberStrategy',
      description: `Customize the animation strategy for position transitions.`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render with the system renderer registered through setupNativeSheet. UIKit does not expose continuous position, so Sheet.useAnimatedPosition() and onTransition are unavailable in this mode.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      default: 'false',
      description: `Disables the RemoveScroll behavior that prevents body scrolling while sheet is open. By default, RemoveScroll is enabled when the sheet is open and modal.`,
    },
    {
      name: 'portalProps',
      type: 'PortalProps',
      description: `Props passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Makes the sheet move up when the mobile keyboard opens so the focused input remains visible. Works on native and on mobile web.',
    },
    {
      name: 'preferAdaptParentOpenState',
      type: 'boolean',
      default: 'false',
      description: `By default Sheet will prefer the open prop over a parent component that is controlling it via Adapt. In general if you want to Adapt to a sheet, you'd leave the open prop undefined. If you'd like to have the parent override the prop you've set manually on Sheet, set this to true.`,
    },
    {
      name: 'onTransition',
      type: `(e: { phase: 'start' | 'end', cause: 'open' | 'close' | 'snap', position: number, finished?: boolean }) => void`,
      description: `Fires at the start and end of the custom sheet's position transition. cause is "open" when moving from closed, "close" when moving off screen, and "snap" when moving between snap points while open. On the end phase, finished is false when the transition was interrupted (e.g. a close canceled by a re-open). position is the resolved translateY target in px from the top of the screen. Replaces the old onAnimationComplete prop. The native iOS system sheet does not expose this lifecycle.`,
    },
    {
      name: 'disableHideWhenClosed',
      type: 'boolean',
      default: 'false',
      description: `By default a fully-closed sheet wrapper is hidden with display: "none". Set this to keep the closed wrapper laid out, for example so native visual effects can initialize below it. pointerEvents still gates interaction while closed.`,
    },
    {
      name: 'unmountChildrenWhenHidden',
      type: 'boolean',
      default: 'false',
      description: `(experimental) Remove the children while the sheet is fully closed to save some rendering cost. Can interfere with animations.`,
    },
  ]}
/>

### Sheet.Overlay

Displays behind the sheet content. Extends [YStack](/ui/stacks).

`Sheet.Overlay` must be a direct child of `Sheet`. It renders outside the animated
content region so it stays fixed while the container moves.

In v3 the sheet no longer fades anything for you. `Sheet.Overlay` has no baked-in
opacity, so you drive its fade yourself. See [Overlay fades](#overlay-fades) for
the two supported patterns.

### Sheet.Container

Contains the sheet content and layout props. Extends
[YStack](/ui/stacks).

<PropsTable
  data={[
    {
      name: 'adjustPaddingForOffscreenContent',
      type: 'boolean',
      description: `Adds padding for currently offscreen content so flex children size to the visible sheet area.`,
    },
  ]}
/>

### Sheet.Background

The themed sheet surface. Extends [YStack](/ui/stacks).

Place it as the first child of `Sheet.Container`. By default it fills the
container and extends past the bottom edge so spring overshoot does not reveal
the page below the sheet. Put visual surface props like `bg`, `borderRadius`,
and `shadow*` on `Sheet.Background`; keep layout props like
`padding`, `gap`, and `maxHeight` on `Sheet.Container`.

<PropsTable
  data={[
    {
      name: 'disableHideBottomOverflow',
      type: 'boolean',
      description: `Disables the default background extension below the sheet.`,
    },
  ]}
/>

### Sheet.Handle

Shows a handle above the container by default. On tap, it will cycle between
`snapPoints`, but this can be overridden with `onPress`.

Extends [XStack](/ui/stacks).

In v3 the Handle ships no opacity of its own. The idle dim and the fade-in on
open are aesthetics, so they live in the copied skin rather than the behavior
package. Set `opacity` (and an `open`-driven opacity if you want it) on your own
`Sheet.Handle`.

### Sheet.ScrollView

Allows scrolling within Sheet. Extends
[ScrollView](/ui/scroll-view).

## Sheet.useAnimatedPosition

`Sheet.useAnimatedPosition()` returns the sheet's live animated position so you
can drive effects that track the drag on the UI thread. Call it inside a `Sheet`;
it throws with a clear message outside that scope.

```tsx
const { value, screenSize, frameSize, snapOffsets, minY } =
  Sheet.useAnimatedPosition()
```

- `value` is the exact `UniversalAnimatedNumber` driving the frame's translateY,
  in px from the top of the screen. Feed it to
  [useAnimatedNumberStyle](/docs/core/animations#imperative-animation-hooks).
- `screenSize` is the height of the viewport the sheet positions against.
- `frameSize` is the measured height of the sheet frame.
- `snapOffsets` are the resolved translateY positions, in the same order as
  `snapPoints`.
- `minY` is the top-most (fully open) position.

These are enough to compute any progress mapping inside a `getStyle` worklet.
There is no separate derived progress value; the recipe lives in docs and the
canonical skin.

`Sheet.useAnimatedPosition()` and the Sheet `onTransition` callback are available
on Tamagui's custom Sheet. The native iOS system sheet selected by the `native`
prop is driven by UIKit, which does not expose a continuous position. Remove the
`native` prop when you need position-linked effects or transition lifecycle events.

## Overlay fades

The sheet does not fade anything for you, so an overlay fade is your code. There
are two supported patterns.

**1. Presence fade** (animates on open and close only). Put enter/exit styles on
`Sheet.Overlay`:

```tsx
<Sheet.Overlay
  transition="quick"
  opacity="0.5 enter:0 exit:0"
/>
```

**2. Drag-linked fade** (tracks the finger). Read the animated position and map
it to opacity with `useAnimatedNumberStyle`:

```tsx
import type { Animated } from 'react-native'
import {
  Sheet,
  View as TamaguiView,
  useAnimationDriver,
  useAnimatedNumberStyle,
} from 'tamagui'

// drag-linked overlay fade built entirely on the public hooks:
// Sheet.useAnimatedPosition() gives the live translateY, useAnimatedNumberStyle
// maps it to an opacity worklet. rendered through the driver's animated view so
// it works on every driver (css re-renders + DOM transition, motion/reanimated
// run on their own value).
function DragLinkedBackdrop() {
  const animationDriver = useAnimationDriver()
  const AnimatedView = (animationDriver.View ?? TamaguiView) as typeof Animated.View

  const { value, screenSize } = Sheet.useAnimatedPosition()

  const style = useAnimatedNumberStyle(value, (y: number) => {
    'worklet'
    return { opacity: Math.max(0, 0.6 * (1 - y / screenSize)) }
  })

  return (
    <AnimatedView
      transition="quick"
      style={[
        { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, backgroundColor: '#000' },
        style,
      ]}
    />
  )
}

<Sheet.Overlay backgroundColor="transparent">
  <DragLinkedBackdrop />
</Sheet.Overlay>
```

Keep `Sheet.Overlay` as the direct child of `Sheet`, then render the hook-driven
backdrop inside it. The driver's animated view makes the worklet-driven style
apply on every driver.

## Native system renderers

Register a renderer at app startup to use system presentation with `<Sheet native>`.
Without a registered renderer, Sheet uses its custom implementation. Tamagui
owns open and position state, context, Adapt, and the lifetime of one content
tree. The renderer owns platform presentation, authored detents, gestures,
keyboard handling, and physical dismissal.

```tsx
import { setupNativeSheet, type NativeSheetRendererProps } from '@tamagui/sheet'

setupNativeSheet('ios', NativeSheetRenderer)
```

`NativeSheetRendererProps` supplies the resolved `open` value, `onOpenChange`,
`position`, `onPositionChange`, and normalized `snapPoints`. A point is
`{ type: 'percent', value: number }`, `{ type: 'height', value: number }`, or
`{ type: 'fit' }`. A dismissal-only bottom point is removed before forwarding.
The other Sheet props, content, and host ref reach the renderer unchanged.

Report interaction requests through `onOpenChange` and `onPositionChange`.
Controlled parents may decline either request; continue presenting their
accepted values. Call `onDismiss` only after the original presentation is
physically removed following an accepted close. A reopen interrupts that
completion. Tamagui then releases Adapt presence and, when requested, unmounts
hidden children. Do not mount a second copy of the content beside the native
presentation.

Render `children` once inside the platform host. `Sheet.Container` measures
content without custom sheet positioning, `Sheet.ScrollView` forwards to the
native React Native ScrollView, and the system supplies the background,
overlay, and grabber. `Sheet.Background`, `Sheet.Overlay`, and `Sheet.Handle`
render nothing in this mode. Their styles and press handlers do not customize
the system chrome. Use the renderer's presentation callbacks for dismissal
policy.

The registration accepts a React component. An imperative implementation keeps
a controller ref inside that component and drives its presentation methods from
the resolved `open` value. Use a layout effect when these commands synchronize
the host's controlled value, so its acknowledgment observes the parent's accepted
state. Forward interaction requests and physical completion separately. Preserve
the native library's content container and lazy mounting behavior, and check
parent-declined close and reopen during dismissal against its actual events.
The previous `setupNativeSheet('ios', modalModule)` object registration is
replaced by this component contract; no modal dependency is built into Tamagui.

Native renderers decide which Sheet options their platform can represent.
Reject unsupported combinations before presenting. A native iOS system sheet
does not expose continuous animated position or custom transition events.
`moveOnKeyboardChange` does not install Tamagui's custom keyboard driver in a
native renderer; its host handles the keyboard. Keep `native` off for custom
sheet animation and gesture behavior.

## Native gesture handler integration

For the best gesture experience on iOS and Android, Sheet supports optional integration with `react-native-gesture-handler`. This provides:

- **Smooth scroll-to-drag handoffs** - transition between scrolling content and dragging the sheet
- **No gesture conflicts** - Sheet and ScrollView gestures coordinate properly
- **Native-quality feel** - matches the behavior of system sheets

#### Setup

1. Install `react-native-gesture-handler`:

```bash
npm install react-native-gesture-handler
```

2. Add the setup import to your app entry point (before any Tamagui imports):

```tsx
// App.tsx or index.js
import '@tamagui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app */}</GestureHandlerRootView>
  )
}
```

That's it! Sheet will automatically detect and use the native gesture handler when available.

#### Using Sheet.ScrollView

When using scrollable content inside a Sheet, use `Sheet.ScrollView` for proper gesture coordination:

```tsx
<Sheet>
  <Sheet.Handle />
  <Sheet.Container>
    <Sheet.Background />
    <Sheet.ScrollView>{/* Scrollable content */}</Sheet.ScrollView>
  </Sheet.Container>
</Sheet>
```

This ensures:

- Scrolling up at the top of content works naturally
- Dragging down when scroll is at top drags the sheet
- Direction changes mid-gesture work smoothly

#### Without gesture handler

If you don't set up `react-native-gesture-handler`, Sheet falls back to React Native's built-in `PanResponder`. This works well for basic use cases but has some limitations on iOS where scroll and pan gestures can occasionally conflict.

## Notes

A fully-closed sheet is hidden with `display: 'none'` rather than by fading to
transparent. Use [`disableHideWhenClosed`](#sheet) if you need the closed
wrapper to stay laid out. `pointerEvents` still gates interaction while closed,
and `unmountChildrenWhenHidden` keys off the same closed state.

For Android you need to manually re-propagate any context when using `modal`.
This is because React Native doesn't support portals yet.


## components/sheet/1.123.18

---
title: Sheet
description: A bottom sheet that animates.
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

### Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

### API

#### &lt;Sheet /&gt;

Contains every component for the sheet.

<PropsTable
  data={[
    { name: 'open', type: 'boolean', description: `Set to use as controlled component.` },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
  ]}
/>

#### &lt;Overlay /&gt;

Displays behind Frame. Extends [YStack](/docs/components/stacks).

#### &lt;Frame /&gt;

Contains the content. Extends [YStack](/docs/components/stacks).

#### &lt;Handle /&gt;

Shows a handle above the frame by default, on tap it will cycle between `snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

#### &lt;Scrollview /&gt;

Allows scrolling within Sheet. Extends [Scrollview](/docs/components/scroll-view).

### Notes

For Android you need to manually re-propagate any context when using `modal`. This is because React Native doesn't support portals yet.

### Native support

We've deprecated the `native` prop in favor of using Adapt.


## components/sheet/1.130.0

---
title: Sheet
description: A bottom sheet that animates.
name: sheet
component: Sheet
package: sheet
demoName: Sheet
---

<HeroContainer showAnimationDriverControl>
  <SheetDemo />
</HeroContainer>

```tsx hero template=Sheet

```

<Highlights
  features={[
    `Lightweight implementation with drag support`,
    `Multiple snap points and a handle`,
    `Automatic screen-size adaptation`,
    `Animations, themes, and size props`,
  ]}
/>

## Installation

Sheet is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/sheet
```

### Anatomy

```tsx
import { Sheet } from 'tamagui' // or '@tamagui/sheet'

export default () => (
  <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Frame>{/* ...inner contents */}</Sheet.Frame>
  </Sheet>
)
```

### API

#### &lt;Sheet /&gt;

Contains every component for the sheet.

<PropsTable
  data={[
    {
      name: 'open',
      type: 'boolean',
      description: `Set to use as controlled component.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Uncontrolled open state on mount.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called on change open, controlled or uncontrolled.`,
    },
    {
      name: 'position',
      type: 'number',
      description: `Controlled position, set to an index of snapPoints.`,
    },
    {
      name: 'defaultPosition',
      type: 'number',
      description: `Uncontrolled default position on mount.`,
    },
    {
      name: 'snapPoints',
      type: 'number[]',
      default: `[80, 10]`,
      description: `Array of numbers, 0-100 that corresponds to % of the screen it should take up. Should go from most visible to least visible in order. Use "open" prop for fully closed.`,
    },
    {
      name: 'onPositionChange',
      type: '(position: number) => void',
      description: `Called on change position, controlled or uncontrolled.`,
    },
    {
      name: 'dismissOnOverlayPress',
      type: 'boolean',
      default: 'true',
      description: `Controls tapping on the overlay to close, defaults to true.`,
    },
    {
      name: 'animationConfig',
      type: 'Animated.SpringAnimationConfig',
      default: 'true',
      description: `Customize the spring used, passed to react-native Animated.spring().`,
    },
    {
      name: 'native',
      type: 'boolean | "ios"[]',
      description: `(iOS only) Render to a native sheet, must install native dependency first.`,
    },
    {
      name: 'disableDrag',
      type: 'boolean',
      description: `Disables all touch events to drag the sheet.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      description: `Renders sheet into the root of your app instead of inline.`,
    },
    {
      name: 'dismissOnSnapToBottom',
      type: 'boolean',
      description: `Adds a snap point to the end of your snap points set to "0", that when snapped to will set open to false (uncontrolled) and call onOpenChange with false (controlled).`,
    },
    {
      name: 'forceRemoveScrollEnabled',
      type: 'boolean',
      default: 'false',
      description: `By default. Tamagui uses react-remove-scroll to prevent anything outside the sheet scrolling. This can cause some issues so you can override the behavior with this prop (either true or false).`,
    },
    {
      name: 'portalProps',
      type: 'Object',
      description: `YStack props that can be passed to the Portal that sheet uses when in modal mode.`,
    },
    {
      name: 'moveOnKeyboardChange',
      type: 'boolean',
      default: 'false',
      description:
        'Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible.',
    },
    {
      name: 'preferAdaptParentOpenState',
      type: 'boolean',
      default: 'false',
      description: `By default Sheet will prefer the open prop over a parent component that is controlling it via Adapt. In general if you want to Adapt to a sheet, you'd leave the open prop undefined. If you'd like to have the parent override the prop you've set manually on Sheet, set this to true.`,
    },
  ]}
/>

#### &lt;Overlay /&gt;

Displays behind Frame. Extends [YStack](/docs/components/stacks).

#### &lt;Frame /&gt;

Contains the content. Extends [YStack](/docs/components/stacks).

#### &lt;Handle /&gt;

Shows a handle above the frame by default, on tap it will cycle between
`snapPoints` but this can be overridden with `onPress`.

Extends [XStack](/docs/components/stacks).

#### &lt;ScrollView /&gt;

Allows scrolling within Sheet. Extends
[Scrollview](/docs/components/scroll-view).

### Notes

For Android you need to manually re-propagate any context when using `modal`.
This is because React Native doesn't support portals yet.

### Native support

We've deprecated the `native` prop in favor of using Adapt.


## components/card/1.0.0

---
title: Card
description: Sizable, themeable cards with a flexible API.
name: card
component: Card
package: card
demoName: Card
---

<HeroContainer>
  <CardDemo />
</HeroContainer>

```tsx hero template=Card

```

<Highlights
  features={[
    `Size prop shared with Card children`,
    `Themeable helper props including elevate`,
    `Background component with built-in positioning`,
  ]}
/>

## Installation

Card is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/card
```

## Anatomy

```tsx
import { Card } from 'tamagui' // or '@tamagui/card'

export default () => (
  <Card>
    <Card.Header />
    <Card.Footer />
    {/* any other components */}
    <Card.Background />
  </Card>
)
```

## API Reference

### Card

Frame of the card, extends [ThemeableStack props](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Header

Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Footer

Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Background

Extends [YStack](/docs/components/stacks), set to `position="absolute"` and `inset={0}` with zIndex below Header/Footer.

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/card/2.0.0

---
title: Card
description: Sizable, themeable cards with a flexible API
name: card
component: Card
package: card
demoName: Card
---

<HeroContainer>
  <CardDemo />
</HeroContainer>

```tsx hero template=Card

```

<Highlights
  features={[
    `Size prop shared with Card children`,
    `Themeable helper props including elevate`,
    `Background component with built-in positioning`,
  ]}
/>

## Installation

Card is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/card
```

## Anatomy

```tsx
import { Card } from 'tamagui' // or '@tamagui/card'

export default () => (
  <Card>
    <Card.Header />
    <Card.Footer />
    {/* any other components */}
    <Card.Background />
  </Card>
)
```

## API Reference

### Card

Frame of the card, extends [ThemeableStack props](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Header

Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Footer

Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Background

Extends [YStack](/docs/components/stacks), set to `position="absolute"` and `inset={0}` with `zIndex` below Header/Footer.

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/card/3.0.0

---
title: Card
description: Sizable, themeable cards with a flexible API
name: card
component: Card
package: card
demoName: Card
---

<IntroParagraph>
  Card composes headers, footers, backgrounds, and content into a sizable,
  theme-aware container.
</IntroParagraph>

<HeroContainer>
  <CardDemo />
</HeroContainer>

```tsx hero template=Card

```

<Highlights
  features={[
    `Size prop shared with Card children`,
    `Backgrounds and borders from the surrounding theme`,
    `Background component with built-in positioning`,
  ]}
/>

## Installation

Card is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/card
```

## Anatomy

```tsx
import { Card } from 'tamagui' // or '@tamagui/card'

export default () => (
  <Card>
    <Card.Header />
    <Card.Footer />
    {/* any other components */}
    <Card.Background />
  </Card>
)
```

## API reference

### Card

Frame of the card, extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'size',
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      required: false,
      description: `Drives the frame's border radius and the Header/Footer padding, and is published to the parts through context.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Header

Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Footer

Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Card.Background

Extends [YStack](/ui/stacks), set to `position="absolute"` and `inset={0}` with `zIndex` below Header/Footer.

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/tabs/1.7.0

---
title: Tabs
description: Use in pages to manage sub-pages.
name: tabs
component: Tabs
package: tabs
demoName: Tabs
---

<HeroContainer>
  <TabsDemo />
</HeroContainer>

```tsx hero template=Tabs

```

<Highlights
  features={[
    `Accessible, composable, customizable, and animatable`,
    `Sizing with controlled or uncontrolled state`,
    `Automatic and manual activation on web`,
    `Full keyboard navigation`,
  ]}
/>

Note: Tabs have landed on v1.7 and not fully ready for runtime. Send us your feedback and we'll address it. We're marking it Beta a such as there may be hopefully minimal breaking changes as we get feedback on the API.

## Usage

```tsx
import { SizableText, Tabs } from 'tamagui'

export default () => (
  <Tabs defaultValue="tab1" width={400}>
    <Tabs.List gap="4">
      <Tabs.Tab value="tab1">
        <SizableText>Tab 1</SizableText>
      </Tabs.Tab>
      <Tabs.Tab value="tab2">
        <SizableText>Tab 2</SizableText>
      </Tabs.Tab>
    </Tabs.List>

    <Tabs.Content value="tab1">
      <H5>Tab 1</H5>
    </Tabs.Content>
    <Tabs.Content value="tab2">
      <H5>Tab 2</H5>
    </Tabs.Content>
  </Tabs>
)
```

## API Reference

### Tabs

Root tabs component. Extends `View`. Passing the `size` prop to this component will have effect on the descendants.

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the selected tab, if controlled`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `The value of the tab to select by default, if uncontrolled`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `A function called when a new tab is selected`,
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      default: 'horizontal',
      description: `The orientation the tabs are layed out`,
    },
    {
      name: 'dir',
      type: '"ltr" | "rtl"',
      description: `The direction of navigation between toolbar items`,
    },
    {
      name: 'activationMode',
      type: '"manual" | "automatic"',
      default: 'automatic',
      description: `Whether or not a tab is activated automatically or manually. Not applicable on mobile`,
    },
  ]}
/>

### Tabs.List

Container for the trigger buttons. Supports scrolling by extending [Group](/docs/components/group). You can disable passing border radius to children by passing `disablePassBorderRadius`.

<PropsTable
  data={[
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether or not to loop over after reaching the end or start of the items. Used mainly for managing keyboard navigation`,
    },
  ]}
/>

### Tabs.Trigger

Extends [Button](/docs/components/button), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the tabs state to be changed to after activation of the trigger`,
    },
    {
      name: 'onInteraction',
      type: `(type: InteractionType, layout: TabTriggerLayout | null) => void`,
      description: `Used for making custom indicators when trigger interacted with`,
    },
    {
      name: 'unstyled',
      type: `boolean`,
      description: `When true, remove all default tamagui styling`,
    },
  ]}
/>

### Tabs.Content

Where each tab's content will be shown. Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `Will show the content when the value matches the state of Tabs root`,
    },
    {
      name: 'forceMount',
      type: 'boolean',
      default: 'false',
      description: `Used to force mounting when more control is needed. Useful when controlling animation with Tamagui animations`,
    },
  ]}
/>

## Examples

### Animations

Here is a demo with more advanced animations using [AnimatePresence](/docs/core/animations#animatepresence-and-exitstyle) and [Trigger](#trigger)'s `onInteraction` prop.

<HeroContainer noPad showAnimationDriverControl>
  <TabsAdvancedDemo />
</HeroContainer>

```tsx hero template=TabsAdvanced

```


## components/tabs/2.0.0

---
title: Tabs
description: Use in pages to manage sub-pages
name: tabs
component: Tabs
package: tabs
demoName: Tabs
---

<HeroContainer>
  <TabsDemo />
</HeroContainer>

```tsx hero template=Tabs

```

<Highlights
  features={[
    `Accessible, composable, customizable, and animatable`,
    `Sizing with controlled or uncontrolled state`,
    `Automatic and manual activation modes`,
    `Full keyboard navigation`,
  ]}
/>

## Installation

Tabs is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tabs
```

## Usage

```tsx
import { SizableText, Tabs } from 'tamagui'

export default () => (
  <Tabs defaultValue="tab1" width={400}>
    <Tabs.List>
      <Tabs.Tab value="tab1">
        <SizableText>Tab 1</SizableText>
      </Tabs.Tab>
      <Tabs.Tab value="tab2">
        <SizableText>Tab 2</SizableText>
      </Tabs.Tab>
    </Tabs.List>

    <Tabs.Content value="tab1">
      <H5>Tab 1</H5>
    </Tabs.Content>
    <Tabs.Content value="tab2">
      <H5>Tab 2</H5>
    </Tabs.Content>
  </Tabs>
)
```

### Headless Usage

To use headless tabs without `@tamagui/core`, install `@tamagui/tabs-headless`:

```bash
npm install @tamagui/tabs-headless
```

The `useTabs` hook provides all the state and accessibility props needed to build custom tabs with any styling solution:

```tsx
import { useTabs } from '@tamagui/tabs-headless'

function MyTabs() {
  const { tabsProps, listProps, getTabProps, getContentProps, value } = useTabs({
    defaultValue: 'tab1',
    orientation: 'horizontal',
  })

  return (
    <div {...tabsProps}>
      <div {...listProps}>
        <button {...getTabProps('tab1')}>Tab 1</button>
        <button {...getTabProps('tab2')}>Tab 2</button>
      </div>

      <div {...getContentProps('tab1')}>{value === 'tab1' && <p>Content 1</p>}</div>
      <div {...getContentProps('tab2')}>{value === 'tab2' && <p>Content 2</p>}</div>
    </div>
  )
}
```

## API Reference

### Tabs

Root tabs component. Extends View. Passing the `size` prop to this component will affect the descendants.

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the selected tab, if controlled.`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `The value of the tab to select by default, if uncontrolled.`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `A function called when a new tab is selected.`,
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      default: 'horizontal',
      description: `The orientation the tabs are laid out in.`,
    },
    {
      name: 'dir',
      type: '"ltr" | "rtl"',
      description: `The direction of navigation between toolbar items.`,
    },
    {
      name: 'activationMode',
      type: '"manual" | "automatic"',
      default: 'automatic',
      description: `Whether a tab is activated automatically (on focus) or manually (on click/enter). Automatic activation is web-only; native always activates manually.`,
    },
    {
      name: 'size',
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | SizeTokens",
      default: 'true',
      description: `Sets the size of the tab triggers. Passed down via context to all Tabs.Tab children.`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether keyboard navigation should loop from last to first and vice versa.`,
    },
  ]}
/>

### Tabs.List

Container for the trigger buttons. Supports scrolling by extending [Group](/docs/components/group). You can disable passing border radius to children by passing `disablePassBorderRadius`.

<PropsTable
  data={[
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether or not to loop over after reaching the end or start of the items. Used mainly for managing keyboard navigation.`,
    },
  ]}
/>

<Notice>
  Since Tabs.List extends Group, the same limitation applies: automatic border radius
  detection only works when `Tabs.Tab` is a **direct child** of `Tabs.List`. If you wrap
  tabs in custom components, see the [Group docs on nested
  items](/docs/components/group#custom-components--nested-items) for workarounds.
</Notice>

### Tabs.Tab

Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the tabs state to be changed to after activation of the trigger.`,
    },
    {
      name: 'onInteraction',
      type: `(type: InteractionType, layout: TabLayout | null) => void`,
      description: `Used for making custom indicators when trigger is interacted with.`,
    },
    {
      name: 'disabled',
      type: `boolean`,
      description: `Whether the tab is disabled.`,
    },
    {
      name: 'unstyled',
      type: `boolean`,
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'activeStyle',
      type: `StylePiece`,
      description: `Styles to apply when the tab is selected. Accepts a style() piece.`,
    },
    {
      name: 'activeTheme',
      type: `string | null`,
      description: `Theme to apply when the tab is selected. Set to null for no theme change.`,
    },
  ]}
/>

### Tabs.Content

Where each tab's content will be shown. Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `Will show the content when the value matches the state of Tabs root.`,
    },
    {
      name: 'forceMount',
      type: 'boolean',
      default: 'false',
      description: `Used to force mounting when more control is needed. Useful when controlling animation with Tamagui animations.`,
    },
  ]}
/>

## Headless Props

### useTabs Return Value

| Property          | Type                                            | Description                           |
| ----------------- | ----------------------------------------------- | ------------------------------------- |
| `value`           | `string`                                        | The currently selected tab value      |
| `setValue`        | `(value: string) => void`                       | Function to change the selected tab   |
| `direction`       | `'ltr' \| 'rtl'`                                | The resolved text direction           |
| `tabsProps`       | `object`                                        | Props to spread on the tabs container |
| `listProps`       | `object`                                        | Props to spread on the tab list       |
| `getTabProps`     | `(value: string, disabled?: boolean) => object` | Get props for a tab trigger           |
| `getContentProps` | `(value: string) => object`                     | Get props for a tab content panel     |
| `contextValue`    | `TabsContextValue`                              | Context value for component-based API |

### useTab

Hook for individual tab triggers when using the component-based API.

```tsx
const { isSelected, tabProps } = useTab({
  value: 'tab1',
  disabled: false,
  onPress: () => {},
  onKeyDown: () => {},
  onFocus: () => {},
})
```

### useTabContent

Hook for tab content panels when using the component-based API.

```tsx
const { isSelected, shouldMount, contentProps } = useTabContent({
  value: 'tab1',
  forceMount: false,
})
```

## Examples

### Animations

Here is a demo with more advanced animations using [AnimatePresence](/docs/core/animations#animatepresence-and-exitstyle) and [Tab](#tabstab)'s `onInteraction` prop.

<HeroContainer noPad showAnimationDriverControl>
  <TabsAdvancedDemo />
</HeroContainer>

```tsx hero template=TabsAdvanced

```


## components/tabs/3.0.0

---
title: Tabs
description: Use in pages to manage sub-pages
name: tabs
component: Tabs
package: tabs
demoName: Tabs
---

<IntroParagraph>
  Tabs organizes related panels behind a controlled or uncontrolled,
  keyboard-navigable list of triggers.
</IntroParagraph>

<HeroContainer>
  <TabsDemo />
</HeroContainer>

```tsx hero template=Tabs

```

<Highlights
  features={[
    `Accessible, composable, customizable, and animatable`,
    `Sizing with controlled or uncontrolled state`,
    `Automatic and manual activation modes`,
    `Full keyboard navigation`,
  ]}
/>

## Installation

Tabs is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tabs
```

## Usage

```tsx
import { SizableText, Tabs } from 'tamagui'

export default () => (
  <Tabs defaultValue="tab1" width={400}>
    <Tabs.List>
      <Tabs.Tab value="tab1">
        <SizableText>Tab 1</SizableText>
      </Tabs.Tab>
      <Tabs.Tab value="tab2">
        <SizableText>Tab 2</SizableText>
      </Tabs.Tab>
    </Tabs.List>

    <Tabs.Content value="tab1">
      <H5>Tab 1</H5>
    </Tabs.Content>
    <Tabs.Content value="tab2">
      <H5>Tab 2</H5>
    </Tabs.Content>
  </Tabs>
)
```

### Headless usage

To use headless tabs without `@tamagui/core`, install `@tamagui/tabs-headless`:

```bash
npm install @tamagui/tabs-headless
```

The `useTabs` hook provides all the state and accessibility props needed to build custom tabs with any styling solution:

```tsx
import { useTabs } from '@tamagui/tabs-headless'

function MyTabs() {
  const { tabsProps, listProps, getTabProps, getContentProps, value } = useTabs({
    defaultValue: 'tab1',
    orientation: 'horizontal',
  })

  return (
    <div {...tabsProps}>
      <div {...listProps}>
        <button {...getTabProps('tab1')}>Tab 1</button>
        <button {...getTabProps('tab2')}>Tab 2</button>
      </div>

      <div {...getContentProps('tab1')}>{value === 'tab1' && <p>Content 1</p>}</div>
      <div {...getContentProps('tab2')}>{value === 'tab2' && <p>Content 2</p>}</div>
    </div>
  )
}
```

## API reference

### Tabs

Root tabs component. Extends View. Passing the `size` prop to this component will affect the descendants.

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the selected tab, if controlled.`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `The value of the tab to select by default, if uncontrolled.`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `A function called when a new tab is selected.`,
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      default: 'horizontal',
      description: `The orientation the tabs are laid out in.`,
    },
    {
      name: 'dir',
      type: '"ltr" | "rtl"',
      description: `The direction of navigation between toolbar items.`,
    },
    {
      name: 'activationMode',
      type: '"manual" | "automatic"',
      default: 'automatic',
      description: `Whether a tab is activated automatically (on focus) or manually (on click/enter). Automatic activation is web-only; native always activates manually.`,
    },
    {
      name: 'size',
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      default: 'md',
      description: `Sets the size of the tab triggers. Passed down via context to all Tabs.Tab children.`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether keyboard navigation should loop from last to first and vice versa.`,
    },
  ]}
/>

### Tabs.List

Container for the trigger buttons. Supports scrolling by extending [Group](/ui/group).

<PropsTable
  data={[
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether or not to loop over after reaching the end or start of the items. Used mainly for managing keyboard navigation.`,
    },
  ]}
/>

<Notice>
  Since Tabs.List extends Group, the same limitation applies: automatic border radius
  detection only works when `Tabs.Tab` is a **direct child** of `Tabs.List`. If you wrap
  tabs in custom components, see the [Group docs on nested
  items](/ui/group#custom-components--nested-items) for workarounds.
</Notice>

### Tabs.Tab

Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the tabs state to be changed to after activation of the trigger.`,
    },
    {
      name: 'onInteraction',
      type: `(type: InteractionType, layout: TabLayout | null) => void`,
      description: `Used for making custom indicators when trigger is interacted with.`,
    },
    {
      name: 'disabled',
      type: `boolean`,
      description: `Whether the tab is disabled.`,
    },
    {
      name: 'unstyled',
      type: `boolean`,
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'activeStyle',
      type: `StylePiece`,
      description: `Styles to apply when the tab is selected. Accepts a style() piece.`,
    },
    {
      name: 'activeTheme',
      type: `string | null`,
      description: `Theme to apply when the tab is selected. Set to null for no theme change.`,
    },
  ]}
/>

### Tabs.Content

Where each tab's content will be shown. Extends [YStack](/ui/stacks), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `Will show the content when the value matches the state of Tabs root.`,
    },
    {
      name: 'forceMount',
      type: 'boolean',
      default: 'false',
      description: `Used to force mounting when more control is needed. Useful when controlling animation with Tamagui animations.`,
    },
  ]}
/>

## Headless props

### useTabs return value

| Property          | Type                                            | Description                           |
| ----------------- | ----------------------------------------------- | ------------------------------------- |
| `value`           | `string`                                        | The currently selected tab value      |
| `setValue`        | `(value: string) => void`                       | Function to change the selected tab   |
| `direction`       | `'ltr' \| 'rtl'`                                | The resolved text direction           |
| `tabsProps`       | `object`                                        | Props to spread on the tabs container |
| `listProps`       | `object`                                        | Props to spread on the tab list       |
| `getTabProps`     | `(value: string, disabled?: boolean) => object` | Get props for a tab trigger           |
| `getContentProps` | `(value: string) => object`                     | Get props for a tab content panel     |
| `contextValue`    | `TabsContextValue`                              | Context value for component-based API |

### useTab

Hook for individual tab triggers when using the component-based API.

```tsx
const { isSelected, tabProps } = useTab({
  value: 'tab1',
  disabled: false,
  onPress: () => {},
  onKeyDown: () => {},
  onFocus: () => {},
})
```

### useTabContent

Hook for tab content panels when using the component-based API.

```tsx
const { isSelected, shouldMount, contentProps } = useTabContent({
  value: 'tab1',
  forceMount: false,
})
```

## Examples

### Animations

Here is a demo with more advanced animations using [AnimatePresence](/docs/core/animations#enterexit-transitions) and [Tabs.Tab](#tabstab)'s `onInteraction` prop.

<HeroContainer noPad showAnimationDriverControl>
  <TabsAdvancedDemo />
</HeroContainer>

```tsx hero template=TabsAdvanced

```


## components/tabs/1.125.35

---
title: Tabs
description: Use in pages to manage sub-pages.
name: tabs
component: Tabs
package: tabs
demoName: Tabs
---

<Tabs id="type" defaultValue="styled">
  <Tabs.List>
    <TooltipSimple label="With Tamagui's default styles">
      <Tabs.Tab value="styled">Styled</Tabs.Tab>
    </TooltipSimple>
    <TooltipSimple label="No dependency on Tamagui's core">
      <Tabs.Tab value="headless">Headless</Tabs.Tab>
    </TooltipSimple>
  </Tabs.List>
</Tabs>

<Tabs.Content value="styled">
  <HeroContainer>
    <TabsDemo />
  </HeroContainer>

```tsx hero template=Tabs

```

<Highlights
  features={[
    `Accessible, composable, customizable, and animatable`,
    `Sizing with controlled or uncontrolled state`,
    `Automatic and manual activation on web`,
    `Full keyboard navigation`,
  ]}
/>

Note: Tabs have landed on v1.7 and not fully ready for runtime. Send us your feedback and we'll address it. We're marking it Beta a such as there may be hopefully minimal breaking changes as we get feedback on the API.

## Installation

Tabs is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tabs
```

## Usage

```tsx
import { SizableText, Tabs } from 'tamagui'

export default () => (
  <Tabs defaultValue="tab1" width={400}>
    <Tabs.List space>
      <Tabs.Tab value="tab1">
        <SizableText>Tab 1</SizableText>
      </Tabs.Tab>
      <Tabs.Tab value="tab2">
        <SizableText>Tab 2</SizableText>
      </Tabs.Tab>
    </Tabs.List>

    <Tabs.Content value="tab1">
      <H5>Tab 1</H5>
    </Tabs.Content>
    <Tabs.Content value="tab2">
      <H5>Tab 2</H5>
    </Tabs.Content>
  </Tabs>
)
```

## API Reference

### Tabs

Root tabs component. Extends `View`. Passing the `size` prop to this component will have effect on the descendants.

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the selected tab, if controlled`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `The value of the tab to select by default, if uncontrolled`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `A function called when a new tab is selected`,
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      default: 'horizontal',
      description: `The orientation the tabs are laid out.`,
    },
    {
      name: 'dir',
      type: '"ltr" | "rtl"',
      description: `The direction of navigation between toolbar items`,
    },
    {
      name: 'activationMode',
      type: '"manual" | "automatic"',
      default: 'automatic',
      description: `Whether or not a tab is activated automatically or manually. Not applicable on mobile`,
    },
  ]}
/>

### Tabs.List

Container for the trigger buttons. Supports scrolling by extending [Group](/docs/components/group). You can disable passing border radius to children by passing `disablePassBorderRadius`.

<PropsTable
  data={[
    {
      name: 'loop',
      type: 'boolean',
      default: 'true',
      description: `Whether or not to loop over after reaching the end or start of the items. Used mainly for managing keyboard navigation`,
    },
  ]}
/>

### Tabs.Tab

The clickable tab button that activates its corresponding content. Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the tabs state to be changed to after activation of the tab`,
    },
    {
      name: 'onInteraction',
      type: `(type: InteractionType, layout: TabLayout | null) => void`,
      description: `Used for making custom indicators when tab is interacted with. InteractionType is 'select' | 'focus' | 'hover'`,
    },
    {
      name: 'disabled',
      type: `boolean`,
      description: `When true, prevents user interaction with the tab`,
    },
    {
      name: 'disableActiveTheme',
      type: `boolean`,
      description: `When true, disables applying the 'active' theme when the tab is selected`,
    },
    {
      name: 'unstyled',
      type: `boolean`,
      description: `When true, remove all default tamagui styling`,
    },
  ]}
/>

### Tabs.Trigger

<Aside type="deprecated">
  Use `Tabs.Tab` instead. `Tabs.Trigger` is an alias kept for backwards compatibility.
</Aside>

Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `The value for the tabs state to be changed to after activation of the trigger`,
    },
    {
      name: 'onInteraction',
      type: `(type: InteractionType, layout: TabLayout | null) => void`,
      description: `Used for making custom indicators when trigger interacted with`,
    },
    {
      name: 'unstyled',
      type: `boolean`,
      description: `When true, remove all default tamagui styling`,
    },
  ]}
/>

### Tabs.Content

Where each tab's content will be shown. Extends [ThemeableStack](/docs/components/stacks#themeablestack), adding:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `Will show the content when the value matches the state of Tabs root`,
    },
    {
      name: 'forceMount',
      type: 'boolean',
      default: 'false',
      description: `Used to force mounting when more control is needed. Useful when controlling animation with Tamagui animations`,
    },
  ]}
/>

## Examples

### Animations

Here is a demo with more advanced animations using [AnimatePresence](/docs/core/animations#animatepresence-and-exitstyle) and [Trigger](#trigger)'s `onInteraction` prop.

<HeroContainer noPad showAnimationDriverControl>
  <TabsAdvancedDemo />
</HeroContainer>

```tsx hero template=TabsAdvanced

```

</Tabs.Content>

<Tabs.Content value="headless">
  <HeroContainer>
    <TabsCustomDemo />
  </HeroContainer>

```tsx hero template=TabsCustom

```

### Customization Options

When using `createTabs`, you need to provide three styled components:

- `TabsFrame`: The root container component
- `TabFrame`: The tab trigger component
- `ContentFrame`: The content container component

The created tabs component will maintain all the accessibility features and keyboard navigation while allowing you to have complete control over the visual presentation.

The headless API gives you the foundation to build completely custom tab interfaces while maintaining accessibility and interaction patterns. You can integrate it with your design system and add any custom behaviors you need.

</Tabs.Content>


## components/toggle-group/1.10.0

---
title: ToggleGroup
description: Two-state buttons that can be toggled on or off.
name: toggleGroup
component: ToggleGroup
package: toggle-group
demoName: ToggleGroup
---

<HeroContainer>
  <ToggleGroupDemo />
</HeroContainer>

```tsx hero template=ToggleGroup

```

<Highlights
  features={[
    `Full keyboard navigation`,
    `Horizontal and vertical orientation`,
    `Single or multiple pressed buttons`,
    `Controlled or uncontrolled state`,
  ]}
/>

## Installation

ToggleGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/toggle-group
```

## Usage

```tsx
import { ToggleGroup } from 'tamagui'

export default () => {
  return (
    <ToggleGroup type="single">
      <ToggleGroup.Item value="foo"></ToggleGroup.Item>
      <ToggleGroup.Item value="bar"></ToggleGroup.Item>
    </ToggleGroup>
  )
}
```

## API Reference

### ToggleGroup

`ToggleGroup` extends the [Group](/docs/components/group) component. You can disable passing border radius to children by passing `disablePassBorderRadius`. plus:

<PropsTable
  data={[
    {
      name: 'asChild',
      type: 'boolean',
      description: `When true, Tamagui expects a single child element. Instead of rendering its own element, it will pass all props to that child, merging together any event handling props.`,
      default: `false`,
    },
    {
      name: 'type',
      type: 'enum',
      description: `Determines whether a single or multiple items can be pressed at a time.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `The controlled value of the pressed item when type is "single". Must be used in conjunction with onValueChange.`,
    },
    {
      name: 'defaultValue',
      description: 'The values of the items to show as pressed when initially rendered.',
      type: 'string',
      default: ``,
    },
    {
      name: 'orientation',
      type: 'enum',
      description: `The orientation of the component, which determines how focus moves: horizontal for left/right arrows and vertical for up/down arrows.`,
      default: `horizontal`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `When true, prevents the user from interacting with the toggle group and all its items.`,
      default: `false`,
    },
    {
      name: 'onValueChange',
      type: '(value: string[]) => void',
      description: `Event handler called when the pressed state of an item changes and type is "multiple".`,
    },
    {
      name: 'loop',
      type: 'boolean',
      description: `Whether or not to loop over after reaching the end or start of the items. Used mainly for managing keyboard navigation.`,
      default: `true`,
    },
    {
      name: 'disableDeactivation',
      type: 'boolean',
      description: `Won't let the user turn the active item off. Only applied to single toggle group.`,
      default: 'false',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
    {
      name: 'sizeAdjust',
      type: 'number',
      description: `Adjust the component's size scaling by this number.`,
    },
  ]}
/>

### ToggleGroup.Item

`ToggleGroup.Item` extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'asChild',
      type: 'boolean',
      description: `When true, Tamagui expects a single child element. Instead of rendering its own element, it will pass all props to that child, merging together any event handling props.`,
      default: `false`,
    },
    {
      name: 'value',
      type: 'string',
      description: `The controlled value of the pressed item when type is "single".`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `When true, prevents the user from interacting with the toggle group item.`,
      default: `false`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

When it is active, it will receive an `active` prop set to true. This means you can customize the active styles like so:

```tsx
import { ToggleGroup } from '@tamagui/toggle-group'
import { styled } from 'tamagui'

const MyToggleGroupItem = styled(ToggleGroup.Item, {
  variants: {
    active: {
      true: {
        backgroundColor: 'red',
      },
    },
  },
})
```


## components/toggle-group/2.0.0

---
title: ToggleGroup
description: Two-state buttons that can be toggled on or off
name: toggleGroup
component: ToggleGroup
package: toggle-group
demoName: ToggleGroup
---

<IntroParagraph>
  ToggleGroup arranges two-state buttons into a keyboard-navigable single or
  multiple selection control.
</IntroParagraph>

<HeroContainer>
  <ToggleGroupDemo />
</HeroContainer>

```tsx hero template=ToggleGroup

```

<Highlights
  features={[
    `Full keyboard navigation`,
    `Horizontal and vertical orientation`,
    `Single or multiple pressed buttons`,
    `Controlled or uncontrolled state`,
  ]}
/>

## Installation

ToggleGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/toggle-group
```

## Usage

ToggleGroup handles the toggle state logic. For visual grouping with border radius, compose with `XGroup` or `YGroup`. Use `activeStyle` to customize the active state appearance:

```tsx
import { ToggleGroup, XGroup, style } from 'tamagui'

const activeItemStyle = style({ backgroundColor: 'color-5' })

export default () => {
  return (
    <ToggleGroup type="single">
      <XGroup>
        <XGroup.Item>
          <ToggleGroup.Item
            value="foo"
            borderRadius="4"
            activeStyle={activeItemStyle}
          >
            Foo
          </ToggleGroup.Item>
        </XGroup.Item>
        <XGroup.Item>
          <ToggleGroup.Item
            value="bar"
            borderRadius="4"
            activeStyle={activeItemStyle}
          >
            Bar
          </ToggleGroup.Item>
        </XGroup.Item>
      </XGroup>
    </ToggleGroup>
  )
}
```

For vertical layouts, use `YGroup`:

```tsx
<ToggleGroup type="single" orientation="vertical">
  <YGroup>
    <YGroup.Item>
      <ToggleGroup.Item value="top" borderRadius="4">
        Top
      </ToggleGroup.Item>
    </YGroup.Item>
    <YGroup.Item>
      <ToggleGroup.Item value="bottom" borderRadius="4">
        Bottom
      </ToggleGroup.Item>
    </YGroup.Item>
  </YGroup>
</ToggleGroup>
```

## API reference

### ToggleGroup

ToggleGroup manages toggle state and keyboard navigation. It does not render any visible element by default. Use `XGroup`/`YGroup` for visual grouping.

<PropsTable
  data={[
    {
      name: 'type',
      type: '"single" | "multiple"',
      description: `Determines whether a single or multiple items can be pressed at a time.`,
    },
    {
      name: 'value',
      type: 'string | string[]',
      description: `The controlled value of the pressed item(s). Use string for type="single", string[] for type="multiple".`,
    },
    {
      name: 'defaultValue',
      description: 'The value of the item(s) to show as pressed when initially rendered.',
      type: 'string | string[]',
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      description: `The orientation of the component, which determines how focus moves: horizontal for left/right arrows and vertical for up/down arrows.`,
      default: `"horizontal"`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `When true, prevents the user from interacting with the toggle group and all its items.`,
      default: `false`,
    },
    {
      name: 'onValueChange',
      type: '(value: string | string[]) => void',
      description: `Event handler called when the pressed state of an item changes.`,
    },
    {
      name: 'loop',
      type: 'boolean',
      description: `Whether or not to loop over after reaching the end or start of the items. Used for keyboard navigation.`,
      default: `true`,
    },
    {
      name: 'disableDeactivation',
      type: 'boolean',
      description: `Won't let the user turn the active item off. Only applies to type="single".`,
      default: 'false',
    },
    {
      name: 'rovingFocus',
      type: 'boolean',
      description: `Enable roving focus keyboard navigation between items.`,
      default: 'true',
    },
  ]}
/>

### ToggleGroup.Item

`ToggleGroup.Item` extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `A unique value for this toggle item.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `When true, prevents the user from interacting with this item.`,
      default: `false`,
    },
    {
      name: 'activeStyle',
      type: 'StylePiece',
      description: `Style piece applied when the item is in its active/pressed state. Accepts a style() piece.`,
    },
    {
      name: 'activeTheme',
      type: 'string | null',
      description: `Theme to apply when the item is active. Set to null for no theme change.`,
    },
  ]}
/>

### Styling active state

Customize the active/pressed state using `activeStyle`:

```tsx
const greenActiveStyle = style({
  backgroundColor: 'green-500',
})

// Usage on ToggleGroup.Item
<ToggleGroup.Item value="left" activeStyle={greenActiveStyle}>
  Left
</ToggleGroup.Item>

// Or via styled()
const GreenItem = styled(ToggleGroup.Item, {
  activeStyle: greenActiveStyle,
})
```

You can also use `activeTheme` to apply a theme when active:

```tsx
<ToggleGroup.Item value="option1" activeTheme="green">
  Option 1
</ToggleGroup.Item>
```

### useToggleGroupItem

For custom components inside `ToggleGroup.Item` that need to know the active state, use the `useToggleGroupItem` hook:

```tsx
import { useToggleGroupItem, ToggleGroup } from '@tamagui/toggle-group'

function CustomLabel({ children }) {
  const { active, color } = useToggleGroupItem()
  return <html.span color={active ? 'green-10' : 'color'}>{children}</html.span>
}

// Usage
;<ToggleGroup.Item value="option1">
  <CustomLabel>Option 1</CustomLabel>
</ToggleGroup.Item>
```


## components/form/1.3.0

---
title: Form
description: A simple form component for native and web.
name: form
component: Form
package: form
demoName: Form
---

<HeroContainer>
  <FormsDemo />
</HeroContainer>

```tsx hero template=Forms

```

<Highlights
  features={[
    `Native and web support`,
    `Accessible form output`,
    `All Tamagui props supported`,
  ]}
/>

## Installation

Form is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/form
```

## Anatomy

```tsx
import { Form } from 'tamagui' // or '@tamagui/form'

export default () => (
  <Form>
    {/* ... */}
    <Form.Trigger asChild>
      <Button />
    </Form.Trigger>
  </Form>
)
```

## API Reference

### Form

<PropsTable
  data={[
    {
      name: 'onSubmit',
      type: '() => void',
      required: true,
      description: `Must use Form.Trigger to ensure onSubmit will callback.`,
    },
  ]}
/>

### Form.Trigger

Wrap this around your submitting element to make the form submit. We recommend using `asChild` to a child element of your choosing for more control.

Accepts [Tamagui Props](/docs/intro/props).


## components/form/2.0.0

---
title: Form
description: A simple form component for native and web
name: form
component: Form
package: form
demoName: Form
---

<HeroContainer>
  <FormsDemo />
</HeroContainer>

```tsx hero template=Forms

```

<Highlights
  features={[
    `Native and web support`,
    `Accessible form output`,
    `All Tamagui props supported`,
  ]}
/>

## Installation

Form is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/form
```

## Anatomy

```tsx
import { Form } from 'tamagui' // or '@tamagui/form'

export default () => (
  <Form>
    {/* ... */}
    <Form.Trigger asChild>
      <Button />
    </Form.Trigger>
  </Form>
)
```

## API Reference

### Form

<PropsTable
  data={[
    {
      name: 'onSubmit',
      type: '() => void',
      required: true,
      description: `Must use \`Form.Trigger\` to ensure \`onSubmit\` will be called.`,
    },
  ]}
/>

### Form.Trigger

Wrap this around your submitting element to make the form submit. We recommend using `asChild` to a child element of your choosing for more control.

Accepts [Tamagui Props](/docs/intro/props).


## components/form/3.0.0

---
title: Form
description: Collect and validate fields on native and web
name: form
component: Form
package: form
demoName: Form
---

<IntroParagraph>
  Form collects values and coordinates validation, focus, and submission with
  the same component tree on web and native.
</IntroParagraph>

<HeroContainer>
  <FormsDemo />
</HeroContainer>

```tsx hero template=Forms

```

<Highlights
  features={[
    `Field value collection on native and web`,
    `Automatic focus on the first invalid control`,
    `Shared bridge for server and form-library errors`,
    `Cross-platform submission through Form.Trigger`,
  ]}
/>

Form coordinates registered [Fields](/ui/field). It validates synchronously,
projects their values by name, focuses the first invalid control, and then calls
`onSubmit(values, details)`.

## Installation

Form is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/form
```

## Usage

```tsx
import { Button, Field, Form } from 'tamagui'

export function AccountForm() {
  return (
    <Form
      validationMode="onSubmit"
      onSubmit={(values, details) => {
        console.log(values.email, details.reason)
      }}
    >
      <Field name="email">
        <Field.Label>Email</Field.Label>
        <EmailInput required />
        <Field.Error />
      </Field>

      <Form.Trigger asChild>
        <Button>Create account</Button>
      </Form.Trigger>
    </Form>
  )
}
```

The callback receives values from every registered Field with a `name`:

```ts
{
  email: 'ada@example.com',
  displayName: 'Ada'
}
```

The second argument is a `TamaguiEventDetails` with reason `submit` for a
native form submission or `trigger-press` for Form.Trigger.

## Validation and focus

Form validates every registered field before calling `onSubmit`. Async
validators are started but never delay the submit attempt. Synchronous
validation and previously committed errors can stop submission.

When a field is invalid, Form focuses the first registered control. Text inputs
are also selected on web. Native focus uses the `@tamagui/focusable` registry.

Set the default validation boundary on Form:

```tsx
<Form validationMode="onBlur">{/* fields */}</Form>
```

An individual Field can override it.

## Server errors

Pass an error record keyed by Field name:

```tsx
const [errors, setErrors] = useState({})

<Form
  errors={errors}
  onSubmit={async (values) => {
    const result = await createAccount(values)
    setErrors(result.errors)
  }}
>
  {/* fields */}
</Form>
```

Server errors participate in invalid styling, accessible error messages, and
first-invalid focus. An error clears when that field is edited. If errors arrive
after a submit, Form focuses the first matching field again.

The same prop is the bridge for React Hook Form or TanStack Form:

```tsx
const {
  formState: { errors },
} = useForm()

const fieldErrors = Object.fromEntries(
  Object.entries(errors).map(([name, error]) => [name, error?.message])
)

<Form errors={fieldErrors}>{/* Field presentation around library controls */}</Form>
```

## Imperative validation

Use `actionsRef` to validate every field or one field by name:

```tsx
const actionsRef = useRef<Form.Actions>(null)

<Form actionsRef={actionsRef}>{/* ... */}</Form>

actionsRef.current?.validate()
actionsRef.current?.validate('email')
```

## Anatomy

```tsx
<Form>
  {/* Fields and other content */}
  <Form.Trigger />
</Form>
```

## Migrating from Form 2

Form 3 changes `onSubmit` from a zero-argument callback to:

```ts
onSubmit(values, details)
```

Callbacks that ignore their arguments continue to work. Code that previously
read values through a second form system can usually read them from `values`
instead.

## API reference

### Form

Accepts [Tamagui Props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'onSubmit',
      type: '(values, details) => void | Promise<void>',
      description: `Called after synchronous validation passes with projected Field values and submit details.`,
    },
    {
      name: 'scope',
      type: 'string',
      description: `Names this Form so a Form.Trigger rendered elsewhere can target it.`,
    },
    {
      name: 'validationMode',
      type: `'onSubmit' | 'onBlur' | 'onChange'`,
      default: `'onSubmit'`,
      description: `Sets the default validation mode for registered Fields.`,
    },
    {
      name: 'errors',
      type: 'Record<string, string | string[]>',
      description: `External server or form-library errors keyed by Field name.`,
    },
    {
      name: 'actionsRef',
      type: 'React.RefObject<Form.Actions | null>',
      description: `Provides validate(fieldName?) for imperative validation.`,
    },
  ]}
/>

### Form.Trigger

Submits the nearest scoped Form on web and native. We recommend `asChild` when
you want to use a Button or another pressable component.

Accepts [Tamagui Props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'scope',
      type: 'string',
      description: `Targets a Form with the same scope when the trigger is composed separately.`,
    },
  ]}
/>


## components/toast/1.11.3

---
title: Toast
description: A toast component with native features
name: toast
component: Toast
package: toast
demoName: Toast
---

# Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Installation

Run the following command:

```
yarn add @tamagui/toast burnt
```

then, rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

## Usage

To display the toast natively, you should either pass an array of native platforms (`native: ["ios", "web"]`), a single platform or `true` for all platforms.

```tsx
import { Button } from 'tamagui' // or '@tamagui/button'
import { Toast, ToastProvider, useToast } from '@tamagui/toast'

export default () => (
  <ToastProvider native={['mobile']}>
    <CurrentToast />
    <MyPage />
    <ToastViewport />
  </ToastProvider>
)

const CurrentToast = () => {
  const { currentToast } = useToast()

  // only show the component if it's present and not handled by native toast
  if (!currentToast || currentToast.isHandledNatively) return null
  return (
    <Toast key={currentToast.id}>
      <Toast.Title>{currentToast.title}</Toast.Title>
      <Toast.Description>{currentToast.message}</Toast.Description>
    </Toast>
  )
}

const MyPage = () => {
  const { show } = useToast()

  return (
    <Button onPress={() => show('Done!', { message: 'Form submitted successfully.' })}>
      Show Toast
    </Button>
  )
}
```

## API

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
    {
      name: 'native',
      required: false,
      type: 'boolean | ToastNativePlatform | ToastNativePlatform[]',
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
    },
    {
      name: `burntOptions`,
      required: false,
      type: `Omit<BurntToastOptions, 'title' | 'message' | 'duration'>`,
      description: `Options for the burnt package if you're using native toasts on mobile`,
    },
    {
      name: `notificationOptions`,
      required: false,
      type: `NotificationOptions`,
      description: `Options for the notification API if you're using native toasts on web`,
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be used inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be used inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
  ]}
/>

#### Toast.Title

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Description

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Close

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

#### Toast.Action

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### useToast

Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Returns"
  data={[
    {
      name: 'currentToast',
      type: 'ToastData | null',
      description: `The information about the current toast to show such as title, message, duration, etc.`,
    },
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
  ]}
/>

## FAQ

#### How to change the placement of toasts?

Native toasts:

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastProvider burntOptions={{ from: 'bottom' }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

Non-native toasts:

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

#### How to show non-native toasts within safe area on mobile?

Install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

#### Can I send toasts to different toast viewports?

Yes, but you will have to name them and then reference the viewport name on the `<Toast>` component. for instance:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> {/* name will be "default" */}
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}

const MyComponent = () => {
  return <Toast>{/* goes to default viewport */}</Toast>
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}
```

#### How can I have more control over toasts?

You will have to opt-out of the native toasts and only use custom ones. Here are some examples:

##### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

##### Multiple Toasts

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```


## components/toast/1.9.1

---
title: Toast
description: A toast component with native features
name: toast
component: Toast
package: toast
demoName: Toast
---

# Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Usage

### Imperative API

This API offers a nice imperative interface, support for native toasts with a lot of control.

#### Installation

For native support on mobile, run `yarn add burnt` to add `burnt`, then rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

Note: `Burnt` [will not work](https://github.com/nandorojo/burnt?tab=readme-ov-file#expo) with Expo Go.

#### Usage

To display the toast natively, you should either pass an array of native platforms (`native: ["ios", "web"]`), a single platform or `true` for all platforms.

```tsx
import { Button } from 'tamagui' // or '@tamagui/button'
import { Toast, ToastImperativeProvider, ToastProvider, useToast } from 'tamagui' // or '@tamagui/toast'

const options = { native: 'mobile' }

export default () => (
  <ToastProvider>
    <ToastImperativeProvider options={options}>
      <CurrentToast />
      <MyPage />
    </ToastImperativeProvider>

    <ToastViewport />
  </ToastProvider>
)

const CurrentToast = () => {
  const { currentToast } = useToast()

  // only show the component if it's present and not handled by native toast
  if (!currentToast || currentToast.isHandledNatively) return null
  return (
    <Toast key={currentToast.id}>
      <Toast.Title>{currentToast.title}</Toast.Title>
      <Toast.Description>{currentToast.message}</Toast.Description>
    </Toast>
  )
}

const MyPage = () => {
  const { show } = useToast()

  return (
    <Button onPress={() => show('Done!', { message: 'Form submitted successfully.' })}>
      Show Toast
    </Button>
  )
}
```

### Barebone API

<Notice>
  This API does not support native toasts. For native toasts, use the [Imperative
  API](#imperative-api).
</Notice>

#### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

#### Multiple Toast

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```

## API

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
  ]}
/>

#### Toast.Title

Should be inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Description

Should be inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Close

Should be inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

#### Toast.Action

Should be inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### ToastImperativeProvider

Wrap components within this provider to use `useToast()` inside them.

<PropsTable
  data={[
    {
      name: 'options',
      type: 'ToastImperativeOptions',
      required: false,
      description: `Used to provide defaults to imperative API. Options can be overwritten when calling \`show()\`.`,
    },
  ]}
/>

### useToast

Used when using the imperative API.

<PropsTable
  title="Returns"
  data={[
    {
      name: 'currentToast',
      type: 'ToastData | null',
      description: `The information about the current toast to show such as title, message, duration, etc.`,
    },
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
  ]}
/>

## FAQ

#### How to change the placement of toasts?

##### Native toasts

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastImperativeProvider options={{ burntOptions: { from: 'bottom' } }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

##### Non-native toasts

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

#### How to show non-native toasts within safe area on mobile?

Install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

#### Can I have multiple viewports?

Yes, but you will have to name them and then reference the viewport name on the `<Toast>` component. for instance:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> // name will be "default"
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}

const MyComponent = () => {
  return <Toast> // goes to default viewport // ...</Toast>
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom">// ...</Toast>
}
```


## components/toast/1.83.0

---
title: Toast
description: Use to show feedback to user interactions.
name: toast
component: Toast
package: toast
demoName: Toast
---

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Installation

Note that `@tamagui/toast` is the only UI package not included by default in `tamagui`. The reason for this is that Metro would force you to install the native `burnt` dependency, and that would mean `tamagui` wouldn't work with Expo Go and would require a native install step no matter if you used Toast or not. This is due to a limitation in Metro.

To install toast:

```bash
yarn add @tamagui/toast burnt
```

Then, if targeting native, rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

We're open to a refactor that moves the burnt dependency into a sub-path like `@tamagui/toast/burnt` and forces setup through there, that likely fixes the Metro issue and allow us to include it by default.

## Anatomy

```tsx
<ToastProvider>
  <Toast>
    <Toast.Title />
    <Toast.Description />
    <Toast.Action />
    <Toast.Close />
  </Toast>

  <ToastViewport />
</ToastProvider>
```

## API Reference

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
    {
      name: 'native',
      required: false,
      type: 'boolean | ToastNativePlatform | ToastNativePlatform[]',
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
    },
    {
      name: `burntOptions`,
      required: false,
      type: `Omit<BurntToastOptions, 'title' | 'message' | 'duration'>`,
      description: `Options for the burnt package if you're using native toasts on mobile`,
    },
    {
      name: `notificationOptions`,
      required: false,
      type: `NotificationOptions`,
      description: `Options for the notification API if you're using native toasts on web`,
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be used inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
    {
      name: 'portalToRoot',
      type: 'boolean | number',
      default: 'false',
      description: `When true, uses a portal to render at the very top of the root TamaguiProvider.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be used inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Title

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Description

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Close

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### Toast.Action

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### useToastController

Used to control the display of toasts. Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Returns"
  data={[
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
    {
      name: `options`,
      type: `ToastOptions`,
      description: `You can use if need to access the toast options.`,
    },
  ]}
/>

### useToastState

Used to render out your toast contents. Should be used inside [ToastProvider](#toastprovider). Doesn't take in anything and returns `ToastData`.

```tsx
const CurrentToast = () => {
  const toast = useToastState()

  // don't show any toast if no toast is present or it's handled natively
  if (!toast || toast.isHandledNatively) {
    return null
  }

  return (
    <Toast key={toast.id} duration={toast.duration} viewport={toast.viewport}>
      <Toast.Title>{toast.title}</Toast.Title>
      <Toast.Description>{toast.message}</Toast.Description>
    </Toast>
  )
}
```

## Examples

### Position the viewport

To position the viewport on native toasts:

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastProvider burntOptions={{ from: 'bottom' }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

To position the viewport on custom toasts:

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

### Mobile safe area

To show toasts inside device's safe area, install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and then use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

### Different viewports

To send toasts to different viewports, you can set up different viewports:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> {/* default viewport */}
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}
```

And then, use the viewport's name on the toasts.

```tsx
const MyComponent = () => {
  return <Toast /> // default viewport
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}
```

### Custom data

Just pass your custom data to the second parameter of the `show()` method.

```ts
const toastController = useToastController()
toastController.show('Title', { myPreset: 'error' }) // or toastController.show("Title", { customData: { myPreset: 'error' } })
```

then, when showing the toast, you can retrieve them like so:

```ts
const toastState = useToastState()
toastState.myPreset // or toastState.customData.myPreset
```

To add TypeScript auto-completion for your custom fields, you can use TS module augmentation:

```ts
declare module '@tamagui/toast' {
  interface CustomData {
    myPreset: 'error' | 'success' | 'warning'
  }
}
```

### Without hooks

You can also use toasts without the hooks.

<Notice>You can't use native toasts this way.</Notice>

#### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

#### Multiple Toasts

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```


## components/toast/1.15.15

---
title: Toast
description: A toast component with native features
name: toast
component: Toast
package: toast
demoName: Toast
---

# Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Installation

Run the following command:

```bash
yarn add @tamagui/toast burnt
```

Then, if targeting native, rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

## Anatomy

```tsx
<ToastProvider>
  <Toast>
    <Toast.Title />
    <Toast.Description />
    <Toast.Action />
    <Toast.Close />
  </Toast>

  <ToastViewport />
</ToastProvider>
```

## API Reference

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
    {
      name: 'native',
      required: false,
      type: 'boolean | ToastNativePlatform | ToastNativePlatform[]',
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
    },
    {
      name: `burntOptions`,
      required: false,
      type: `Omit<BurntToastOptions, 'title' | 'message' | 'duration'>`,
      description: `Options for the burnt package if you're using native toasts on mobile`,
    },
    {
      name: `notificationOptions`,
      required: false,
      type: `NotificationOptions`,
      description: `Options for the notification API if you're using native toasts on web`,
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be used inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be used inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Title

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Description

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Close

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### Toast.Action

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### useToastController

Used to control the display of toasts. Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Returns"
  data={[
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
    {
      name: `options`,
      type: `ToastOptions`,
      description: `You can use if need to access the toast options.`,
    },
  ]}
/>

### useToastState

Used to render out your toast contents. Should be used inside [ToastProvider](#toastprovider). Doesn't take in anything and returns `ToastData`.

```tsx
const CurrentToast = () => {
  const toast = useToastState()

  // don't show any toast if no toast is present or it's handled natively
  if (!toast || toast.isHandledNatively) {
    return null
  }

  return (
    <Toast key={toast.id} duration={toast.duration} viewport={toast.viewport}>
      <Toast.Title>{toast.title}</Toast.Title>
      <Toast.Description>{toast.message}</Toast.Description>
    </Toast>
  )
}
```

## Examples

### Position the viewport

To position the viewport on native toasts:

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastProvider burntOptions={{ from: 'bottom' }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

To position the viewport on custom toasts:

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

### Mobile safe area

To show toasts inside device's safe area, install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and then use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

### Different viewports

To send toasts to different viewports, you can set up different viewports:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> {/* default viewport */}
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}
```

And then, use the viewport's name on the toasts.

```tsx
const MyComponent = () => {
  return <Toast /> // default viewport
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}
```

### Custom data

Just pass your custom data to the second parameter of the `show()` method.

```ts
const toastController = useToastController()
toastController.show('Title', { myPreset: 'error' }) // or toastController.show("Title", { customData: { myPreset: 'error' } })
```

then, when showing the toast, you can retrieve them like so:

```ts
const toastState = useToastState()
toastState.myPreset // or toastState.customData.myPreset
```

To add TypeScript auto-completion for your custom fields, you can use TS module augmentation:

```ts
declare module '@tamagui/toast' {
  interface CustomData {
    myPreset: 'error' | 'success' | 'warning'
  }
}
```

### Without hooks

You can also use toasts without the hooks.

<Notice>You can't use native toasts this way.</Notice>

#### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

#### Multiple Toasts

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```


## components/toast/2.0.0

---
title: Toast
description: Use to show feedback to user interactions.
name: toast
component: Toast
package: toast
---

<Notice theme="yellow">
  This page documents the v2 imperative Toast API (`ToastProvider`,
  `ToastViewport`, `useToastController`, `useToastState`), which was removed in
  v3. Use the composable [Toast](/ui/toast) and the `toast()` function instead.
  See the [upgrade guide](/docs/guides/how-to-upgrade) for the migration.
</Notice>

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Installation

Toast is included by default in `tamagui`. If you're using it standalone:

```bash
yarn add @tamagui/toast
```

### Native Toast Setup

For native toasts on iOS/Android (using [Burnt](https://github.com/nandorojo/burnt) by Fernando Rojo), install the native dependency and import the setup module:

```bash
yarn add burnt
```

```tsx
// App.tsx - before any Tamagui imports
import '@tamagui/native/setup-burnt'
```

Then rebuild your React Native app. Without this setup, toasts will still work but the `native` prop will have no effect on mobile.

## Anatomy

```tsx
<ToastProvider>
  <Toast>
    <Toast.Title />
    <Toast.Description />
    <Toast.Action />
    <Toast.Close />
  </Toast>

  <ToastViewport />
</ToastProvider>
```

## API Reference

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
    {
      name: 'native',
      required: false,
      type: 'boolean | ToastNativePlatform | ToastNativePlatform[]',
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
    },
    {
      name: `burntOptions`,
      required: false,
      type: `Omit<BurntToastOptions, 'title' | 'message' | 'duration'>`,
      description: `Options for the burnt package if you're using native toasts on mobile`,
    },
    {
      name: `notificationOptions`,
      required: false,
      type: `NotificationOptions`,
      description: `Options for the notification API if you're using native toasts on web`,
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be used inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
    {
      name: 'portalToRoot',
      type: 'boolean | number',
      default: 'false',
      description: `When true, uses a portal to render at the very top of the root TamaguiProvider.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be used inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Title

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Description

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text#sizabletext), adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### Toast.Close

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### Toast.Action

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### useToastController

Used to control the display of toasts. Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Returns"
  data={[
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
    {
      name: `options`,
      type: `ToastOptions`,
      description: `You can use if need to access the toast options.`,
    },
  ]}
/>

### useToastState

Used to render out your toast contents. Should be used inside [ToastProvider](#toastprovider). Doesn't take in anything and returns `ToastData`.

```tsx
const CurrentToast = () => {
  const toast = useToastState()

  // don't show any toast if no toast is present or it's handled natively
  if (!toast || toast.isHandledNatively) {
    return null
  }

  return (
    <Toast key={toast.id} duration={toast.duration} viewport={toast.viewport}>
      <Toast.Title>{toast.title}</Toast.Title>
      <Toast.Description>{toast.message}</Toast.Description>
    </Toast>
  )
}
```

## Examples

### Position the viewport

To position the viewport on native toasts:

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastProvider burntOptions={{ from: 'bottom' }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

To position the viewport on custom toasts:

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

### Mobile safe area

To show toasts inside device's safe area, install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and then use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

### Different viewports

To send toasts to different viewports, you can set up different viewports:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> {/* default viewport */}
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}
```

And then, use the viewport's name on the toasts.

```tsx
const MyComponent = () => {
  return <Toast /> // default viewport
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}
```

### Custom data

Just pass your custom data to the second parameter of the `show()` method.

```ts
const toastController = useToastController()
toastController.show('Title', { myPreset: 'error' }) // or toastController.show("Title", { customData: { myPreset: 'error' } })
```

then, when showing the toast, you can retrieve them like so:

```ts
const toastState = useToastState()
toastState.myPreset // or toastState.customData.myPreset
```

To add TypeScript auto-completion for your custom fields, you can use TS module augmentation:

```ts
declare module '@tamagui/toast' {
  interface CustomData {
    myPreset: 'error' | 'success' | 'warning'
  }
}
```

### Without hooks

You can also use toasts without the hooks.

<Notice>You can't use native toasts this way.</Notice>

#### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

#### Multiple Toasts

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```


## components/toast/3.0.0

---
title: Toast
description: Accessible toasts with stacking, gestures, and animations
name: toast
component: Toast
package: toast
demoName: Toast
---

<IntroParagraph>
  Toast presents time-sensitive messages with accessible announcements,
  stacking, gestures, and animated entry or exit.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Composable component API`,
    `Smooth stacking with hover-to-expand`,
    `Swipe dismissal with spring physics`,
    `Promise toasts for async operations`,
    `All Tamagui animation drivers supported`,
  ]}
/>

## Installation

Toast ships with `tamagui`: there's nothing extra to install:

```tsx
import { Toast, toast } from 'tamagui/toast'
```

If you're using the unstyled primitives directly, it's also published on its own:

```bash
npm install @tamagui/toast
```

Native OS toasts are opt-in. By default toasts render as in-app Tamagui views on
every platform, so adding Toast to your app never pulls in a native dependency.
See [Native toasts](#native-toasts) if you want the real iOS/Android system
toast.

## Quick start

Toast is a composable component API: you mount the parts, and `toast()` drives
them from anywhere in your app.

```tsx
import { Button } from 'tamagui/button'
import { Toast, toast } from 'tamagui/toast'

function App() {
  return (
    <Toast position="bottom-right">
      <Toast.Viewport>
        <Toast.List />
      </Toast.Viewport>

      <Button onPress={() => toast('Hello!')}>Show Toast</Button>
    </Toast>
  )
}
```

Mount this inside your `TamaguiProvider`, usually next to your app navigation or
root layout. `toast()` is global, so callers don't need to be inside `<Toast>`.

`<Toast.List />` renders the default styled toast. Pass `renderItem` to own the
markup completely:

```tsx
<Toast.List
  renderItem={({ toast: t, index }) => (
    <Toast.Item key={t.id} toast={t} index={index}>
      <Toast.Title>{t.title}</Toast.Title>
      <Toast.Description>{t.description}</Toast.Description>
      <Toast.Close />
    </Toast.Item>
  )}
/>
```

Omit `renderItem` and `Toast.List` renders the default styled toast content.

## Anatomy

```tsx
<Toast>             {/* Root - context and position */}
  <Toast.Viewport>  {/* Container with portal */}
    <Toast.Item>    {/* Individual toast with stacking/drag */}
      <Toast.Title />
      <Toast.Description />
      <Toast.Close />
      <Toast.Action />
    </Toast.Item>
  </Toast.Viewport>
</Toast>
```

## API reference

### toast()

The imperative toast function:

```tsx
// Basic
toast('Hello world')

// With types
toast.success('Saved!')
toast.error('Failed')
toast.warning('Careful')
toast.info('FYI')
toast.loading('Processing...')

// With options
toast('Message', {
  description: 'More details here',
  duration: 5000,
})

// Dismiss
const id = toast('Hello')
toast.dismiss(id) // dismiss specific
toast.dismiss()   // dismiss all
```

### toast.promise()

For async operations:

```tsx
toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save',
})
```

### Toast (Root)

<PropsTable
  data={[
    {
      name: 'position',
      type: "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
      default: "'bottom-right'",
      description: 'Position of the toast viewport.',
    },
    {
      name: 'duration',
      type: 'number',
      default: '4000',
      description: 'Default toast duration in milliseconds.',
    },
    {
      name: 'gap',
      type: 'number',
      default: '14',
      description: 'Gap between toasts when expanded.',
    },
    {
      name: 'visibleToasts',
      type: 'number',
      default: '4',
      description: 'Maximum number of visible toasts.',
    },
    {
      name: 'swipeDirection',
      type: "'auto' | 'left' | 'right' | 'up' | 'down'",
      default: "'auto'",
      description: "Swipe direction to dismiss. 'auto' detects based on position.",
    },
    {
      name: 'closeButton',
      type: 'boolean',
      default: 'false',
      description: 'Show close button on toasts.',
    },
    {
      name: 'native',
      type: 'boolean',
      default: 'false',
      description:
        'Use the native OS toast on iOS/Android instead of in-app views. Requires burnt.',
    },
  ]}
/>

### Toast.Viewport

The portal container for toasts. Extends View.

<PropsTable
  data={[
    {
      name: 'offset',
      type: 'number | { top?: number, right?: number, bottom?: number, left?: number }',
      default: '16',
      description: 'Offset from screen edge.',
    },
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['altKey', 'KeyT']",
      description: 'Hotkey to focus viewport.',
    },
    {
      name: 'label',
      type: 'string',
      default: "'Notifications'",
      description: 'Aria label for the viewport.',
    },
  ]}
/>

### Toast.Item

Individual toast wrapper with stacking and drag support. Extends View.

<PropsTable
  data={[
    {
      name: 'toast',
      type: 'ToastT',
      required: true,
      description: 'The toast data object.',
    },
    {
      name: 'index',
      type: 'number',
      required: true,
      description: 'Index in the toast list (for stacking).',
    },
  ]}
/>

Supports render prop for custom content:

```tsx
<Toast.Item toast={t} index={i}>
  {({ toast, handleClose }) => (
    <YStack>
      <Toast.Title>{toast.title}</Toast.Title>
      <Button onPress={handleClose}>Close</Button>
    </YStack>
  )}
</Toast.Item>
```

### Toast.Title

Styled text for the toast title. Extends SizableText.

### Toast.Description

Styled text for the toast description. Extends SizableText.

### Toast.Close

Close button. Extends View.

### Toast.Action

Action button. Extends View.

### useToasts

Hook to access toast state from a descendant of `<Toast>`. Most apps should use `<Toast.List>` for rendering and reach for this hook only when they need custom list control.

```tsx
const { toasts, expanded, position } = useToasts()
```

## Features

### Stacking

Multiple toasts stack visually. Hover over the stack to expand and see all toasts.

### Swipe to dismiss

Toasts can be swiped away. The direction is auto-detected based on position:
- **Web:** Left/right positioned toasts swipe toward their edge, center toasts swipe horizontally
- **Native:** All positions swipe vertically (up/down) to avoid conflicting with iOS/Android navigation back gesture

When `react-native-gesture-handler` is set up via `@tamagui/native/setup-gesture-handler`, the toast uses native gesture coordination (`activeOffsetY`, `failOffsetX`) to prevent ScrollView from scrolling while swiping.

### Native toasts

Toasts render as in-app Tamagui views on every platform by default. To use the real iOS/Android system toast instead, install [Burnt](https://github.com/nandorojo/burnt) and import its setup module at your app entry:

```bash
npm install burnt
```

```tsx
import '@tamagui/native/setup-burnt'
```

Then opt in on the root:

```tsx
<Toast native>{/* ... */}</Toast>
```

Burnt is resolved lazily, so apps that don't set it up never load it and never need the native module.

### Native safe area

On native, toasts portal to root and automatically respect safe area insets (status bar, Dynamic Island, home indicator) when configured:

```tsx
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import { TamaguiProvider } from 'tamagui'

function App() {
  return (
    <SafeAreaProvider>
      <AppInner />
    </SafeAreaProvider>
  )
}

function AppInner() {
  const insets = useSafeAreaInsets()
  return (
    <TamaguiProvider config={config} insets={insets}>
      {/* toasts will automatically avoid status bar and home indicator */}
    </TamaguiProvider>
  )
}
```

The toast reads insets from `TamaguiProvider` via `useConfiguration().insets`, the same mechanism used by other Tamagui components like Slider.

### Custom styling

Each part can be styled independently:

```tsx
<Toast.Item toast={t} index={i} backgroundColor="blue-100" borderRadius="6">
  <Toast.Title color="blue-950" fontWeight="bold">
    {t.title}
  </Toast.Title>
  <Toast.Description color="blue-800">
    {t.description}
  </Toast.Description>
</Toast.Item>
```

## Migrating from v2

The v2 imperative API (`ToastProvider`, `ToastViewport`, `useToastController`, `useToastState`) was removed. Replace the provider tree with the composable parts shown above, and call `toast()` directly instead of going through a controller hook:

```tsx
// v2
const toast = useToastController()
toast.show('Saved!', { message: 'Your changes are live' })

// v3
toast('Saved!', { description: 'Your changes are live' })
```

See the [upgrade guide](/docs/guides/how-to-upgrade) for the full migration.


## components/toast/1.8.0

---
title: Toast
description: A toast component with native features
name: toast
component: Toast
package: toast
demoName: Toast
---

# Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Native toasts on Android, iOS, and web`,
  ]}
/>

## Install

For native support, run `yarn add burnt` to add `burnt`, then rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

## Anatomy

```tsx
import { Toast, ToastProvider, ToastViewport } from 'tamagui' // or '@tamagui/toast'

export default () => (
  <ToastProvider>
    <Toast>
      <Toast.Title />
      <Toast.Description />
      <Toast.Action />
      <Toast.Close />
    </Toast>

    <ToastViewport />
  </ToastProvider>
)
```

## Usage

### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

### Duplicate Toasts

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```

### Using `createToast`

```tsx
import { Button } from 'tamagui' // or '@tamagui/button'
import { Toast, ToastProvider, createToast } from 'tamagui' // or '@tamagui/toast'

export const { ImperativeToastProvider, useToast } = createToast()

export default () => (
  <ToastProvider>
    <ImperativeToastProvider>
      <CurrentToast />
      <MyPage />
    </ImperativeToastProvider>

    <ToastViewport />
  </ToastProvider>
)

const CurrentToast = () => {
  const { currentToast } = useToast()

  if (!currentToast) return
  return (
    <Toast key={currentToast.id}>
      <Toast.Title>{currentToast.title}</Toast.Title>
      <Toast.Description>{currentToast.message}</Toast.Description>
    </Toast>
  )
}

const MyPage = () => {
  const { show } = useToast()

  return (
    <Button onPress={() => show('Done!', { message: 'Form submitted successfully.' })}>
      Show Toast
    </Button>
  )
}
```

## API

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
  ]}
/>

#### Toast.Title

Should be inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Description

Should be inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Close

Should be inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

#### Toast.Action

Should be inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### createToast

An alternative way to work with toasts.

<PropsTable
  title="Arguments"
  data={[
    {
      name: 'native',
      type: "boolean | 'web' | 'mobile'",
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
      default: 'false',
    },
  ]}
/>

This function, then returns the following:

#### ImperativeToastProvider

Wrap children within this provider so that they can use `useToast()`. Takes no params.

#### useToast

You may export this hook to use it throughout your app.

<PropsTable
  title="Returns"
  data={[
    {
      name: 'currentToast',
      type: 'ToastData | null',
      description: `The information about the current toast to showm such as title, message, duration, etc.`,
    },
    {
      name: `show`,
      type: '(title: string, showOptions?: ToastOptions): void',
      description: 'Call it to show a new toast.',
    },
  ]}
/>


## components/toast/1.13.0

---
title: Toast
description: A toast component with native features
name: toast
component: Toast
package: toast
demoName: Toast
---

# Toast <Beta />

<Description>Use to show feedback to user interactions</Description>

<HeroContainer showAnimationDriverControl>
  <ToastDemo />
</HeroContainer>

```tsx hero template=Toast

```

<Highlights
  features={[
    `Automatic dismissal`,
    `Closing paused on hover, focus, window blur, and mobile touch`,
    `Swipe gesture dismissal`,
    `Support for Tamagui's animation drivers`,
    `Android/iOS native toasts and web Notification API`,
  ]}
/>

## Installation

Run the following command:

```
yarn add @tamagui/toast burnt
```

then, if targetin native, rebuild your React Native app. React Native requires sub-dependencies with native dependencies always be hoisted to your apps package.json and Toast relies on the amazing [Burnt](https://github.com/nandorojo/burnt) library by Fernando Rojo to provide its native functionality.

## Usage

To display the toast natively, you should either pass an array of native platforms (`native: ["ios", "web"]`), a single platform or `true` for all platforms.

```tsx
import { Toast, ToastProvider, useToastController, useToastState } from '@tamagui/toast'
import { Button } from 'tamagui' // or '@tamagui/button'

export default () => (
  <ToastProvider native={['mobile']}>
    <CurrentToast />
    <MyPage />
    <ToastViewport />
  </ToastProvider>
)

const CurrentToast = () => {
  const toast = useToastState()

  // only show the component if it's present and not handled by native toast
  if (!toast || toast.isHandledNatively) {
    return null
  }

  return (
    <Toast key={toast.id}>
      <Toast.Title>{toast.title}</Toast.Title>
      <Toast.Description>{toast.message}</Toast.Description>
    </Toast>
  )
}

const MyPage = () => {
  const { show } = useToastController()

  return (
    <Button onPress={() => show('Done!', { message: 'Form submitted successfully.' })}>
      Show Toast
    </Button>
  )
}
```

## API

### ToastProvider

Your toasts should be wrapped within a `ToastProvider`. This is usually done at the root of your application.

<PropsTable
  data={[
    {
      name: 'label',
      required: false,
      type: 'string',
      description: `An author-localized label for each toast. Used to help screen reader users associate the interruption with a toast.`,
      default: 'Notification',
    },
    {
      name: 'duration',
      required: false,
      type: 'number',
      description: `Time in milliseconds that each toast should remain visible for. This could be overwritten at the toast level as well.`,
      default: 5000,
    },
    {
      name: 'swipeDirection',
      required: false,
      type: 'SwipeDirection',
      description: `Direction of pointer swipe that should close the toast.`,
      default: 'right',
    },
    {
      name: 'swipeThreshold',
      required: false,
      type: 'number',
      description: `Distance in pixels that the swipe must pass before a close is triggered.`,
      default: 50,
    },
    {
      name: 'id',
      required: false,
      type: 'string',
      default: 'A unique generated ID',
    },
    {
      name: 'native',
      required: false,
      type: 'boolean | ToastNativePlatform | ToastNativePlatform[]',
      description: `Will show a native toast if is true or is set to the current platform. On iOS, it wraps \`SPIndicator\` and \`SPAlert\`. On Android, it wraps \`ToastAndroid\`. On web, it wraps Notification API. Mobile's native features are handled by \`burnt\`.`,
    },
    {
      name: `burntOptions`,
      required: false,
      type: `Omit<BurntToastOptions, 'title' | 'message' | 'duration'>`,
      description: `Options for the burnt package if you're using native toasts on mobile`,
    },
    {
      name: `notificationOptions`,
      required: false,
      type: `NotificationOptions`,
      description: `Options for the notification API if you're using native toasts on web`,
    },
  ]}
/>

### ToastViewport

The portal for toasts to be directed to. Should be used inside [ToastProvider](#toastprovider). Beyond `View` props, adds:

<PropsTable
  data={[
    {
      name: 'hotkey',
      type: 'string[]',
      default: "['F8']",
      required: false,
      description: `The keys to use as the keyboard shortcut that will move focus to the toast viewport.`,
    },
    {
      name: 'label',
      type: 'string',
      default: 'Notifications ({hotkey})',
      required: false,
      description: `An author-localized label for the toast viewport to provide context for screen reader users when navigating page landmarks. The available \`{hotkey}\` placeholder will be replaced for you.`,
    },
    {
      name: 'name',
      type: 'string',
      required: false,
      description: `Used to reference the viewport if you want to have multiple viewports in the same provider.`,
    },
    {
      name: 'multipleToasts',
      type: 'boolean',
      required: false,
      description: `Pass this when you want to have multiple/duplicated toasts.`,
    },
  ]}
/>

### Toast

Contains the Title, Description, Action and Close component. Should be used inside [ToastProvider](#toastprovider). Extends `View` and adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'type',
      type: "'foreground' | 'background'",
      required: false,
      description: `Control the sensitivity of the toast for accessibility purposes. For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.`,
    },
    {
      name: 'duration',
      type: 'number',
      required: false,
      description: `Time in milliseconds that toast should remain visible for. Overrides value given to \`ToastProvider\`.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the dialog. Must be used in conjunction with \`onOpenChange\`.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean): void',
      required: false,
      description: `Event handler called when the open state of the dialog changes.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: "(): DismissableProps['onEscapeKeyDown']",
      required: false,
      description: `Event handler called when the escape key is down. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onPause',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is paused. On web, this occurs when the pointer is moved over the viewport, the viewport is focused or when the window is blurred. On mobile, this occurs when the toast is touched.`,
    },
    {
      name: 'onResume',
      type: '(): void',
      required: false,
      description: `Event handler called when the dismiss timer is resumed. On web, this occurs when the pointer is moved away from the viewport, the viewport is blurred or when the window is focused. On mobile, this occurs when the toast is released.`,
    },
    {
      name: 'onSwipeStart',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called when starting a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeMove',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called during a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeCancel',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the cancellation of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'onSwipeEnd',
      type: '(event: SwipeEvent): void',
      required: false,
      description: `Event handler called at the end of a swipe interaction. It can be prevented by calling \`event.preventDefault\`.`,
    },
    {
      name: 'viewportName',
      type: 'string',
      required: false,
      description: `The viewport's name to send the toast to. Used when using multiple viewports and want to forward toasts to different ones.`,
      default: 'default',
    },
  ]}
/>

#### Toast.Title

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Description

Should be used inside [Toast](#toast). Extends [SizableText](/docs/components/text/1.0.0#sizabletext).

#### Toast.Close

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

#### Toast.Action

Should be used inside [Toast](#toast). Extends `View`. You can pass `asChild` to this component and use a custom `<Button>` inside.

### useToastController

Used to control the display of toasts. Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Returns"
  data={[
    {
      name: `show`,
      type: '(title: string, showOptions?: ShowToastOptions): void',
      description: `Call it to show a new toast. If you're using native toasts, you can pass native options using \`burntOptions\` or \`notificationOptions\` depending on the native platform (mobile/web).`,
    },
    {
      name: `hide`,
      type: '(): void',
      description: `Call it to hide the currently displayed toast.`,
    },
  ]}
/>

### useToastState

Used to render out your toast contents. Should be used inside [ToastProvider](#toastprovider).

<PropsTable
  title="Hook for rendering toast"
  data={[
    {
      name: `title`,
      type: 'string',
    },
    {
      name: `id`,
      type: 'string',
    },
    {
      name: `message`,
      type: 'string',
    },
    {
      name: `duration`,
      type: 'number',
    },
  ]}
/>

## FAQ

#### How to change the placement of toasts?

Native toasts:

- iOS (burnt): Supports top or bottom placements. Adjustable by passing `from` to `burntOptions`:

```tsx
<ToastProvider burntOptions={{ from: 'bottom' }}>
```

- Android (burnt): Not supported.
- Web (Notification API): Not supported.

Non-native toasts:

You should change the positioning of your [`<ToastViewport>`](#toastviewport). For instance, if you want them to appear from top right:

```tsx
<ToastViewport flexDirection="column-reverse" top={0} right={0} />
```

Or for bottom center:

```tsx
<ToastViewport flexDirection="column" bottom={0} left={0} right={0} />
```

When using multiple toasts, you can change the order of toasts by setting
`flexDirection` to `column` or `column-reverse`. Or even have them stack horizontally
using `row` or `row-reverse`.

#### How to show non-native toasts within safe area on mobile?

Install `react-native-safe-area-context` if you haven't, wrap your app inside `<SafeAreaProvider>`, and use the safe area insets to position the viewport inside the safe area.

```tsx
import { useSafeAreaInsets } from 'react-native-safe-area-context'

const SafeToastViewport = () => {
  const { left, top, right } = useSafeAreaInsets()
  return (
    <ToastViewport flexDirection="column-reverse" top={top} left={left} right={right} />
  )
}
```

#### Can I send toasts to different toast viewports?

Yes, but you will have to name them and then reference the viewport name on the `<Toast>` component. for instance:

```tsx
const App = () => {
  return (
    <ToastProvider>
      <ToastViewport /> {/* name will be "default" */}
      <ToastViewport name="viewport-custom" />
    </ToastProvider>
  )
}

const MyComponent = () => {
  return <Toast>{/* goes to default viewport */}</Toast>
}

const MyComponent2 = () => {
  return <Toast viewportName="viewport-custom" />
}
```

#### How can I have more control over toasts?

You will have to opt-out of the native toasts and only use custom ones. Here are some examples:

##### Single Toast

```tsx
export default () => {
  const [open, setOpen] = React.useState(false)
  const timerRef = React.useRef(0)

  React.useEffect(() => {
    return () => clearTimeout(timerRef.current)
  }, [])

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setOpen(false)
          window.clearTimeout(timerRef.current)
          timerRef.current = window.setTimeout(() => {
            setOpen(true)
          }, 150)
        }}
      >
        Single Toast
      </Button>
      <Toast
        onOpenChange={setOpen}
        open={open}
        animation="100ms"
        x="enter:-20px exit:-20px"
        opacity="enter:0 exit:0"
        opacity={1}
        x={0}
      >
        <Toast.Title>Subscribed!</Toast.Title>
        <Toast.Description>We'll be in touch.</Toast.Description>
      </Toast>
    </YStack>
  )
}
```

##### Multiple Toasts

<Notice>
  To use multiple toasts, you should pass `multipleToasts` to your `ToastViewport`.
  Otherwise there'll be issues when swipe-dismissing or animating toasts.
</Notice>

```tsx
export default () => {
  const [savedCount, setSavedCount] = React.useState(0)

  return (
    <YStack ai="center">
      <Button
        onPress={() => {
          setSavedCount((old) => old + 1)
        }}
      >
        Show toast
      </Button>
      {[...Array(savedCount)].map((_, index) => (
        <Toast
          key={index}
          animation="100ms"
          x="enter:-20px exit:-20px"
          opacity="enter:0 exit:0"
          opacity={1}
          x={0}
        >
          <Toast.Title>Subscribed!</Toast.Title>
          <Toast.Description>We'll be in touch.</Toast.Description>
        </Toast>
      ))}
    </YStack>
  )
}
```


## components/intro/1.0.0

---
title: Tamagui Components
---

<IntroParagraph>
  Tamagui Components is a complete suite of components that render nicely on both React web and
  React Native and come in both styled and unstyled forms.
</IntroParagraph>

## Install

You can install each component separately, or all of them at once with:

```bash
yarn add tamagui
```

## Setup

The package `tamagui` is a superset of `@tamagui/core`, so if you've already installed core you can change all the references to `tamagui`.

You'll need to add a provider to the root of your app (unlike core, where that is optional), as it will set up the root portal for components like dialogs and popovers.

```tsx
import { createTamagui, TamaguiProvider, View } from 'tamagui'
import { defaultConfig } from '@tamagui/config/v6' // for quick config install this

const config = createTamagui(defaultConfig)

export default () => (
  <TamaguiProvider config={config}>
    <View />
  </TamaguiProvider>
)
```

For a full guide configuration with `createTamagui`, check [the core configuration docs](/docs/core/configuration). For native setup, platform integrations, and the fast-path runtime, see [the Native documentation](/ui/native).


## components/intro/2.0.0

---
title: Tamagui Components
description: React Native UI kit with copy-paste composable components
---

<IntroParagraph>
  Tamagui Components is a complete suite of copy-paste composable components that render nicely on
  both React Native and React web, in both styled and unstyled forms.
</IntroParagraph>

## Install

You can install each component separately, or all of them at once with:

```bash
npm install tamagui
```

## Setup

The package `tamagui` is a superset of `@tamagui/core`, so if you've already installed core you can change all the references to `tamagui`.

You'll need to add a provider to the root of your app (unlike core, where that is optional), as it will set up the root portal for components like dialogs and popovers.

```tsx
import { createTamagui, TamaguiProvider, View } from 'tamagui'
import { defaultConfig } from '@tamagui/config/v6' // for quick config install this

const config = createTamagui(defaultConfig)

export default () => (
  <TamaguiProvider config={config}>
    <View />
  </TamaguiProvider>
)
```

For a full configuration guide with `createTamagui`, check [the core configuration docs](/docs/core/configuration). For native setup, platform integrations, and the fast-path runtime, see [the Native documentation](/ui/native).


## components/unspaced/1.0.0

---
title: Unspaced
description: Avoids spacing for children inside a spacing container.
name: html
component: Unspaced
---

While the `space` property is deprecated, Unspaced lives on in a better form, one which is easily back-ported to add Unspaced support (as well as adding `gap` support).

When using the `space` style prop, you may want some children to not be spaced.

Use Unspaced:

```tsx
import { Text, Unspaced, View } from '@tamagui/core'

export default () => (
  <View position="relative" gap="4">
    <View width={20} height={20} />
    {/* space */}
    <View width={20} height={20} />
    {/* no */}
    <Unspaced>
      <Text position="absolute">Some absolute positioned text</Text>
    </Unspaced>
  </View>
)
```

If you want the item to be visually hidden as well as unspaced, see
[VisuallyHidden](/docs/components/visually-hidden), which uses Unspaced but also hides the contents in an accessible manner.


## components/visually-hidden/1.0.0

---
title: Visually Hidden
description: Hide content accessibly.
name: html
component: VisuallyHidden
---

VisuallyHidden hides an item but ensures it remains visible to accessibility readers.

<Highlights
  features={[
    'Visually hidden content available to assistive technology',
    'Spacing preserved with the space prop',
  ]}
/>

## Installation

VisuallyHidden is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/visually-hidden
```

## Usage

Simply wrap the content you want hidden in VisuallyHidden:

```tsx
import { Text, VisuallyHidden } from 'tamagui'

export default () => (
  <VisuallyHidden>
    <Text>Add annotations here</Text>
  </VisuallyHidden>
)
```

When using with the `space` property, it will avoid double-spacing:

```tsx
import { H1, Text, VisuallyHidden, YStack } from 'tamagui'

export default () => (
  <YStack gap="4">
    <H1>Title</H1>

    <VisuallyHidden>
      <Text>Add annotations here</Text>
    </VisuallyHidden>
  </YStack>
)
```


## components/visually-hidden/2.0.0

---
title: Visually Hidden
description: Hide content accessibly
name: visually-hidden
component: VisuallyHidden
package: visually-hidden
---

<IntroParagraph>
  VisuallyHidden removes content from the visual layout while keeping it
  available to assistive technology.
</IntroParagraph>

<Highlights
  features={[
    'Visually hidden content available to assistive technology',
    'Spacing preserved with the space prop',
  ]}
/>

## Installation

VisuallyHidden is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/visually-hidden
```

## Usage

Simply wrap the content you want hidden in VisuallyHidden:

```tsx
import { VisuallyHidden, html } from 'tamagui'

export default () => (
  <VisuallyHidden>
    <html.span>Add annotations here</html.span>
  </VisuallyHidden>
)
```

When using with the `space` property, it will avoid double-spacing:

```tsx
import { H1, VisuallyHidden, YStack, html } from 'tamagui'

export default () => (
  <YStack space>
    <H1>Title</H1>

    <VisuallyHidden>
      <html.span>Add annotations here</html.span>
    </VisuallyHidden>
  </YStack>
)
```


## components/tooltip/1.0.0

---
title: Tooltip
description: A simple tooltip component
name: tooltip
component: Tooltip
package: tooltip
demoName: Tooltip
---

# Tooltip

<Description>A tooltip on web, with only accessibility output on native</Description>

<HeroContainer showAnimationDriverControl>
  <TooltipDemo />
</HeroContainer>

```tsx hero template=Tooltip

```

<Highlights
  features={[
    `Opening after the mouse stops moving`,
    `Enter and exit animations`,
    `Sizing, positioning, and styled or unstyled modes`,
  ]}
/>

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

Tooltip is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tooltip
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Tooltip } from 'tamagui' // or '@tamagui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)
```

## API Reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Maximum time before showing (can be set independently for open/close).`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps',
      required: false,
      description: `See floating-ui shift()`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/tooltip/1.0.0#portalprovider) for more information.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in [Stacks](/docs/components/stacks).

### Tooltip.Content

Renders as SizableStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.


## components/tooltip/1.105.0

---
title: Tooltip
description: A simple tooltip component
name: tooltip
component: Tooltip
package: tooltip
demoName: Tooltip
---

# Tooltip

<Description>A tooltip on web, with only accessibility output on native</Description>

<HeroContainer showAnimationDriverControl>
  <TooltipDemo />
</HeroContainer>

```tsx hero template=Tooltip

```

<Highlights
  features={[
    `Opening after the mouse stops moving`,
    `Enter and exit animations`,
    `Sizing, positioning, and styled or unstyled modes`,
  ]}
/>

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

Tooltip is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tooltip
```

### PortalProvider

Only if you aren't not using `tamagui` (but rather `@tamagui/core`) you'll need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Tooltip } from 'tamagui' // or '@tamagui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)
```

## API Reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Maximum time before showing (can be set independently for open/close).`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps',
      required: false,
      description: `See floating-ui shift()`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/tooltip/1.0.0#portalprovider) for more information.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in [Stacks](/docs/components/stacks).

### Tooltip.Content

Renders as SizableStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.

### TooltipGroup

This allows you to logically group any tooltips rendered below this component. You can control their delay props, and components inside a TooltipGroup will be smart about opening quicker if you are moving between targets with tooltips, ensuring that subsequent tooltips show immediately rather than after a delay.

See the [Floating UI docs](https://floating-ui.com/docs/floatingdelaygroup) for full details on how this works.

<PropsTable
  data={[
    {
      name: 'delay',
      type: 'number | { open?: number; close?: number }',
      default: 0,
      required: false,
      description: `The delay to use for the group.`,
    },
    {
      name: 'timeoutMs',
      type: 'number',
      default: 0,
      required: false,
      description: `An optional timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. Useful if you want grouping to last longer than the close delay, for example if there is no close delay at all.`,
    },
    {
      name: 'preventAnimation',
      type: 'boolean',
      default: false,
      required: false,
      description: `Will disable the enter/exit animations while the group is active, but not for the initial enter animation of the first hovered tooltip.`,
    },
  ]}
/>


## components/tooltip/1.122.0

---
title: Tooltip
description: A tooltip on web, with only accessibility output on native.
name: tooltip
component: Tooltip
package: tooltip
demoName: Tooltip
---

<HeroContainer showAnimationDriverControl>
  <TooltipDemo />
</HeroContainer>

```tsx hero template=Tooltip

```

<Highlights
  features={[
    `Opening after the mouse stops moving`,
    `Enter and exit animations`,
    `Sizing, positioning, and styled or unstyled modes`,
  ]}
/>

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

Tooltip is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tooltip
```

### PortalProvider

If you are not using `tamagui` (but rather `@tamagui/core`) you'll need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Tooltip } from 'tamagui' // or '@tamagui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)
```

## API Reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Maximum time before showing (can be set independently for open/close).`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps',
      required: false,
      description: `See floating-ui shift()`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](#portalprovider) for more information.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in [Stacks](/docs/components/stacks).

### Tooltip.Content

Renders as SizableStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.

### TooltipGroup

This allows you to logically group any tooltips rendered below this component. You can control their delay props, and components inside a TooltipGroup will be smart about opening quicker if you are moving between targets with tooltips, ensuring that subsequent tooltips show immediately rather than after a delay.

See the [Floating UI docs](https://floating-ui.com/docs/floatingdelaygroup) for full details on how this works.

<PropsTable
  data={[
    {
      name: 'delay',
      type: 'number | { open?: number; close?: number }',
      default: 0,
      required: false,
      description: `The delay to use for the group.`,
    },
    {
      name: 'timeoutMs',
      type: 'number',
      default: 0,
      required: false,
      description: `An optional timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. Useful if you want grouping to last longer than the close delay, for example if there is no close delay at all.`,
    },
    {
      name: 'preventAnimation',
      type: 'boolean',
      default: false,
      required: false,
      description: `Will disable the enter/exit animations while the group is active, but not for the initial enter animation of the first hovered tooltip.`,
    },
  ]}
/>

### closeOpenTooltips

A small helper function of type `() => void` that will close any open tooltips.


## components/tooltip/2.0.0

---
title: Tooltip
description: A tooltip on web, with only accessibility output on native
name: tooltip
component: Tooltip
package: tooltip
demoName: Tooltip
---

<HeroContainer showAnimationDriverControl>
  <TooltipDemo />
</HeroContainer>

```tsx hero template=Tooltip

```

<Highlights
  features={[
    `Opening after the mouse stops moving`,
    `Enter and exit animations`,
    `Sizing, positioning, and styled or unstyled modes`,
  ]}
/>

Tooltip displays contextual information when hovering over an element. It waits for your mouse to stop moving before appearing, supports animations, and [automatically stacks](/ui/z-index) above other content.

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

Tooltip is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tooltip
```

## Anatomy

```tsx
import { Tooltip } from 'tamagui' // or '@tamagui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)
```

## API Reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Maximum time before showing (can be set independently for open/close).`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the tooltip.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state when initially rendered.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: `Event handler called when the open state changes.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: `Shifts the tooltip horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'zIndex',
      type: 'number',
      required: false,
      description: `Sets the z-index of the tooltip portal. Only needed for global/scoped tooltips mounted at the root - inline tooltips automatically participate in z-index stacking. See the Scoping section below.`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](#portalprovider) for more information.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the popover when uncontrolled, see YStack in [Stacks](/docs/components/stacks).

### Tooltip.Content

Renders as SizableStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.

### TooltipGroup

This allows you to logically group any tooltips rendered below this component. You can control their delay props, and components inside a TooltipGroup will be smart about opening quicker if you are moving between targets with tooltips, ensuring that subsequent tooltips show immediately rather than after a delay.

See the [Floating UI docs](https://floating-ui.com/docs/floatingdelaygroup) for full details on how this works.

<PropsTable
  data={[
    {
      name: 'delay',
      type: 'number | { open?: number; close?: number }',
      default: 0,
      required: false,
      description: `The delay to use for the group.`,
    },
    {
      name: 'timeoutMs',
      type: 'number',
      default: 0,
      required: false,
      description: `An optional timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. Useful if you want grouping to last longer than the close delay, for example if there is no close delay at all.`,
    },
    {
      name: 'preventAnimation',
      type: 'boolean',
      default: false,
      required: false,
      description: `Will disable the enter/exit animations while the group is active, but not for the initial enter animation of the first hovered tooltip.`,
    },
  ]}
/>

### closeOpenTooltips

A small helper function of type `() => void` that will close any open tooltips.

## Scoping

Tooltip supports scoping which lets you mount a single Tooltip instance at
the root of your app, while having deeply nested Trigger components anywhere
in your tree attach to that single parent Tooltip.

This is useful for performance - you only render `Tooltip.Trigger` in your
list items or buttons, while the heavier `Tooltip` and `Tooltip.Content` live
at the root. It also lets you style all your tooltips consistently in one place.

<Notice>
  When using a global scoped tooltip, you should set `zIndex` to ensure tooltips appear above dialogs and other portaled content. This is because the global tooltip's portal is mounted outside the stacking context of other portals. Inline tooltips (rendered alongside their trigger) automatically participate in z-index stacking and don't need this.
</Notice>

```tsx fileName=_layout.tsx
import { Tooltip } from 'tamagui'

export default ({ children }) => (
  // zIndex needed for global tooltips to appear above dialogs
  <Tooltip scope="tooltip" zIndex={1_000_000}>
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* your tooltip content renders here */}
    </Tooltip.Content>

    {/* the rest of your app renders inside */}
    {children}
  </Tooltip>
)
```

```tsx fileName=MyButton.tsx
export default () => (
  <Tooltip.Trigger scope="tooltip" aria-label="Settings">
    <Button icon={Settings} />
  </Tooltip.Trigger>
)
```

The `scope` prop on `Trigger` connects it to the `Tooltip` with the matching scope.


## components/tooltip/3.0.0

---
title: Tooltip
description: A tooltip on web, with only accessibility output on native
name: tooltip
component: Tooltip
package: tooltip
demoName: Tooltip
---

<IntroParagraph>
  Tooltip adds positioned, animated context to a trigger while preserving an
  accessible description.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <TooltipDemo />
</HeroContainer>

```tsx hero template=Tooltip

```

<Highlights
  features={[
    `Opening after the mouse stops moving`,
    `Enter and exit animations`,
    `Sizing, positioning, and styled or unstyled modes`,
  ]}
/>

Tooltip displays contextual information when hovering over an element. It waits for your mouse to stop moving before appearing, supports animations, and [automatically stacks](/ui/z-index) above other content.

<Notice>Note that Tooltip doesn't render on native platforms.</Notice>

## Installation

Tooltip is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/tooltip
```

## Anatomy

```tsx
import { Tooltip } from 'tamagui' // or '@tamagui/tooltip'

export default () => (
  <Tooltip>
    <Tooltip.Trigger />
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* ... */}
    </Tooltip.Content>
  </Tooltip>
)
```

## API reference

### Tooltip

Contains every component for the tooltip.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Tooltip.Content`,
    },
    {
      name: 'groupId',
      type: 'string',
      required: false,
      description: `If given, will work alongside TooltipGroup to ensure only one tooltip in the groups stays open.`,
    },
    {
      name: 'restMs',
      type: 'number',
      required: false,
      description: `Time needed for cursor to rest before showing.`,
    },
    {
      name: 'delay',
      type: `number | { open?: number; close?: number }`,
      required: false,
      description: `Time to wait before showing (can be set independently for open/close).`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `The controlled open state of the tooltip.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `The open state when initially rendered.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: `Event handler called when the open state changes.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: `Shifts the tooltip horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps',
      required: false,
      description: `See floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Tooltip appears from the target, see floating-ui offset().`,
    },
    {
      name: 'zIndex',
      type: 'number',
      required: false,
      description: `Sets the z-index of the tooltip portal. Only needed for global/scoped tooltips mounted at the root - inline tooltips automatically participate in z-index stacking. See the Scoping section below.`,
    },
  ]}
/>

<Notice theme="blue">
  On native, pair modal tooltips with [native portal
  setup](/ui/portal#native-portal-setup-recommended) to preserve React context
  inside Tooltip content.
</Notice>

### Tooltip.Trigger

Used to trigger opening of the tooltip when uncontrolled, see YStack in [Stacks](/ui/stacks).

### Tooltip.Content

Renders as a YStack (see [Stacks](/ui/stacks)); `size` sets width and height.

### Tooltip.Anchor

Renders as YStack, see [Stacks](/ui/stacks).

When you want the Trigger to be in another location from where the Tooltip attaches, use Anchor. When used, Anchor is where the Tooltip will attach, while Trigger will open it.

### TooltipGroup

This allows you to logically group any tooltips rendered below this component. You can control their delay props, and components inside a TooltipGroup will be smart about opening quicker if you are moving between targets with tooltips, ensuring that subsequent tooltips show immediately rather than after a delay.

See the [Floating UI docs](https://floating-ui.com/docs/floatingdelaygroup) for full details on how this works.

<PropsTable
  data={[
    {
      name: 'delay',
      type: 'number | { open?: number; close?: number }',
      default: 0,
      required: false,
      description: `The delay to use for the group.`,
    },
    {
      name: 'timeoutMs',
      type: 'number',
      default: 0,
      required: false,
      description: `An optional timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. Useful if you want grouping to last longer than the close delay, for example if there is no close delay at all.`,
    },
    {
      name: 'preventAnimation',
      type: 'boolean',
      default: false,
      required: false,
      description: `Will disable the enter/exit animations while the group is active, but not for the initial enter animation of the first hovered tooltip.`,
    },
  ]}
/>

### closeOpenTooltips

A small helper function of type `() => void` that will close any open tooltips.

## Scoping

Tooltip supports scoping which lets you mount a single Tooltip instance at
the root of your app, while having deeply nested Trigger components anywhere
in your tree attach to that single parent Tooltip.

This is useful for performance - you only render `Tooltip.Trigger` in your
list items or buttons, while the heavier `Tooltip` and `Tooltip.Content` live
at the root. It also lets you style all your tooltips consistently in one place.

<Notice>
  When using a global scoped tooltip, you should set `zIndex` to ensure tooltips appear above dialogs and other portaled content. This is because the global tooltip's portal is mounted outside the stacking context of other portals. Inline tooltips (rendered alongside their trigger) automatically participate in z-index stacking and don't need this.
</Notice>

```tsx fileName=_layout.tsx
import { Tooltip } from 'tamagui'

export default ({ children }) => (
  // zIndex needed for global tooltips to appear above dialogs
  <Tooltip scope="tooltip" zIndex={1_000_000}>
    <Tooltip.Content>
      <Tooltip.Arrow />
      {/* your tooltip content renders here */}
    </Tooltip.Content>

    {/* the rest of your app renders inside */}
    {children}
  </Tooltip>
)
```

```tsx fileName=MyButton.tsx
export default () => (
  <Tooltip.Trigger scope="tooltip" aria-label="Settings">
    <Button icon={Settings} />
  </Tooltip.Trigger>
)
```

The `scope` prop on `Trigger` connects it to the `Tooltip` with the matching scope.


## components/text/1.0.0

---
title: Text
description: Text primitives with themes custom to each font.
name: text
component: Paragraph
package: text
demoName: Text
---

<HeroContainer demoMultiple>
  <TextDemo />
</HeroContainer>

```tsx hero template=Text

```

<Highlights
  features={[
    'Font-specific themes for spacing, weights, and sizes',
    'Automatic theme matching through the size prop',
    'Flat media, hover, press, and focus clauses',
  ]}
/>

## Installation

Text is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/text
```

## Usage

```tsx
export default () => (
  <>
    <Text>Text</Text>
    <SizableText>Sizable Text</SizableText>
    <Paragraph>Paragraph</Paragraph>
  </>
)
```

## Text

Text in Tamagui matches to Text in react-native-web, just with the added [Tamagui Props](/docs/intro/props).

It explicitly doesn't inherit your theme color or other font properties, as it's meant to be plain and used for extension. Below, we'll show `SizableText` which extends Text, and `Paragraph` which extends SizableText. Generally, Paragraph is the useful view as it will use theme values, while you can extend Text if you'd like to derive your own design system.

```tsx
import { Text, XStack, YStack } from 'tamagui'

export default () => (
  <>
    <Text
      // can add theme values
      color="white hover:color-hover"
      fontFamily="body"
      // or just use direct values
      fontSize={20}
    >
      Lorem ipsum
    </Text>
  </>
)
```

## SizableText

Tamagui lets you define font sizing, spacing, line height, letter spacing and other properties with `createFont`, of which you can have many different configurations. We've found a nice pattern is to "align" all your keys across these sub-objects.

SizableText adds a `size` property thats defined using a [spread variant](/docs/core/styled#spread-variants) which looks for a matching key on each of these properties (using `@tamagui/get-font-sized`):

- color
- fontStyle
- textTransform
- fontFamily
- fontWeight
- letterSpacing
- fontSize
- lineHeight

So, if you've defined `small`, `medium` and `large` keys on each createFont category, you can use it like so:

```tsx
<SizableText size="small" />
```

[Source code for SizableText](https://github.com/tamagui/tamagui/blob/main/code/ui/text/src/SizableText.tsx).

## Paragraph

Paragraph extends SizableText and is defined as:

```tsx
export const Paragraph = styled(SizableText, {
  displayName: 'Paragraph',
  tag: 'p',
  userSelect: 'auto',
  color: 'color',
  size: true,
  whiteSpace: 'normal',
})
```

<Notice>
  Note: Paragraph renders to a `p` tag on web, which can cause issues when you nest them
  during SSR. If you don't mind rendering to a span, use `SizableText`, otherwise, be
  careful when nesting items inside a Paragraph.
</Notice>


## components/text/1.0.0-alpha

---
title: Text
description: Text, Sized Text and Paragraph show one way to build a design system.
name: text
component: Paragraph
demoName: Text
---

# Text

<Description>
  Text, Sized Text and Paragraph show one way to build a design system.
</Description>

<HeroContainer>
  <TextDemo />
</HeroContainer>

```tsx hero template=Text

```

<Highlights
  features={[
    'All react-native-web props and Tamagui styles',
    'Flat media, hover, and press clauses',
    'Theme and spread-variant defaults for Paragraph',
  ]}
/>

### Usage

Text in Tamagui matches to Text in react-native-web, just with the added [Tamagui Props](/docs/intro/props).

It explicitly doesn't inherit your theme color or other font properties, as it's meant to be plain and used for extension. Below, we'll show `SizableText` which extends Text, and `Paragraph` which extends SizableText. Generally, Paragraph is the useful view as it will use theme values, while you can extend Text if you'd like to derive your own design system.

```tsx
import { Text, XStack, YStack } from 'tamagui'

export default () => (
  <>
    <Text
      // can add theme values
      color="white hover:color-2"
      fontFamily="body"
      // or just use direct values
      fontSize={20}
    >
      Lorem ipsum
    </Text>
  </>
)
```

SizableText and Paragraph default to the "body" fontFamily defined in your config.
Headings all default to "heading".

## SizableText

[Seeing how SizableText is defined](https://github.com/tamagui/tamagui/blob/v2/code/ui/text/src/SizableText.tsx) is helpful for understanding Tamagui. They serve as a good example of how you can extend and compose components.

SizableText simply adds a single `size` property to maniplulate all of:

- fontSize
- lineHeight
- fontWeight
- letterSpacing

Based on the values set in your tokens. It uses [spread variants](/docs/core/styled#spread-variants) feature. Then Paragraph extends that and ensures it defaults to values from your theme - fontSize, lineHeight, color and fontFamily.

## Paragraph

Finally Paragraph extends `SizableText` and simply sets some default values from your theme:

```tsx
export const Paragraph = styled(SizableText, {
  fontFamily: 'body',
  color: 'color',
  size: true,
})
```


## components/text/2.0.0

---
title: Text
description: Text primitives with themes custom to each font
name: text
component: Paragraph
package: text
demoName: Text
---

<IntroParagraph>
  Text primitives connect semantic text, configured fonts, shared sizing, and
  Tamagui style props across web and native.
</IntroParagraph>

<HeroContainer demoMultiple>
  <TextDemo />
</HeroContainer>

```tsx hero template=Text

```

<Highlights
  features={[
    'Font-specific themes for spacing, weights, and sizes',
    'Automatic theme matching through the size prop',
    'Flat media, hover, press, and focus clauses',
  ]}
/>

The base `Text` component is already included in `@tamagui/core` (and `tamagui`). This
package is optional and adds `SizableText` and `Paragraph`, which extend `Text` with the
`size` prop and theme-aware defaults.

## Installation

If you're using `tamagui`, `SizableText` and `Paragraph` are already included. Otherwise, install independently:

```bash
npm install @tamagui/text
```

## Usage

```tsx
export default () => (
  <>
    <Text>Text</Text>
    <SizableText>Sizable Text</SizableText>
    <Paragraph>Paragraph</Paragraph>
  </>
)
```

## Text

Text in Tamagui matches Text in react-native-web, with the added [Tamagui props](/docs/intro/props).

It explicitly does not inherit your theme color or other font properties, as it is meant to be plain and used for extension. Below, we show `SizableText` which extends Text, and `Paragraph` which extends SizableText. Generally, Paragraph is the useful component as it uses theme values, while you can extend Text if you want to derive your own design system.

```tsx
import { Text, XStack, YStack } from 'tamagui'

export default () => (
  <>
    <Text
      // can add theme values
      color="white hover:color-hover"
      fontFamily="body"
      // or just use direct values
      fontSize={20}
    >
      Lorem ipsum
    </Text>
  </>
)
```

## SizableText

Tamagui lets you define font sizing, spacing, line height, letter spacing and other properties with `createFont`, of which you can have many different configurations. We've found a nice pattern is to "align" all your keys across these sub-objects.

SizableText adds a `size` property whose variant is a [`styled.dynamic`](/docs/core/variants#dynamic-variants) callback, with a [component resolver](/docs/core/styled#component-resolvers-resolve) that looks for a matching key on each of these properties (using `@tamagui/get-font-sized`):

- color
- fontStyle
- textTransform
- fontFamily
- fontWeight
- letterSpacing
- fontSize
- lineHeight

So, if you've defined `small`, `medium` and `large` keys on each createFont category, you can use it like so:

```tsx
<SizableText size="small" />
```

[Source code for SizableText](https://github.com/tamagui/tamagui/blob/main/code/ui/text/src/SizableText.tsx).

## Paragraph

Paragraph extends SizableText and is defined as:

```tsx
export const Paragraph = styled(SizableText, {
  displayName: 'Paragraph',
  render: 'p',
  userSelect: 'auto',
  color: 'color',
  whiteSpace: 'normal',
  size: true,
})
```

<Notice>
  Note: Paragraph renders to a `p` tag on web, which can cause issues when you nest them
  during SSR. If you don't mind rendering to a span, use `SizableText`, otherwise, be
  careful when nesting items inside a Paragraph.
</Notice>

## Inline text elements

For semantic inline text styling, `@tamagui/text` exports `Strong`, `Em`, and `Span`:

```tsx
import { Strong, Em, Span, Paragraph } from '@tamagui/text'

export default () => (
  <Paragraph>
    This is <Strong>bold text</Strong>, this is <Em>italic text</Em>, and this is a{' '}
    <Span color="blue-10">colored span</Span>.
  </Paragraph>
)
```

These render to their corresponding HTML elements (`<strong>`, `<em>`, `<span>`) on web while remaining compatible with React Native.

## Text truncation

Tamagui provides two props for truncating text with ellipsis: `ellipsis` for single-line truncation and `numberOfLines` for multi-line clamping.

### Single-line ellipsis

Use the `ellipsis` prop to truncate text to a single line with an ellipsis:

```tsx
import { Text, SizableText, Paragraph } from 'tamagui'

export default () => (
  <Paragraph ellipsis maxWidth={200}>
    This is a very long text that will be truncated with an ellipsis when it overflows.
  </Paragraph>
)
```

On web, this applies `text-overflow: ellipsis`, `white-space: nowrap`, and `overflow: hidden`. On native, it sets `numberOfLines={1}`.

### Multi-line clamping

Use the `numberOfLines` prop to clamp text to a specific number of lines:

```tsx
import { Paragraph } from 'tamagui'

export default () => (
  <>
    <Paragraph numberOfLines={1} maxWidth={200}>
      Single line truncation, same as ellipsis.
    </Paragraph>

    <Paragraph numberOfLines={3} maxWidth={200}>
      This text will be clamped to three lines. Any overflow beyond the third
      line will be hidden. This is useful for card descriptions or preview text
      where you want to show a limited amount of content.
    </Paragraph>
  </>
)
```

On web, multi-line clamping uses `-webkit-line-clamp` with `-webkit-box` display. On native, it passes `numberOfLines` directly to the React Native Text component.

The `numberOfLines` prop is supported on the base `Text` component from `@tamagui/core`
as well as `SizableText` and `Paragraph`. The `ellipsis` prop is a shorthand for
`numberOfLines={1}`.

## API reference

### Text

The base text component from `@tamagui/core`. Accepts all [Tamagui style props](/docs/intro/props) for text elements.

<PropsTable
  data={[
    {
      name: 'ellipsis',
      required: false,
      type: 'boolean',
      description: `When true, truncates text to a single line with an ellipsis. Equivalent to numberOfLines={1}.`,
    },
    {
      name: 'numberOfLines',
      required: false,
      type: 'number',
      description: `Clamps text to the specified number of lines. Overflow is hidden. On web uses -webkit-line-clamp; on native uses the React Native numberOfLines prop.`,
    },
  ]}
/>

### SizableText

Extends Text with the `size` prop for theme-aware font sizing.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens | true',
      description: `Sets font size, line height, letter spacing, and font weight from your theme's font configuration. Accepts any size token (e.g., "4") or true for the default size.`,
    },
    {
      name: 'ellipsis',
      required: false,
      type: 'boolean',
      description: `When true, truncates text to a single line with an ellipsis.`,
    },
    {
      name: 'numberOfLines',
      required: false,
      type: 'number',
      description: `Clamps text to the specified number of lines.`,
    },
  ]}
/>

### Paragraph

Extends SizableText with semantic defaults. Renders as `<p>` on web, uses theme color, and sets `userSelect: 'auto'` and `whiteSpace: 'normal'`.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens | true',
      default: 'true',
      description: `Sets font size from your theme. Defaults to the theme's base size.`,
    },
    {
      name: 'ellipsis',
      required: false,
      type: 'boolean',
      description: `When true, truncates text to a single line with an ellipsis.`,
    },
    {
      name: 'numberOfLines',
      required: false,
      type: 'number',
      description: `Clamps text to the specified number of lines.`,
    },
  ]}
/>


## components/headings/1.0.0

---
title: Headings
description: Heading components that mimic HTML equivalents
name: html
component: Headings
package: text
demoName: Headings
---

<HeroContainer>
  <HeadingsDemo />
</HeroContainer>

```tsx hero template=Headings

```

<Highlights
  features={[
    'One size prop for all styles',
    'Custom fonts with per-size styles',
  ]}
/>

## Installation

Headings is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/text
```

```tsx
import { H1, H2, H3, H4, H5, H6, Heading } from 'tamagui'

export default () => (
  <>
    <H1>Heading 1</H1>
    <H2>Heading 2</H2>
    <H3>Heading 3</H3>
    <H4>Heading 4</H4>
    <H5>Heading 5</H5>
    <H6>Heading 6</H6>
    <Heading>Heading</Heading>
  </>
)
```

The headings all extend from the base `Heading` component. Note, this is just our own theme for Inter headings, but you can change the styles for any font completely.

Tamagui expects for your [font.size](/docs/core/configuration#font-tokens) to have the keys 1-10 so headings work with your font tokens automatically.

## How it works

The `Heading` component is defined as follows:

```tsx
export const Heading = styled(Paragraph, {
  tag: 'span',
  displayName: 'Heading',
  accessibilityRole: 'header',
  fontFamily: 'heading',
  size: '8',
  margin: 0,
})
```

Note that Heading, and H1-H6 all default to the `heading` font family that must be defined in your tamagui.config.ts.

Because [Paragraph](/docs/components/text#paragraph) extends [SizableText](/docs/components/text#sizabletext), you get automatic styles based on your font theme. Let's see how `SizableText` defines the size variant, roughly, which gives a good idea of how Tamagui works, and how you could create or change your own headings at a lower level.

```tsx
import { Text } from 'tamagui' // or '@tamagui/core'

const SizableText = styled(Text, {
  displayName: 'SizableText',
  fontFamily: 'body',
  color: 'color',

  variants: {
    size: {
      '...fontSize': (val, { font, props }) => {
        const fontSize = font.size[val]
        const lineHeight = font.lineHeight[val]
        const fontWeight = font.weight[val]
        const letterSpacing = font.letterSpacing[val]
        const fontStyle = font.style?.[val]
        const textTransform = font.transform?.[val]
        return {
          fontStyle,
          textTransform,
          fontWeight,
          letterSpacing,
          fontSize,
          lineHeight,
        }
      },
    },
  },

  defaultVariants: {
    size: true,
  },
})
```

## API Reference

### Heading

Headings extend [SizableText props](/docs/components/text#sizabletext) inheriting all the [Tamagui standard props](/docs/intro/props).


## components/headings/2.0.0

---
title: Headings
description: Heading components that mirror HTML equivalents
name: headings
component: Headings
package: text
demoName: Headings
---

<IntroParagraph>
  Heading components map semantic HTML headings to your configured font sizes
  on web and native.
</IntroParagraph>

<HeroContainer>
  <HeadingsDemo />
</HeroContainer>

```tsx hero template=Headings

```

<Highlights
  features={[
    'One size prop for all styles',
    'Custom fonts with per-size styles',
  ]}
/>

## Installation

Headings is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/text
```

```tsx
import { H1, H2, H3, H4, H5, H6, Heading } from 'tamagui'

export default () => (
  <>
    <H1>Heading 1</H1>
    <H2>Heading 2</H2>
    <H3>Heading 3</H3>
    <H4>Heading 4</H4>
    <H5>Heading 5</H5>
    <H6>Heading 6</H6>
    <Heading>Heading</Heading>
  </>
)
```

The headings all extend from the base `Heading` component. This is our own theme for Inter headings; you can restyle them for any font.

Tamagui expects your [font.size](/docs/core/configuration#font-tokens) tokens to include the keys 1-10 so headings resolve automatically.

## How it works

The `Heading` component is defined as follows:

```tsx
export const Heading = styled(Paragraph, {
  render: 'span',
  displayName: 'Heading',
  role: 'heading',
  fontFamily: 'heading',
  margin: 0,
  size: '8',
})
```

Note that Heading, and H1-H6 all default to the `heading` font family that must be defined in your tamagui.config.ts.

Because [Paragraph](/ui/text#paragraph) extends [SizableText](/ui/text#sizabletext), you get automatic styles based on your font theme. Let's see how `SizableText` defines the size variant, roughly, which gives a good idea of how Tamagui works, and how you could create or change your own headings at a lower level.

```tsx
import { Text } from 'tamagui' // or '@tamagui/core'

const SizableText = styled(Text, {
  displayName: 'SizableText',
  fontFamily: 'body',
  color: 'color',

  variants: {
    size: {
      '...fontSize': (val, { font, props }) => {
        const fontSize = font.size[val]
        const lineHeight = font.lineHeight[val]
        const fontWeight = font.weight[val]
        const letterSpacing = font.letterSpacing[val]
        const fontStyle = font.style?.[val]
        const textTransform = font.transform?.[val]
        return {
          fontStyle,
          textTransform,
          fontWeight,
          letterSpacing,
          fontSize,
          lineHeight,
        }
      },
    },
  },

  defaultVariants: {
    size: true,
  },
})
```

## API reference

### Heading

Headings extend [SizableText props](/ui/text#sizabletext) inheriting all the [Tamagui standard props](/docs/intro/props).


## components/anchor/1.0.0

---
title: Anchor
description: Link to external websites.
name: html
component: Anchor
---

<Highlights
  features={['Server rendering support', 'Native and web support', 'Full Tamagui style props']}
/>

## Usage

The Anchor component provides a way to link to external websites. It extends [SizableText](/docs/components/text#sizable-text), adding the `href`, `target`, and `rel` attributes.

On native, it will use React Native `Linking.openURL`, on web it will render to an `a` element with `href` set appropriately.

## API Reference

### Anchor

Inherits [Tamagui props](/docs/intro/props) as well as:

<PropsTable
  data={[
    {
      name: 'href',
      required: false,
      type: 'string',
      description: `Location to link to.`,
    },
    {
      name: 'target',
      required: false,
      type: 'string',
    },
    {
      name: 'rel',
      required: false,
      type: 'string',
    },
  ]}
/>


## components/anchor/2.0.0

---
title: Anchor
description: Link to external websites
name: anchor
component: Anchor
---

<IntroParagraph>
  Anchor adds Tamagui style props and cross-platform behavior to links.
</IntroParagraph>

<Highlights
  features={['Server rendering support', 'Native and web support', 'Full Tamagui style props']}
/>

## Installation

Anchor is already installed in `tamagui`:

## Usage

Anchor extends [SizableText](/ui/text#sizabletext), adding the `href`, `target`, and `rel` attributes.

On native, it uses React Native `Linking.openURL`. On web, it renders an `a` element with `href` set appropriately.

## API reference

### Anchor

Inherits [Tamagui props](/docs/intro/props) as well as:

<PropsTable
  data={[
    {
      name: 'href',
      required: false,
      type: 'string',
      description: `The URL to link to.`,
    },
    {
      name: 'target',
      required: false,
      type: 'string',
      description: `Specifies where to open the linked document.`,
    },
    {
      name: 'rel',
      required: false,
      type: 'string',
      description: `Specifies the relationship between the current document and the linked document.`,
    },
  ]}
/>


## components/alert-dialog/1.0.0

---
title: AlertDialog
description: Show an alert prompt in a dialog
name: alertDialog
component: AlertDialog
package: alert-dialog
demoName: AlertDialog
---

<HeroContainer showAnimationDriverControl>
  <AlertDialogDemo />
</HeroContainer>

```tsx hero template=AlertDialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Accessibility checks for ARIA props during development`,
  ]}
/>

## Installation

Alert Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/alert-dialog
```

In order to use this component independently of `tamagui`, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

## Anatomy

```tsx
import { AlertDialog } from 'tamagui' // or '@tamagui/alert-dialog'

export default () => (
  <AlertDialog>
    <AlertDialog.Trigger />
    <AlertDialog.Portal>
      <AlertDialog.Overlay />
      <AlertDialog.Content>
        <AlertDialog.Title />
        <AlertDialog.Description />
        <AlertDialog.Cancel />
        {/* ... */}
      </AlertDialog.Content>
    </AlertDialog.Portal>
  </AlertDialog>
)
```

## API Reference

### AlertDialog

Contains every component for the AlertDialog. Shares all [Dialog Props](/docs/components/dialog#api), except modal which is on by default. Adds:

<PropsTable
  data={[
    {
      name: 'native',
      type: 'boolean',
      required: false,
      description: `When true, on iOS it will render as a native AlertDialog.`,
    },
  ]}
/>

### AlertDialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### AlertDialog.Portal

Renders AlertDialog into appropriate container. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Content

Main container for AlertDialog content, this is where you should apply animations.

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/docs/components/headings).

### AlertDialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/docs/components/text).

### AlertDialog.Cancel

Closes the AlertDialog, accepts all YStack props. Recommended to use with your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Cancel elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

### PortalProvider

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Examples

### Inside native modals

If you're using native modals (maybe from react-navigation), you'll notice the Dialogs won't show up inside the modal. To get around this, you should wrap your screen inside `PortalProvider`, like so:

```tsx
import { PortalProvider } from 'tamagui'

// this component used in react-navigation/expo-router with `presentation: "modal"`
export function Page() {
  return (
    <PortalProvider>{/* rest of your page, including the Dialog... */}</PortalProvider>
  )
}
```


## components/alert-dialog/2.0.0

---
title: Alert Dialog
description: Show an alert prompt in a dialog
name: alert-dialog
component: AlertDialog
package: alert-dialog
demoName: AlertDialog
---

<IntroParagraph>
  AlertDialog asks users to confirm an action in a focused, accessible modal.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <AlertDialogDemo />
</HeroContainer>

```tsx hero template=AlertDialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Accessibility checks for ARIA props during development`,
  ]}
/>

AlertDialog is built on Dialog with stricter accessibility requirements, and [automatically stacks](/ui/z-index) above other content.

## Installation

Alert Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/alert-dialog
```

## Anatomy

```tsx
import { AlertDialog } from 'tamagui' // or '@tamagui/alert-dialog'

export default () => (
  <AlertDialog>
    <AlertDialog.Trigger />
    <AlertDialog.Portal>
      <AlertDialog.Overlay />
      <AlertDialog.Content>
        <AlertDialog.Title />
        <AlertDialog.Description />
        <AlertDialog.Cancel />
        {/* ... */}
      </AlertDialog.Content>
    </AlertDialog.Portal>
  </AlertDialog>
)
```

## API reference

### AlertDialog

Contains every component for the AlertDialog. Shares all [Dialog Props](/ui/dialog#api-reference), except modal which is on by default. Adds:

<PropsTable
  data={[
    {
      name: 'native',
      type: 'boolean',
      required: false,
      description: `When true, on iOS it will render as a native AlertDialog.`,
    },
  ]}
/>

### AlertDialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### AlertDialog.Portal

Renders AlertDialog into appropriate container. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Content

Main container for AlertDialog content, this is where you should apply animations.

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### AlertDialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/ui/headings).

### AlertDialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/ui/text#paragraph).

### AlertDialog.Cancel

Closes the AlertDialog, accepts all View props. Recommended to use with your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Cancel elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

### AlertDialog.Action

Confirms the AlertDialog action, accepts all View props. Recommended to use with your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Action elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

### AlertDialog.Destructive

A destructive action button for the AlertDialog. When using `native` mode on iOS, this renders with the native red destructive button style. Accepts all View props.

```tsx
<AlertDialog native>
  <AlertDialog.Trigger asChild>
    <Button>Delete Account</Button>
  </AlertDialog.Trigger>
  <AlertDialog.Portal>
    <AlertDialog.Overlay />
    <AlertDialog.Content>
      <AlertDialog.Title>Delete Account?</AlertDialog.Title>
      <AlertDialog.Description>This action cannot be undone.</AlertDialog.Description>
      <AlertDialog.Cancel asChild>
        <Button>Cancel</Button>
      </AlertDialog.Cancel>
      <AlertDialog.Destructive asChild>
        <Button theme="red">Delete</Button>
      </AlertDialog.Destructive>
    </AlertDialog.Content>
  </AlertDialog.Portal>
</AlertDialog>
```

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Destructive elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

### PortalProvider

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>


## components/native/2.0.0

---
title: Native
description: Native integrations for portals, sheets, menus, toasts, and gradients
name: native
---

<IntroParagraph>
  `@tamagui/native` connects Tamagui UI components to platform integrations for
  gestures, portals, sheets, menus, toasts, and gradients.
</IntroParagraph>

For native press handling and the style runtime, see
[core Native](/docs/core/native).

## Setup

The `@tamagui/native` package provides setup utilities for native integrations.
Import the setup modules at your app's entry point, before any Tamagui imports.

```bash
npm install @tamagui/native
```

<Notice>
  `@tamagui/native` is a light setup package. When you use one of its optional
  integrations, make sure the matching native dependency is installed in your
  app as well, such as `react-native-gesture-handler`, `react-native-teleport`,
  `@expo/ui`, `zeego`, or `burnt`. In a monorepo, install those native packages in the
  parent app or workspace root rather than a leaf package.
</Notice>

## Portal

**Native portals preserve React context**. The default implementation on native
uses a JS-based approach that breaks React context, or requires you to hoist
data awkwardly. With native portals, your custom contexts (navigation, app
state) work inside Sheet, Dialog, Popover, and other portaled content.

### Setup

```bash
npm install react-native-teleport
```

```tsx
// App.tsx - before any Tamagui imports
import '@tamagui/native/setup-teleport'
```

See [Portal docs](/ui/portal) for full details.

## Gesture Handler

Enable native gesture coordination for Sheet dragging and scrolling:

```bash
npm install react-native-gesture-handler
```

```tsx
import { setupGestureHandler } from '@tamagui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

setupGestureHandler({ pressEvents: false, sheet: true })

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* your app */}</GestureHandlerRootView>
  )
}
```

See [Sheet](/ui/sheet) for component usage. For native press events and
`PressBoundary`, see [core Native](/docs/core/native#gesture-handler).

## Menu & ContextMenu

**Native menus** render platform-native context menus instead of custom
overlays. They use the OS menu API for haptics, blur effects, and system
integration.

### Setup

```bash
npm install @expo/ui
```

```tsx
// App.tsx - before any Tamagui imports
import '@tamagui/native/setup-expo-ui-menu'
```

Then use the `native` prop:

```tsx
<Menu native>{/* menu content */}</Menu>
```

The Zeego adapter remains available for apps on compatible React Native versions:

```bash
npm install zeego @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities sf-symbols-typescript
```

```tsx
import '@tamagui/native/setup-zeego'
```

See [Menu docs](/ui/menu) and
[ContextMenu docs](/ui/context-menu) for full details.

## Toast

**Native toasts** use platform-native toast implementations:

- iOS: SPIndicator (system-style indicators)
- Android: ToastAndroid
- Web: Notification API

### Setup

```bash
npm install burnt
```

```tsx
// App.tsx - before any Tamagui imports
import '@tamagui/native/setup-burnt'
```

Then use the `native` prop on ToastProvider:

```tsx
<Toast.Provider native>{/* your app */}</Toast.Provider>
```

See [Toast docs](/ui/toast) for full details.

## LinearGradient

**Native gradients** use `expo-linear-gradient` for high-performance native gradient rendering.

### Setup

```bash
npm install expo-linear-gradient
```

```tsx
// App.tsx - before any Tamagui imports
import '@tamagui/native/setup-expo-linear-gradient'
```

See [LinearGradient docs](/ui/linear-gradient) for full details.

## Optimized native runtime (experimental)

The native style runtime is configured at the core level. See
[core Native](/docs/core/native#native-runtime) for setup.


## components/select/1.0.0

---
title: Select
description: A simple select component
name: select
component: Select
package: select
demoName: Select
---

# Select

<Description>Show a menu of items users can select from one of.</Description>

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

### Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

### API

#### &lt;Select /&gt;

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms`,
    },
  ]}
/>

#### &lt;Trigger /&gt;

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### &lt;Value /&gt;

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### &lt;Content /&gt;

Main container for Select content, used to contain the up/down arrows, no API beyond children.

#### &lt;ScrollUpButton /&gt;

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

#### &lt;ScrollDownButton /&gt;

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

#### &lt;Viewport /&gt;

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
  ]}
/>

#### &lt;Group /&gt;

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

#### &lt;Label /&gt;

Extends [ListItem](/docs/components/list-item). Used to label Groups.

#### &lt;Item /&gt;

Extends [ListItem](/docs/components/list-item). Used to add selectable values ot the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

#### &lt;ItemText /&gt;

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

#### &lt;Sheet /&gt;

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.SheetContents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="maxMd" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <SheetContents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/1.128.0

---
title: Select
description: Show a menu of items that users can select from.
name: select
component: Select
package: select
demoName: Select
---

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

## Installation

Select is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/select
```

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    {/* Optional: Control focus behavior */}
    <Select.FocusScope loop trapped focusOnIdle={true}>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton />
      </Select.Content>
    </Select.FocusScope>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

## API Reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### SelectContent

Main container for Select content, used to contain the up/down arrows, no API beyond children.

#### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles`,
    },
  ]}
/>

<Notice>
  Make sure to not pass `height` prop as that is managed internally because of UX reasons
  and having a fixed height will break that behavior
</Notice>

### Select.Group

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [ListItem](/docs/components/list-item). Used to label Groups.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values to the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.FocusScope

Provides access to the underlying FocusScope component used by Select for focus management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Select.Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.Adapt.Contents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="maxMd" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <Adapt.Contents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/1.40.0

---
title: Select
description: Show a menu of items that users can select from.
name: select
component: Select
package: select
demoName: Select
---

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

## Installation

Select is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/select
```

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

## API Reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### SelectContent

Main container for Select content, used to contain the up/down arrows, no API beyond children.

#### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles`,
    },
  ]}
/>

<Notice>
  Make sure to not pass `height` prop as that is managed internally because of UX reasons
  and having a fixed height will break that behavior
</Notice>

### Select.Group

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [ListItem](/docs/components/list-item). Used to label Groups.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values ot the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.Adapt.Contents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="maxMd" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <Adapt.Contents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/2.0.0

---
title: Select
description: Show a menu of items that users can select from
name: select
component: Select
package: select
demoName: Select
---

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

Select provides a dropdown menu for choosing from a list of options. It's fully accessible with keyboard navigation, supports typeahead search, and [automatically stacks](/ui/z-index) above other content.

## Installation

Select is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/select
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/docs/components/portal#native-portal-setup-recommended) to preserve React
  context inside Select content.
</Notice>

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    {/* Optional: Control focus behavior */}
    <Select.FocusScope loop trapped focusOnIdle={true}>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton />
      </Select.Content>
    </Select.FocusScope>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

## API Reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label.`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements.`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value.`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value.`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change.`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change.`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms.`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
    {
      name: 'renderValue',
      type: '(value: string) => ReactNode',
      description: `Render function for the selected value. Useful for SSR when you need custom display text. By default, Select falls back to showing the raw value for SSR compatibility.`,
    },
    {
      name: 'lazyMount',
      type: 'boolean',
      default: 'false',
      description: `When true, defers mounting Select items until opened using React's startTransition. Significantly improves initial render performance for pages with many Selects. Should be combined with \`renderValue\` for best results.`,
    },
    {
      name: 'zIndex',
      type: 'number',
      description: `z-index for the select portal. Use when select dropdowns need to appear above other portaled content like dialogs or fixed headers. Defaults to automatic stacking (~100000).`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected.`,
    },
  ]}
/>

### Select.Content

Main container for Select content, used to contain the up/down arrows, no API beyond children.

### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles.`,
    },
  ]}
/>

<Notice>
  Make sure to not pass `height` prop as that is managed internally because of UX reasons
  and having a fixed height will break that behavior.
</Notice>

### Select.Group

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [SizableText](/docs/components/text). Used to label Groups. Includes size-based padding and minHeight for consistent appearance with other Select items.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values to the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.Indicator

An animated indicator that highlights the currently focused item. Place it inside `Select.Viewport` to enable a smooth sliding highlight animation as users navigate through options.

```tsx
<Select.Viewport>
  <Select.Indicator transition="quick" />
  <Select.Group>{/* items */}</Select.Group>
</Select.Viewport>
```

Use the `transition` prop to control the animation speed. You can use any animation name from your config like `quick`, `quicker`, or `quickest`.

<Notice>
  By default, Select uses the item's `hover:` and `press:` clauses for hover feedback. Add
  `Select.Indicator` for a smoother animated effect. If using the indicator, you may want
  to set items to have transparent hover styles to avoid visual conflict.
</Notice>

### Select.FocusScope

Provides access to the underlying FocusScope component used by Select for focus management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled.`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable.`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus.`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations.`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented.`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented.`,
    },
  ]}
/>

## Performance

For pages with many Select components, you can significantly improve initial render performance by using the `lazyMount` prop combined with `renderValue`:

```tsx
const labels = {
  apple: 'Apple',
  orange: 'Orange',
  banana: 'Banana',
}

<Select
  lazyMount
  renderValue={(value) => labels[value]}
  defaultValue="apple"
>
  {/* Items are not mounted until the Select is opened */}
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Content>
    <Select.Viewport>
      {/* These items mount in a startTransition when first opened */}
      <Select.Item index={0} value="apple">
        <Select.ItemText>Apple</Select.ItemText>
      </Select.Item>
      {/* ... more items */}
    </Select.Viewport>
  </Select.Content>
</Select>
```

**How it works:**

- `lazyMount` defers mounting all Select items until the dropdown is first opened
- The mount happens inside React's `startTransition`, keeping the trigger responsive
- `renderValue` provides the display text synchronously, avoiding the need to mount items just to show the selected value
- Once mounted, items stay mounted for fast subsequent opens

This is especially useful when rendering many Selects on a single page, as each Select with 20+ items would otherwise mount all those items on initial page load.

### Select.Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.Adapt.Contents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="max-md" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <Adapt.Contents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/3.0.0

---
title: Select
description: Show a menu of items that users can select from
name: select
component: Select
package: select
demoName: Select
---

<IntroParagraph>
  Select gives users an accessible, keyboard-navigable list of choices and can
  adapt its content into a Sheet on smaller screens.
</IntroParagraph>

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Transitions, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
    `Shared Sheet handoff with Dialog and Popover`,
  ]}
/>

Select provides a dropdown menu for choosing from a list of options. It's fully accessible with keyboard navigation, supports typeahead search, and [automatically stacks](/ui/z-index) above other content.

In v3, Select keeps adapted sheet content mounted through the sheet exit
animation, and web trigger and viewport parts expose `data-state="open" | "closed"`
for styling.

Select also supports ordered multiple selection across custom web lists,
browser-native controls, adapted Sheets, and plain React Native content. The
same item registry and value controller power every path.

## Installation

Select is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/select
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/ui/portal#native-portal-setup-recommended) to preserve React
  context inside Select content.
</Notice>

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    {/* Optional: Control focus behavior */}
    <Select.FocusScope loop trapped focusOnIdle={true}>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton />
      </Select.Content>
    </Select.FocusScope>
  </Select>
)
```

## Multiple selection

Pass `multiple` to use a controlled or uncontrolled `string[]`. Selecting a new
item appends it. Selecting it again removes it without changing the order of the
remaining values. Multiple selection keeps custom lists and adapted Sheets open.

```tsx
const [fruit, setFruit] = useState<Array<'apple' | 'pear'>>([])

<Select multiple name="fruit" value={fruit} onValueChange={setFruit}>
  <Select.Trigger>
    <Select.Value placeholder="Choose fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Viewport>
      <Select.Item value="apple">
        <Select.ItemText>Apple</Select.ItemText>
        <Select.ItemIndicator />
      </Select.Item>
      <Select.Item value="pear">
        <Select.ItemText>Pear</Select.ItemText>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Viewport>
  </Select.Content>
</Select>
```

`Select.Value` renders registered `Select.ItemText` labels in selection order,
separated by `, `. Use `renderValue` for chips, localized separators, summaries,
or labels that must render before lazy items mount.

```tsx
<Select
  multiple
  value={fruit}
  renderValue={(values) => `${values.length} selected`}
/>
```

### Behavior by render path

- A custom floating web Select is an ARIA multi-select listbox. Arrow keys and
  typeahead move focus. Enter and Space toggle the focused option.
- `native="web"` renders a real `<select multiple>`. Browser selection,
  keyboard behavior, and form submission are authoritative.
- An adapted Sheet uses the same listbox controller on web and stays open after
  each toggle. The Sheet closes through its overlay, drag-to-bottom behavior,
  platform back action, or controlled state. Select does not add a Done row.
- Plain React Native content renders inline when no Adapt target is active.
  Multiple items expose checkbox-style accessibility state and remain visible
  after a toggle.

On custom web paths, `name` renders one root-level hidden input per selected
value, including when the collection is portaled into a Sheet. `form` can point
those inputs at an external form. The browser-native path puts `name` and `form`
on its `<select>` directly and does not render hidden inputs. React Native does
not render HTML form controls.

## API reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label.`,
    },
    {
      name: 'size',
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `Set the size of itself and pass to all inner elements.`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components.`,
    },
    {
      name: 'value',
      type: 'string | string[]',
      description: `Controlled value. With multiple, this is an ordered string array.`,
    },
    {
      name: 'defaultValue',
      type: 'string | string[]',
      description: `Default value. With multiple, this defaults to an empty array.`,
    },
    {
      name: 'multiple',
      type: 'boolean',
      default: 'false',
      description: `Enables ordered multiple selection and makes value callbacks array-valued.`,
    },
    {
      name: 'onValueChange',
      type: '(value, details) => void',
      description: `Cancelable value request. Details identify item-press, keyboard, or native-change.`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean, details) => void',
      description: `Cancelable open request with the interaction reason and source event.`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Web form field name. Multiple values submit as repeated entries.`,
    },
    {
      name: 'form',
      type: 'string',
      description: `Associates the web form control with an external form id.`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
    {
      name: 'renderValue',
      type: '(value: string | string[]) => ReactNode',
      description: `Render function for the selected value. Multiple mode receives the ordered string array. Useful for SSR, lazy mounting, chips, and custom summaries.`,
    },
    {
      name: 'lazyMount',
      type: 'boolean',
      default: 'false',
      description: `When true, defers mounting Select items until opened using React's startTransition. Significantly improves initial render performance for pages with many Selects. Should be combined with \`renderValue\` for best results.`,
    },
    {
      name: 'zIndex',
      type: 'number',
      description: `z-index for the select portal. Use when select dropdowns need to appear above other portaled content like dialogs or fixed headers. Defaults to automatic stacking (~100000).`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/ui/list-item) to give sizing, icons, and more.
On web it includes `data-state="open" | "closed"`.

### Select.Value

Extends [Paragraph](/ui/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected.`,
    },
  ]}
/>

### Select.Content

Main container for Select content, used to contain the up/down arrows.

<PropsTable
  data={[
    {
      name: 'onEscapeKeyDown',
      type: '(event: KeyboardEvent) => void',
      description: `Called when Escape is pressed while the content is active.`,
    },
    {
      name: 'onInteractOutside',
      type: '(event: Event) => void',
      description: `Called when pointer or focus interaction happens outside the content.`,
    },
    {
      name: 'onPointerDownOutside',
      type: '(event: Event) => void',
      description: `Called on outside pointer down. Select composes this with its own preventDefault handling.`,
    },
    {
      name: 'onFocusOutside',
      type: '(event: Event) => void',
      description: `Called on outside focus. Select composes this with its own preventDefault handling.`,
    },
  ]}
/>

### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/ui/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/ui/stacks).

### Select.Viewport

Extends [YStack](/ui/stacks). Contains scrollable content items as children.
On web it includes `data-state="open" | "closed"`.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles.`,
    },
  ]}
/>

<Notice>
  Make sure to not pass `height` prop as that is managed internally because of UX reasons
  and having a fixed height will break that behavior.
</Notice>

### Select.Group

Extends [YStack](/ui/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [SizableText](/ui/text). Used to label Groups. Includes size-based padding and minHeight for consistent appearance with other Select items.

### Select.Separator

Extends [Separator](/ui/separator). Use inside `Select.Group` or
`Select.Viewport` to visually divide option groups.

### Select.Item

Extends [ListItem](/ui/list-item). Used to add selectable string values to the
list. Item registration order controls keyboard navigation, typeahead, and
selection anchoring.

<PropsTable
  data={[
    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/ui/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.Indicator

An animated indicator that highlights the currently focused item. Place it inside `Select.Viewport` to enable a smooth sliding highlight animation as users navigate through options.

```tsx
<Select.Viewport>
  <Select.Indicator transition="quick" />
  <Select.Group>{/* items */}</Select.Group>
</Select.Viewport>
```

Use the `transition` prop to control the animation speed. You can use any animation name from your config like `quick`, `quicker`, or `quickest`.

<Notice>
  By default, Select uses the item's `hover:` and `press:` clauses for hover feedback. Add
  `Select.Indicator` for a smoother animated effect. If using the indicator, you may want
  to set items to have transparent hover styles to avoid visual conflict.
</Notice>

### Select.FocusScope

Provides access to the underlying FocusScope component used by Select for focus management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled.`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable.`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus.`,
    },
    {
      name: 'noFocus',
      type: 'boolean',
      default: 'false',
      description: `Zero focus mode. While active, focus is allowed neither inside nor outside the scope. Web only.`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'true',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations.`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented.`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented.`,
    },
  ]}
/>

## Performance

For pages with many Select components, you can significantly improve initial render performance by using the `lazyMount` prop combined with `renderValue`:

```tsx
const labels = {
  apple: 'Apple',
  orange: 'Orange',
  banana: 'Banana',
}

<Select
  lazyMount
  renderValue={(value) => labels[value]}
  defaultValue="apple"
>
  {/* Items are not mounted until the Select is opened */}
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Content>
    <Select.Viewport>
      {/* These items mount in a startTransition when first opened */}
      <Select.Item value="apple">
        <Select.ItemText>Apple</Select.ItemText>
      </Select.Item>
      {/* ... more items */}
    </Select.Viewport>
  </Select.Content>
</Select>
```

**How it works:**

- `lazyMount` defers mounting all Select items until the dropdown is first opened
- The mount happens inside React's `startTransition`, keeping the trigger responsive
- `renderValue` provides the display text synchronously, avoiding the need to mount items just to show the selected value
- Once mounted, items stay mounted for fast subsequent opens

This is especially useful when rendering many Selects on a single page, as each Select with 20+ items would otherwise mount all those items on initial page load.

### Adapted Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active. See [Adapt](/ui/adapt) for how the handoff works.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/ui/sheet) for more props.

Use `Adapt.Contents` inside `Sheet.Container` to insert the contents given to
`Select.Content`.

```tsx
import { Adapt, Select, Sheet } from 'tamagui'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="max-md" platform="touch">
      <Sheet modal dismissOnSnapToBottom>
        <Sheet.Container>
          <Sheet.Background />
          <Adapt.Contents />
        </Sheet.Container>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
          <Select.Separator />
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/1.19.0

---
title: Select
description: A simple select component
name: select
component: Select
package: select
demoName: Select
---

# Select

<Description>Show a menu of items users can select from one of</Description>

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

## API Reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### SelectContent

Main container for Select content, used to contain the up/down arrows, no API beyond children.

#### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
  ]}
/>

### Select.Group

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [ListItem](/docs/components/list-item). Used to label Groups.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values ot the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.SheetContents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="maxMd" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <SheetContents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/select/1.141.0

---
title: Select
description: Show a menu of items that users can select from.
name: select
component: Select
package: select
demoName: Select
---

<HeroContainer>
  <SelectDemo />
</HeroContainer>

```tsx hero template=Select

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Full-featured, accessible, and keyboard navigable`,
  ]}
/>

## Installation

Select is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/select
```

## Anatomy

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>
    {/* Optional: Control focus behavior */}
    <Select.FocusScope loop trapped focusOnIdle={true}>
      <Select.Content>
        <Select.ScrollUpButton />
        <Select.Viewport>
          <Select.Group>
            <Select.Label />
            <Select.Item>
              <Select.ItemText />
            </Select.Item>
          </Select.Group>
        </Select.Viewport>
        <Select.ScrollDownButton />
      </Select.Content>
    </Select.FocusScope>
  </Select>
)
```

<Notice>
  Note that Select only works on Native using the Adapt component to adapt it to a Sheet.
  See below for docs.
</Notice>

## Server-Side Rendering (SSR)

By default, Select uses a portal-based mechanism to display the selected item's text in the trigger. This happens in a client-side effect, which can cause hydration mismatches when using SSR.

To fix this, use the `renderValue` prop to provide the label synchronously during render:

```tsx
const items = [
  { value: 'apple', label: 'Apple' },
  { value: 'orange', label: 'Orange' },
]

// Create a lookup function
const getLabel = (value: string) => items.find((item) => item.value === value)?.label

export function MySelect() {
  const [value, setValue] = React.useState('apple')

  return (
    <Select value={value} onValueChange={setValue} renderValue={getLabel}>
      <Select.Trigger>
        <Select.Value placeholder="Select a fruit..." />
      </Select.Trigger>

      <Select.Content>
        <Select.Viewport>
          {items.map((item, i) => (
            <Select.Item key={item.value} value={item.value} index={i}>
              <Select.ItemText>{item.label}</Select.ItemText>
            </Select.Item>
          ))}
        </Select.Viewport>
      </Select.Content>
    </Select>
  )
}
```

When `renderValue` is provided, it's called synchronously during render, ensuring the server and client render the same content.

## API Reference

### Select

Contains every component for the select:

<PropsTable
  data={[
    {
      name: 'id',
      type: 'string',
      description: `Optional for usage with Label`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Set the size of itself and pass to all inner elements`,
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: `Select children API components`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value`,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: `Callback on value change`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open value`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Default open value`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Callback on open change`,
    },
    {
      name: 'dir',
      type: 'Direction',
      description: `Direction of text display`,
    },
    {
      name: 'name',
      type: 'string',
      description: `For use in forms`,
    },
    {
      name: 'native',
      type: 'NativeValue',
      description: `If passed, will render a native component instead of the custom one. Currently only \`web\` is supported.`,
    },
    {
      name: 'renderValue',
      type: '(value: string) => React.ReactNode',
      description: `Render function for the selected value. Use this for SSR support to avoid hydration mismatches. When provided, this is called synchronously during render to display the selected value.`,
    },
  ]}
/>

### Select.Trigger

Extends [ListItem](/docs/components/list-item) to give sizing, icons, and more.

#### Select.Value

Extends [Paragraph](/docs/components/text), adding:

<PropsTable
  data={[
    {
      name: 'placeholder',
      type: 'string',
      description: `Optional placeholder to show when no value selected`,
    },
  ]}
/>

#### SelectContent

Main container for Select content, used to contain the up/down arrows, no API beyond children.

#### Select.ScrollUpButton

Inside Content first, displays when you can scroll up, stuck to the top.

Extends [YStack](/docs/components/stacks).

### Select.ScrollDownButton

Inside Content last, displays when you can scroll down, stuck to the bottom.

Extends [YStack](/docs/components/stacks).

### Select.Viewport

Extends [ThemeableStack](/docs/components/stacks#themeablestack). Contains scrollable content items as children.

<PropsTable
  data={[
    {
      name: 'disableScroll',
      type: 'boolean',
      description: `Removes ability to scroll and all style and functionality related to scrolling`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      description: `Removes all default styles`,
    },
  ]}
/>

<Notice>
  Make sure to not pass `height` prop as that is managed internally because of UX reasons
  and having a fixed height will break that behavior
</Notice>

### Select.Group

Extends [YStack](/docs/components/stacks). Use only when grouping together items, alongside a Label as the first child.

### Select.Label

Extends [ListItem](/docs/components/list-item). Used to label Groups.

### Select.Item

Extends [ListItem](/docs/components/list-item). Used to add selectable values to the list. Must provide an index as React Native doesn't give any escape hatch for us to configure that automatically.

<PropsTable
  data={[
    {
      name: 'index',
      type: 'number',
      required: true,
      description: `Incrementally starting from 0, matching its appearance in the list.`,
    },

    {
      name: 'value',
      type: 'string',
      description: `Provide a value that will be passed on selection.`,
    },

]}
/>

### Select.ItemText

Extends [Paragraph](/docs/components/text). Used inside Item to provide unselectable text that will show above once selected in the parent Select.

### Select.FocusScope

Provides access to the underlying FocusScope component used by Select for focus management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Select.Sheet

When used alongside `<Adapt />`, Select will render as a sheet when that breakpoint is active.

This is the only way to render a Select on Native for now, as mobile apps tend to show Select very differently from web and Tamagui wants to present the right abstractions for each platform.

See [Sheet](/docs/components/sheet) for more props.

Must use `Select.Adapt.Contents` inside the `Select.Sheet.Frame` to insert the contents given to `Select.Content`

```tsx
import { Select } from 'tamagui' // or '@tamagui/select'

export default () => (
  <Select defaultValue="">
    <Select.Trigger>
      <Select.Value placeholder="Search..." />
    </Select.Trigger>

    <Adapt when="maxMd" platform="touch">
      {/* or <Select.Sheet> */}
      <Sheet>
        <Sheet.Frame>
          <Adapt.Contents />
        </Sheet.Frame>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>

    <Select.Content>
      <Select.ScrollUpButton />
      <Select.Viewport>
        <Select.Group>
          <Select.Label />
          <Select.Item>
            <Select.ItemText />
          </Select.Item>
        </Select.Group>
      </Select.Viewport>
      <Select.ScrollDownButton />
    </Select.Content>
  </Select>
)
```


## components/radio-group/1.3.0

---
title: RadioGroup
description: Use in a form to allow selecting one option from multiple.
name: radio-group
component: RadioGroup
package: radio-group
demoName: RadioGroup
---

<HeroContainer>
  <RadioGroupDemo />
</HeroContainer>

```tsx hero template=RadioGroup

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Sizing with controlled or uncontrolled state`,
    `Optional native HTML radio buttons on web`,
  ]}
/>

## Installation

RadioGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/radio-group
```

## Usage

```tsx
import { RadioGroup } from 'tamagui'

export default () => (
  <RadioGroup value="foo" gap="2">
    <RadioGroup.Item value="foo" id="foo-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
    <RadioGroup.Item value="bar" id="bar-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
  </RadioGroup>
)
```

## API Reference

### RadioGroup

RadioGroup extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native for all children items`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native radio button on web.`,
      default: false,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
    },
    {
      name: 'accentColor',
      type: 'string',
      description: 'Sets `accent-color` style when `native` prop is enabled',
    },
  ]}
/>

### RadioGroup.Item

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by on web`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Input value for the radio button.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native`,
    },
    {
      name: 'id',
      type: 'string',
      description: `Id used on the web`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### RadioGroup.Indicator

RadioGroup.Indicator appears only when the parent Item is checked. it extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props) adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/radio-group/1.2.0

---
title: RadioGroup
description: A group of radio buttons
name: radio-group
component: RadioGroup
package: radio-group
demoName: RadioGroup
---

# RadioGroup

<Description>Choose one option from a list in a form.</Description>

<YStack className="is-sticky" />

<Tabs id="type" defaultValue="styled">
<Tabs.List>
  <TooltipSimple label="With Tamagui's default styles">
    <Tabs.Tab value="styled">Styled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No default styles, easy to customize">
    <Tabs.Tab value="unstyled">Unstyled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No dependency on Tamagui's core">
    <Tabs.Tab value="headless" label="No styles and no dependency on Tamagui's styling">Headless</Tabs.Tab>
  </TooltipSimple>
</Tabs.List>

<HeroContainer showAnimationDriverControl>
  <Tabs.Content value="styled" justifyContent="center" alignItems="center" width="100%">
    <RadioGroupDemo />
  </Tabs.Content>
  <Tabs.Content value="unstyled" justifyContent="center" alignItems="center" width="100%">
    <RadioGroupCustomDemo />
  </Tabs.Content>
  <Tabs.Content value="headless" justifyContent="center" alignItems="center" width="100%">
    <RadioGroupHeadlessDemo />
  </Tabs.Content>
</HeroContainer>

<Tabs.Content value="styled">
```tsx hero template=RadioGroup

```
</Tabs.Content>
<Tabs.Content value="unstyled">
```tsx hero template=RadioGroupCustom

```

</Tabs.Content>
<Tabs.Content value="headless">
```tsx hero template=RadioGroupHeadless

```
</Tabs.Content>

<Highlights
features={[
  `Accessible, composable, and customizable`,
  `Sizing with controlled or uncontrolled state`,
  `Optional native HTML radio buttons on web`,
]}
/>

## Installation

<Tabs.Content value="styled">
RadioGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/radio-group
```

</Tabs.Content>

<Tabs.Content value="unstyled">
RadioGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/radio-group
```

</Tabs.Content>

<Tabs.Content value="headless">

To use the headless radio group, you want to import it from the
`@tamagui/radio-headless` package. This package has no dependency on
`@tamagui/core`, but still works off the react-native APIs.
This means can bring your own style library.

```bash
npm install @tamagui/radio-headless
```

</Tabs.Content>

## Usage

<Tabs.Content value="styled">

```tsx
import { RadioGroup } from 'tamagui'

export default () => (
  <RadioGroup value="foo" gap="2">
    <RadioGroup.Item value="foo" id="foo-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
    <RadioGroup.Item value="bar" id="bar-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
  </RadioGroup>
)
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Use the `createRadioGroup` export to create a fully custom RadioGroup that still
uses the Tamagui styling system. This is similar to setting `unstyled`, but goes
a bit further. It doesn't add any types for `size` or `unstyled`, and it won't
automatically apply the `active` theme. If does pass the `checked` prop down as
indicated in the types of `createRadioGroup`.

```tsx template=RadioGroupCustom

```

</Tabs.Content>

<Tabs.Content value="headless">

Using the `useRadioGroup` and `useRadioGroupItem` API, you can make your own RadioGroup from scratch.

```tsx template=RadioGroupHeadless

```

</Tabs.Content>

<Tabs.Content value="styled">

## API Reference

### RadioGroup

RadioGroup extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native for all children items`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native radio button on web.`,
      default: false,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
    },
    {
      name: 'accentColor',
      type: 'string',
      description: 'Sets `accent-color` style when `native` prop is enabled',
    },
  ]}
/>

### RadioGroup.Item

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by on web`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Input value for the radio button.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native`,
    },
    {
      name: 'id',
      type: 'string',
      description: `Id used on the web`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### RadioGroup.Indicator

RadioGroup.Indicator appears only when the parent Item is checked. it extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props) adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

</Tabs.Content>
<Tabs.Content value="unstyled">

## API Reference

### RadioGroup

RadioGroup extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native for all children items`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native radio button on web.`,
      default: false,
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
    },
    {
      name: 'accentColor',
      type: 'string',
      description: 'Sets `accent-color` style when `native` prop is enabled',
    },
  ]}
/>

### RadioGroup.Item

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by on web`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Input value for the radio button.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Set aria-disabled on web, and disable touch on native`,
    },
    {
      name: 'id',
      type: 'string',
      description: `Id used on the web`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

### RadioGroup.Indicator

RadioGroup.Indicator appears only when the parent Item is checked. it extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props) adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

</Tabs.Content>

</Tabs>


## components/radio-group/2.0.0

---
title: RadioGroup
description: Use in a form to allow selecting one option from multiple
name: radio-group
component: RadioGroup
package: radio-group
demoName: RadioGroup
---

<HeroContainer>
  <RadioGroupDemo />
</HeroContainer>

```tsx hero template=RadioGroup

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Sizing with controlled or uncontrolled state`,
    `Optional native HTML radio buttons on web`,
  ]}
/>

## Installation

RadioGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/radio-group
```

## Usage

```tsx
import { RadioGroup } from 'tamagui'

export default () => (
  <RadioGroup value="foo" gap="2">
    <RadioGroup.Item value="foo" id="foo-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
    <RadioGroup.Item value="bar" id="bar-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
  </RadioGroup>
)
```

### Headless Usage

To use headless without `@tamagui/core`, install `@tamagui/radio-headless`:

```bash
npm install @tamagui/radio-headless
```

The `@tamagui/radio-headless` package provides three hooks for building custom radio groups:

- `useRadioGroup` - for the container/group
- `useRadioGroupItem` - for individual radio items
- `useRadioGroupItemIndicator` - for the indicator (checked state visual)

```tsx
import {
  useRadioGroup,
  useRadioGroupItem,
  useRadioGroupItemIndicator,
  RadioGroupContextValue,
  RadioGroupItemContextValue,
} from '@tamagui/radio-headless'
import { createContext, useContext } from 'react'

// Create contexts for the group and item
const RadioGroupContext = createContext<RadioGroupContextValue>({})
const RadioGroupItemContext = createContext<RadioGroupItemContextValue>({
  checked: false,
})

function RadioGroup({ children, ...props }) {
  const { providerValue, frameAttrs } = useRadioGroup({
    orientation: 'vertical',
    ...props,
  })

  return (
    <RadioGroupContext.Provider value={providerValue}>
      <div {...frameAttrs} style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        {children}
      </div>
    </RadioGroupContext.Provider>
  )
}

function RadioItem({ value, children }) {
  const { checked, providerValue, frameAttrs, bubbleInput } = useRadioGroupItem({
    radioGroupContext: RadioGroupContext,
    value,
  })

  return (
    <RadioGroupItemContext.Provider value={providerValue}>
      <button
        {...frameAttrs}
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: 8,
          padding: 8,
          border: '1px solid #ccc',
          borderRadius: 4,
          background: checked ? '#e0f2fe' : 'white',
        }}
      >
        <RadioIndicator />
        {children}
      </button>
      {bubbleInput}
    </RadioGroupItemContext.Provider>
  )
}

function RadioIndicator() {
  const { checked, ...indicatorProps } = useRadioGroupItemIndicator({
    radioGroupItemContext: RadioGroupItemContext,
  })

  return (
    <div
      {...indicatorProps}
      style={{
        width: 16,
        height: 16,
        borderRadius: '50%',
        border: '2px solid #3b82f6',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      {checked && (
        <div
          style={{ width: 8, height: 8, borderRadius: '50%', background: '#3b82f6' }}
        />
      )}
    </div>
  )
}

// Usage
function App() {
  return (
    <RadioGroup defaultValue="option1" onValueChange={console.log}>
      <RadioItem value="option1">Option 1</RadioItem>
      <RadioItem value="option2">Option 2</RadioItem>
      <RadioItem value="option3">Option 3</RadioItem>
    </RadioGroup>
  )
}
```

## API Reference

### RadioGroup

RadioGroup extends View, inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name attribute.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value of the selected radio item.`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value for uncontrolled usage.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required attribute.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Sets aria-disabled on web, and disables touch on native for all children items.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native radio button on web.`,
      default: 'false',
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: 'Called when the selected value changes.',
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      description: 'Orientation of the radio group.',
    },
    {
      name: 'accentColor',
      type: 'string',
      description: 'Sets `accent-color` style when `native` prop is enabled.',
    },
  ]}
/>

### RadioGroup.Item

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Sets aria-labelledby on web.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Input value for the radio button.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Sets aria-disabled on web, and disables touch on native.`,
    },
    {
      name: 'id',
      type: 'string',
      description: `ID used on the web.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
  ]}
/>

### RadioGroup.Indicator

RadioGroup.Indicator appears only when the parent Item is checked. It extends [YStack](/ui/stacks), getting [Tamagui standard props](/docs/intro/props) adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

## Headless Props

### useRadioGroup Return Value

| Property                | Type                     | Description                                                           |
| ----------------------- | ------------------------ | --------------------------------------------------------------------- |
| `providerValue`         | `RadioGroupContextValue` | Value to pass to your context provider                                |
| `frameAttrs`            | `object`                 | Props to spread on the group container (role, aria-orientation, etc.) |
| `rovingFocusGroupAttrs` | `object`                 | Props for roving focus behavior (optional)                            |

### useRadioGroupItem

Hook for individual radio items. Requires a context containing the group state.

```tsx
const {
  checked,
  isFormControl,
  providerValue,
  bubbleInput,
  native,
  frameAttrs,
  rovingFocusGroupAttrs,
} = useRadioGroupItem({
  radioGroupContext: YourRadioGroupContext,
  value: 'option1',
  id: 'option1-id',
  labelledBy: 'label-id',
  disabled: false,
  onPress: () => {},
  onKeyDown: () => {},
  onFocus: () => {},
})
```

| Property        | Type        | Description                             |
| --------------- | ----------- | --------------------------------------- |
| `checked`       | `boolean`   | Whether this item is currently selected |
| `providerValue` | `object`    | Context value for the indicator         |
| `frameAttrs`    | `object`    | Props to spread on the item element     |
| `bubbleInput`   | `ReactNode` | Hidden input for form compatibility     |
| `native`        | `boolean`   | Whether using native radio              |
| `isFormControl` | `boolean`   | Whether inside a form                   |

### useRadioGroupItemIndicator

Hook for the visual indicator of checked state.

```tsx
const { checked, ...dataAttrs } = useRadioGroupItemIndicator({
  radioGroupItemContext: YourRadioGroupItemContext,
  disabled: false,
})
```

| Property        | Type                  | Description                        |
| --------------- | --------------------- | ---------------------------------- |
| `checked`       | `boolean`             | Whether the parent item is checked |
| `data-state`    | `string`              | 'checked' or 'unchecked'           |
| `data-disabled` | `string \| undefined` | Present when disabled              |


## components/radio-group/3.0.0

---
title: RadioGroup
description: Use in a form to allow selecting one option from multiple
name: radio-group
component: RadioGroup
package: radio-group
demoName: RadioGroup
---

<IntroParagraph>
  RadioGroup lets users choose one option from a keyboard-navigable set on web
  and native.
</IntroParagraph>

<HeroContainer>
  <RadioGroupDemo />
</HeroContainer>

```tsx hero template=RadioGroup

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Sizing with controlled or uncontrolled state`,
    `Optional native HTML radio buttons on web`,
  ]}
/>

## Installation

RadioGroup is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/radio-group
```

## Usage

```tsx
import { RadioGroup } from 'tamagui'

export default () => (
  <RadioGroup value="foo" gap="2">
    <RadioGroup.Item value="foo" id="foo-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
    <RadioGroup.Item value="bar" id="bar-radio-item">
      <RadioGroup.Indicator />
    </RadioGroup.Item>
  </RadioGroup>
)
```

### Headless usage

To use headless without `@tamagui/core`, install `@tamagui/radio-headless`:

```bash
npm install @tamagui/radio-headless
```

The `@tamagui/radio-headless` package provides three hooks for building custom radio groups:

- `useRadioGroup` - for the container/group
- `useRadioGroupItem` - for individual radio items
- `useRadioGroupItemIndicator` - for the indicator (checked state visual)

```tsx
import {
  useRadioGroup,
  useRadioGroupItem,
  useRadioGroupItemIndicator,
  RadioGroupContextValue,
  RadioGroupItemContextValue,
} from '@tamagui/radio-headless'
import { createContext, useContext } from 'react'

// Create contexts for the group and item
const RadioGroupContext = createContext<RadioGroupContextValue>({})
const RadioGroupItemContext = createContext<RadioGroupItemContextValue>({
  checked: false,
})

function RadioGroup({ children, ...props }) {
  const { providerValue, frameAttrs } = useRadioGroup({
    orientation: 'vertical',
    ...props,
  })

  return (
    <RadioGroupContext.Provider value={providerValue}>
      <div {...frameAttrs} style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
        {children}
      </div>
    </RadioGroupContext.Provider>
  )
}

function RadioItem({ value, children }) {
  const { checked, providerValue, frameAttrs, bubbleInput } = useRadioGroupItem({
    radioGroupContext: RadioGroupContext,
    value,
  })

  return (
    <RadioGroupItemContext.Provider value={providerValue}>
      <button
        {...frameAttrs}
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: 8,
          padding: 8,
          border: '1px solid #ccc',
          borderRadius: 4,
          background: checked ? '#e0f2fe' : 'white',
        }}
      >
        <RadioIndicator />
        {children}
      </button>
      {bubbleInput}
    </RadioGroupItemContext.Provider>
  )
}

function RadioIndicator() {
  const { checked, ...indicatorProps } = useRadioGroupItemIndicator({
    radioGroupItemContext: RadioGroupItemContext,
  })

  return (
    <div
      {...indicatorProps}
      style={{
        width: 16,
        height: 16,
        borderRadius: '50%',
        border: '2px solid #3b82f6',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      {checked && (
        <div
          style={{ width: 8, height: 8, borderRadius: '50%', background: '#3b82f6' }}
        />
      )}
    </div>
  )
}

// Usage
function App() {
  return (
    <RadioGroup defaultValue="option1" onValueChange={console.log}>
      <RadioItem value="option1">Option 1</RadioItem>
      <RadioItem value="option2">Option 2</RadioItem>
      <RadioItem value="option3">Option 3</RadioItem>
    </RadioGroup>
  )
}
```

## API reference

### RadioGroup

RadioGroup extends View, inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name attribute.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Controlled value of the selected radio item.`,
    },
    {
      name: 'defaultValue',
      type: 'string',
      description: `Default value for uncontrolled usage.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required attribute.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Sets aria-disabled on web, and disables touch on native for all children items.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native radio button on web.`,
      default: 'false',
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      description: 'Called when the selected value changes.',
    },
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      description: 'Orientation of the radio group.',
    },
    {
      name: 'accentColor',
      type: 'string',
      description: 'Sets `accent-color` style when `native` prop is enabled.',
    },
  ]}
/>

### RadioGroup.Item

Item sizes come from the shared [Sizing](/docs/core/sizing) ladder.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: the circle is the ladder's square derivation.`,
    },
    {
      name: 'labeledBy',
      type: 'string',
      description: `Sets aria-labelledby on web.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Input value for the radio button.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Sets aria-disabled on web, and disables touch on native.`,
    },
    {
      name: 'id',
      type: 'string',
      description: `ID used on the web.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
  ]}
/>

### RadioGroup.Indicator

RadioGroup.Indicator appears only when the parent Item is checked. It extends [YStack](/ui/stacks), getting [Tamagui standard props](/docs/intro/props) adding:

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

## Headless props

### useRadioGroup return value

| Property                | Type                     | Description                                                           |
| ----------------------- | ------------------------ | --------------------------------------------------------------------- |
| `providerValue`         | `RadioGroupContextValue` | Value to pass to your context provider                                |
| `frameAttrs`            | `object`                 | Props to spread on the group container (role, aria-orientation, etc.) |
| `rovingFocusGroupAttrs` | `object`                 | Props for roving focus behavior (optional)                            |

### useRadioGroupItem

Hook for individual radio items. Requires a context containing the group state.

```tsx
const {
  checked,
  isFormControl,
  providerValue,
  bubbleInput,
  native,
  frameAttrs,
  rovingFocusGroupAttrs,
} = useRadioGroupItem({
  radioGroupContext: YourRadioGroupContext,
  value: 'option1',
  id: 'option1-id',
  labelledBy: 'label-id',
  disabled: false,
  onPress: () => {},
  onKeyDown: () => {},
  onFocus: () => {},
})
```

| Property        | Type        | Description                             |
| --------------- | ----------- | --------------------------------------- |
| `checked`       | `boolean`   | Whether this item is currently selected |
| `providerValue` | `object`    | Context value for the indicator         |
| `frameAttrs`    | `object`    | Props to spread on the item element     |
| `bubbleInput`   | `ReactNode` | Hidden input for form compatibility     |
| `native`        | `boolean`   | Whether using native radio              |
| `isFormControl` | `boolean`   | Whether inside a form                   |

### useRadioGroupItemIndicator

Hook for the visual indicator of checked state.

```tsx
const { checked, ...dataAttrs } = useRadioGroupItemIndicator({
  radioGroupItemContext: YourRadioGroupItemContext,
  disabled: false,
})
```

| Property        | Type                  | Description                        |
| --------------- | --------------------- | ---------------------------------- |
| `checked`       | `boolean`             | Whether the parent item is checked |
| `data-state`    | `string`              | 'checked' or 'unchecked'           |
| `data-disabled` | `string \| undefined` | Present when disabled              |


## components/avatar/1.0.0

---
title: Avatar
description: Display aspect-fixed images with a fallback while loading
name: avatar
component: Avatar
package: avatar
demoName: Avatar
---

<HeroContainer>
  <AvatarDemo />
</HeroContainer>

```tsx hero template=Avatar

```

<Highlights
  features={[
    'Size matching across components',
    'Full styling control for every element',
    'Automatic fallback replacement on image load',
  ]}
/>

## Installation

Avatar is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/avatar
```

## Usage

```tsx
import { Avatar } from 'tamagui'

export default () => (
  <Avatar circular size="6">
    <Avatar.Image src="http://picsum.photos/200/300" />
    <Avatar.Fallback bc="red" />
  </Avatar>
)
```

## API Reference

### Avatar

Avatar extends [Square](/docs/components/shapes#shape-props), giving it all the [Tamagui standard props](/docs/intro/props) as well as `size` and `circular`.

### Avatar.Fallback

Avatar.Fallback extends [YStack](/docs/components/stacks), plus:

<PropsTable
  data={[
    {
      name: 'delayMs',
      required: false,
      type: 'number',
      description: `Milliseconds to wait before showing the fallback, to prevent flicker.`,
    },
  ]}
/>

### Avatar.Image

Avatar.Image extends [Image](/docs/components/image).


## components/avatar/2.0.0

---
title: Avatar
description: Display aspect-ratio-fixed images with a fallback while loading
name: avatar
component: Avatar
package: avatar
demoName: Avatar
---

<HeroContainer>
  <AvatarDemo />
</HeroContainer>

```tsx hero template=Avatar

```

<Highlights
  features={[
    'Size matching across components',
    'Full styling control for every element',
    'Automatic fallback replacement on image load',
  ]}
/>

## Installation

Avatar is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/avatar
```

## Usage

```tsx
import { Avatar } from 'tamagui'

export default () => (
  <Avatar circular size="6">
    <Avatar.Image src="http://picsum.photos/200/300" />
    <Avatar.Fallback bc="red" />
  </Avatar>
)
```

## API Reference

### Avatar

Avatar extends [Square](/docs/components/shapes#shape-props), giving it all the [Tamagui standard props](/docs/intro/props) as well as `size` and `circular`.

### Avatar.Fallback

Avatar.Fallback extends [YStack](/docs/components/stacks), plus:

<PropsTable
  data={[
    {
      name: 'delayMs',
      required: false,
      type: 'number',
      description: `Milliseconds to wait before showing the fallback, to prevent flicker.`,
    },
  ]}
/>

### Avatar.Image

Avatar.Image extends [Image](/docs/components/image).


## components/avatar/3.0.0

---
title: Avatar
description: Display images at a fixed size with a fallback while loading
name: avatar
component: Avatar
package: avatar
demoName: Avatar
---

<IntroParagraph>
  Avatar displays an image at a consistent size and swaps in a fallback while
  that image loads.
</IntroParagraph>

<HeroContainer>
  <AvatarDemo />
</HeroContainer>

```tsx hero template=Avatar

```

<Highlights
  features={[
    'Size matching across components',
    'Full styling control for every element',
    'Automatic fallback replacement on image load',
  ]}
/>

## Installation

Avatar is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/avatar
```

## Usage

```tsx
import { Avatar } from 'tamagui'

export default () => (
  <Avatar circular size="lg">
    <Avatar.Image src="http://picsum.photos/200/300" />
    <Avatar.Fallback bg="red" />
  </Avatar>
)
```

## API reference

### Avatar

Avatar extends [Square](/ui/shapes#square), giving it all the [Tamagui standard props](/docs/intro/props) as well as `size` and `circular`.

### Avatar.Fallback

Avatar.Fallback extends [YStack](/ui/stacks), plus:

<PropsTable
  data={[
    {
      name: 'delay',
      required: false,
      type: 'number',
      description: `Milliseconds to wait before showing the fallback, to prevent flicker.`,
    },
  ]}
/>

### Avatar.Image

Avatar.Image extends [Image](/ui/image).


## components/accordion/1.0.0

---
title: Accordion
description: A vertically stacked set of interactive headings with content.
name: accordion
component: Accordion
package: accordion
---

<HeroContainer>
  <AccordionDemo />
</HeroContainer>

```tsx hero template=Accordion

```

<Highlights
  features={[
    'Full keyboard navigation',
    'Single or multiple expanded items',
    'Controlled or uncontrolled state',
  ]}
/>

## Installation

Accordion is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/accordion
```

## Anatomy

Import all parts and piece them together.

```jsx
import { Accordion } from 'tamagui' // or '@tamagui/accordion'

export default () => (
  <Accordion>
    <Accordion.Item>
      <Accordion.Header>
        <Accordion.Trigger />
      </Accordion.Header>
      <Accordion.Content />
    </Accordion.Item>
  </Accordion>
)
```

## API Reference

### Accordion

Contains all the parts of an accordion.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'type',
      required: true,
      type: '"single" | "multiple"',
      typeSimple: 'enum',
      description: (
        <span>
          Determines whether one or multiple items can be opened at the same time.
        </span>
      ),
    },
    {
      name: 'value',
      required: false,
      type: 'string',
      description: (
        <span>
          The controlled value of the item to expand when <Code>type</Code> is{' '}
          <Code>"single"</Code>. Must be used in conjunction with{' '}
          <Code>onValueChange</Code>.
        </span>
      ),
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'string',
      description: (
        <span>
          The value of the item to expand when initially rendered and <Code>type</Code> is{' '}
          <Code>"single"</Code>. Use when you do not need to control the state of the
          items.
        </span>
      ),
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: string) => void',
      typeSimple: 'function',
      description: (
        <span>
          Event handler called when the expanded state of an item changes and{' '}
          <Code>type</Code> is <Code>"single"</Code>.
        </span>
      ),
    },
    {
      name: 'value',
      required: false,
      default: '[]',
      type: 'string[]',
      description: (
        <span>
          The controlled value of the item to expand when <Code>type</Code> is{' '}
          <Code>"multiple"</Code>. Must be used in conjunction with{' '}
          <Code>onValueChange</Code>.
        </span>
      ),
    },
    {
      name: 'defaultValue',
      required: false,
      default: '[]',
      type: 'string[]',
      description: (
        <span>
          The value of the item to expand when initially rendered when <Code>type</Code>{' '}
          is <Code>"multiple"</Code>. Use when you do not need to control the state of the
          items.
        </span>
      ),
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: string[]) => void',
      typeSimple: 'function',
      description: (
        <span>
          Event handler called when the expanded state of an item changes and{' '}
          <Code>type</Code> is <Code>"multiple"</Code>.
        </span>
      ),
    },
    {
      name: 'collapsible',
      required: false,
      default: 'false',
      type: 'boolean',
      description: (
        <span>
          When <Code>type</Code> is <Code>"single"</Code>, allows closing content when
          clicking trigger for an open item.
        </span>
      ),
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      default: 'false',
      description: (
        <span>
          When <Code>true</Code>, prevents the user from interacting with the accordion
          and all its items.
        </span>
      ),
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      typeSimple: 'enum',
      default: '"ltr"',
      description:
        'The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode.',
    },
  ]}
/>

### Item

Contains all the parts of a collapsible section.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      default: 'false',
      description: (
        <span>
          When <Code>true</Code>, prevents the user from interacting with the item.
        </span>
      ),
    },
    {
      name: 'value',
      required: true,
      type: 'string',
      description: 'A unique value for the item.',
    },
  ]}
/>

### Header

Wraps an `Accordion.Trigger`. Use the `asChild` prop to update it to the appropriate heading level for your page.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
  ]}
/>

### Trigger

Toggles the collapsed state of its associated item. It should be nested inside of an `Accordion.Header`.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
  ]}
/>

### Content

Contains the collapsible content for an item.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'forceMount',
      type: 'boolean',
      description: (
        <span>
          Used to force mounting when more control is needed. Useful when controlling
          animation with React animation libraries.
        </span>
      ),
    },
  ]}
/>

## Examples

### Expanded by default

Use the `defaultValue` prop to define the open item by default.

```jsx line=1
<Accordion type="single" __defaultValue__="item-2">
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

### Allow collapsing all items

Use the `collapsible` prop to allow all items to close.

```jsx line=1
<Accordion type="single" __collapsible__>
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

### Multiple items open at the same time

Set the `type` prop to `multiple` to enable opening multiple items at once.

```jsx line=1
<Accordion type="__multiple__">
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

## Accessibility

Adheres to the [Accordion WAI-ARIA design pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#accordion).


## components/accordion/2.0.0

---
title: Accordion
description: A vertically stacked set of interactive headings with content
name: accordion
component: Accordion
package: accordion
demoName: Accordion
---

<IntroParagraph>
  Accordion organizes related sections into keyboard-navigable items that can
  expand one at a time or in groups.
</IntroParagraph>

<HeroContainer>
  <AccordionDemo />
</HeroContainer>

```tsx hero template=Accordion

```

<Highlights
  features={[
    'Full keyboard navigation',
    'Single or multiple expanded items',
    'Controlled or uncontrolled state',
  ]}
/>

## Installation

Accordion is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/accordion
```

## Anatomy

Import all parts and piece them together.

```tsx
import { Accordion } from 'tamagui' // or '@tamagui/accordion'

export default () => (
  <Accordion>
    <Accordion.Item>
      <Accordion.Header>
        <Accordion.Trigger />
      </Accordion.Header>
      <Accordion.Content />
    </Accordion.Item>
  </Accordion>
)
```

## API reference

### Accordion

Contains all the parts of an accordion.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'type',
      required: true,
      type: '"single" | "multiple"',
      typeSimple: 'enum',
      description: (
        <span>
          Determines whether one or multiple items can be opened at the same time.
        </span>
      ),
    },
    {
      name: 'value',
      required: false,
      type: 'string',
      description: (
        <span>
          The controlled value of the item to expand when <Code>type</Code> is{' '}
          <Code>"single"</Code>. Must be used in conjunction with{' '}
          <Code>onValueChange</Code>.
        </span>
      ),
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'string',
      description: (
        <span>
          The value of the item to expand when initially rendered and <Code>type</Code> is{' '}
          <Code>"single"</Code>. Use when you do not need to control the state of the
          items.
        </span>
      ),
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: string) => void',
      typeSimple: 'function',
      description: (
        <span>
          Event handler called when the expanded state of an item changes and{' '}
          <Code>type</Code> is <Code>"single"</Code>.
        </span>
      ),
    },
    {
      name: 'value',
      required: false,
      default: '[]',
      type: 'string[]',
      description: (
        <span>
          The controlled value of the item to expand when <Code>type</Code> is{' '}
          <Code>"multiple"</Code>. Must be used in conjunction with{' '}
          <Code>onValueChange</Code>.
        </span>
      ),
    },
    {
      name: 'defaultValue',
      required: false,
      default: '[]',
      type: 'string[]',
      description: (
        <span>
          The value of the item to expand when initially rendered when <Code>type</Code>{' '}
          is <Code>"multiple"</Code>. Use when you do not need to control the state of the
          items.
        </span>
      ),
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: string[]) => void',
      typeSimple: 'function',
      description: (
        <span>
          Event handler called when the expanded state of an item changes and{' '}
          <Code>type</Code> is <Code>"multiple"</Code>.
        </span>
      ),
    },
    {
      name: 'collapsible',
      required: false,
      default: 'false',
      type: 'boolean',
      description: (
        <span>
          When <Code>type</Code> is <Code>"single"</Code>, allows closing content when
          clicking trigger for an open item.
        </span>
      ),
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      default: 'false',
      description: (
        <span>
          When <Code>true</Code>, prevents the user from interacting with the accordion
          and all its items.
        </span>
      ),
    },
    {
      name: 'orientation',
      required: false,
      type: '"horizontal" | "vertical"',
      typeSimple: 'enum',
      default: '"vertical"',
      description:
        'The layout of the accordion. Determines which arrow keys move between triggers.',
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      typeSimple: 'enum',
      default: '"ltr"',
      description:
        'The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode.',
    },
  ]}
/>

### Accordion.Item

Contains all the parts of a collapsible section.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      default: 'false',
      description: (
        <span>
          When <Code>true</Code>, prevents the user from interacting with the item.
        </span>
      ),
    },
    {
      name: 'value',
      required: true,
      type: 'string',
      description: 'A unique value for the item.',
    },
  ]}
/>

### Accordion.Header

Wraps an `Accordion.Trigger`. Use the `asChild` prop to update it to the appropriate heading level for your page.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
  ]}
/>

### Accordion.Trigger

Toggles the collapsed state of its associated item. It should be nested inside of an `Accordion.Header`.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
  ]}
/>

### Accordion.Content

Contains the collapsible content for an item.

<PropsTable
  data={[
    {
      name: 'asChild',
      required: false,
      type: 'boolean',
      default: 'false',
      description:
        'Change the component to the HTML tag or custom component of the only child. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.',
    },
    {
      name: 'forceMount',
      type: 'boolean',
      description: (
        <span>
          Used to force mounting when more control is needed. Useful when controlling
          animation with React animation libraries.
        </span>
      ),
    },
  ]}
/>

## Examples

### Expanded by default

Use the `defaultValue` prop to define the open item by default.

```tsx line=1
<Accordion type="single" __defaultValue__="item-2">
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

### Allow collapsing all items

Use the `collapsible` prop to allow all items to close.

```tsx line=1
<Accordion type="single" __collapsible__>
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

### Multiple items open at the same time

Set the `type` prop to `multiple` to enable opening multiple items at once.

```tsx line=1
<Accordion type="__multiple__">
  <Accordion.Item value="item-1">…</Accordion.Item>
  <Accordion.Item value="item-2">…</Accordion.Item>
</Accordion>
```

## Accessibility

Adheres to the [Accordion WAI-ARIA design pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#accordion).


## components/menu/2.0.0

---
title: Menu
description: A selectable list in a popover with nested submenus
name: menu
component: Menu
package: menu
demoName: Menu
---

<IntroParagraph>
  Menu presents keyboard-navigable actions, selections, groups, and submenus in
  a popover or platform-native menu.
</IntroParagraph>

<HeroContainer>
  <MenuDemo />
</HeroContainer>

```tsx hero template=Menu

```

<Highlights
  features={[
    'Full keyboard navigation',
    'Submenus, items, icons, images, checkboxes, and groups',
    'Modal and non-modal modes',
    'Platform-native menus on mobile',
  ]}
/>

Menu displays a list of actions or options in a floating panel triggered by a button. It supports nested submenus, keyboard navigation, native platform menus, and [automatically stacks](/ui/z-index) above other content.

## Installation

Menu is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/menu
```

For Expo 57 and React Native 0.86, use the Expo UI adapter:

```bash
npm install @expo/ui
```

Then add the setup import at your app entry point:

```tsx
import '@tamagui/native/setup-expo-ui-menu'
```

The Zeego adapter remains available for apps on compatible React Native versions:

```bash
npm install @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities zeego sf-symbols-typescript
```

```tsx
import '@tamagui/native/setup-zeego'
```

On native, `Menu.Trigger` coordinates with parent Tamagui pressables
automatically. You should not need extra wrapper views or empty `onPress`
handlers just to prevent a parent `press:` clause from activating.

<Notice theme="yellow">
  **Expo Router users:** This import must run _before_ `expo-router/entry`. Create an `index.js` at your project root that imports the setup first, then expo-router, and update your `package.json` main field to `"index.js"`. See the [Expo guide](/docs/guides/expo) for details.
</Notice>

## Anatomy

Import all parts and piece them together.

```tsx
import { Menu } from 'tamagui' // or '@tamagui/menu'

export default () => (
  <Menu>
    <Menu.Trigger asChild>
      <Button />
    </Menu.Trigger>

    <Menu.Portal zIndex={100}>
      <Menu.Content>
        <Menu.Item>
          <Menu.ItemTitle>About Notes</Menu.ItemTitle>
        </Menu.Item>
        <Menu.Item>
          <Menu.ItemTitle>Settings</Menu.ItemTitle>
        </Menu.Item>
        {/* when title is nested inside a React element then you need to use `textValue` */}
        <Menu.Item textValue="Calendar">
          <Menu.ItemTitle>
            <Text>Calendar</Text>
          </Menu.ItemTitle>
          <Menu.ItemIcon>
            <Calendar color="gray" size="1" />
          </Menu.ItemIcon>
        </Menu.Item>
        <Menu.Separator />
        <Menu.Sub>
          <Menu.SubTrigger>
            <Menu.ItemTitle>Actions</Menu.ItemTitle>
          </Menu.SubTrigger>
          <Menu.Portal zIndex={200}>
            <Menu.SubContent>
              <Menu.Label fontSize={'1'}>Note settings</Menu.Label>
              <Menu.Item onSelect={onSelect} key="create-note">
                <Menu.ItemTitle>Create note</Menu.ItemTitle>
              </Menu.Item>
              <Menu.Item onSelect={onSelect} key="delete-all">
                <Menu.ItemTitle>Delete all notes</Menu.ItemTitle>
              </Menu.Item>
              <Menu.Item onSelect={onSelect} key="sync-all">
                <Menu.ItemTitle>Sync notes</Menu.ItemTitle>
              </Menu.Item>
            </Menu.SubContent>
          </Menu.Portal>
        </Menu.Sub>
      </Menu.Content>
    </Menu.Portal>
  </Menu>
)
```

## API reference

### Menu

Contains every component for the Menu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu parts: Trigger, Portal, Content, Items, etc.',
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `Where the menu appears relative to the trigger. Options: 'top' | 'right' | 'bottom' | 'left' with optional '-start' | '-end' alignment.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: 'Controlled open state for the menu.',
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: 'Initial open state when uncontrolled.',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: 'Called when the menu opens or closes.',
    },
    {
      name: 'onOpenWillChange',
      type: '(open: boolean) => void',
      required: false,
      platform: 'ios',
      description: 'Called before the open/close animation begins.',
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description:
        'When true, traps focus inside the menu and blocks outside scroll/interactions.',
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: 'Shifts the menu horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).',
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: 'Flips the menu to the opposite side if there is insufficient space.',
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      default: '10',
      required: false,
      description: 'Distance between the menu and its trigger.',
    },
    {
      name: 'resize',
      type: 'boolean',
      default: 'true',
      required: false,
      description: 'Constrains the menu to fit within available viewport space. When enabled, use Menu.ScrollView inside Content for scrollable overflow.',
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: 'Removes all default Tamagui styles.',
    },
  ]}
/>

### Menu.Portal

Required for rendering the menu content.

<PropsTable
  data={[
    {
      name: 'zIndex',
      required: false,
      type: 'number',
      description: 'Stacking order of the portal layer.',
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Content to render inside the portal.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description:
        'Forces the portal to stay mounted, useful for controlling animations.',
    },
  ]}
/>

### Menu.TriggerGroup

Wrap related menu triggers in `Menu.TriggerGroup` to make a web menubar. Hovering
an enabled sibling switches menus once a menu in that group is open. Hovering
an idle group does not open a menu. Each panel opens at its own trigger.

```tsx
<Menu.TriggerGroup gap="2" aria-label="Application">
  <Menu placement="bottom-start">
    <Menu.Trigger asChild><Button>File</Button></Menu.Trigger>
    <Menu.Portal>
      <Menu.Content>
        <Menu.Item textValue="New"><Menu.ItemTitle>New</Menu.ItemTitle></Menu.Item>
      </Menu.Content>
    </Menu.Portal>
  </Menu>
  <Menu placement="bottom-start">
    <Menu.Trigger asChild><Button>Edit</Button></Menu.Trigger>
    <Menu.Portal>
      <Menu.Content>
        <Menu.Item textValue="Undo"><Menu.ItemTitle>Undo</Menu.ItemTitle></Menu.Item>
      </Menu.Content>
    </Menu.Portal>
  </Menu>
</Menu.TriggerGroup>
```

The container accepts [Tamagui Props](/docs/intro/props) and `dir="ltr" | "rtl"`.
It lays out triggers in a row. Left and right arrow keys move between enabled
triggers and wrap at either end. While a menu is open, they switch to the next
menu and focus its first item. Submenu opening and closing keys keep their
usual behavior. Escape closes the menu and returns focus to its active trigger.

You can also place a trigger group inside one `Menu` whose triggers share a
single content panel. Use trigger `onMouseEnter` and `onFocus` handlers to
prepare the corresponding contents. Groups are independent, and grouped web
menus are non-modal so sibling triggers remain reachable. Native platform
menus keep their platform interactions. `Menu.Group` continues to group items
inside a menu panel.

### Menu.Trigger

Trigger element for the menu. Accepts [Tamagui Props](/docs/intro/props).

<PropsTable
  data={[
    {
      name: 'action',
      required: false,
      type: 'press|longPress',
      default: 'press',
      platform: 'android/ios',
      description:
        "Works with the native prop and accepts 'press' or 'longPress'. The default is 'press' for Menu.",
    },
  ]}
/>

### Menu.Content

Contains the content of the menu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu items, groups, labels, separators, and submenus.',
    },
    {
      name: 'loop',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Whether keyboard navigation wraps from last to first item.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description:
        'Forces the content to stay mounted, useful for controlling animations.',
    },
    {
      name: 'onCloseAutoFocus',
      type: '(event: Event) => void',
      required: false,
      description: 'Called when focus returns to the trigger after closing.',
    },
    {
      name: 'onEscapeKeyDown',
      type: '(event: KeyboardEvent) => void',
      required: false,
      description: 'Called when the escape key is pressed. Can be prevented.',
    },
    {
      name: 'onPointerDownOutside',
      type: '(event: PointerEvent) => void',
      required: false,
      description: 'Called when a pointer event occurs outside the content.',
    },
    {
      name: 'onInteractOutside',
      type: '(event: Event) => void',
      required: false,
      description: 'Called when any interaction occurs outside the content.',
    },
  ]}
/>

### Menu.Item

A selectable menu item that triggers an action when selected.

<PropsTable
  data={[
    {
      name: 'key',
      type: 'string',
      required: true,
      description: 'Unique identifier for the item.',
    },
    {
      name: 'disabled',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Prevents interaction and dims the item.',
    },
    {
      name: 'destructive',
      type: 'boolean',
      required: false,
      platform: 'ios/android',
      description:
        'Renders the item in red on iOS to indicate a dangerous action (e.g. delete). No effect on web.',
    },
    {
      name: 'hidden',
      type: 'boolean',
      required: false,
      description: 'Hides the item from the menu.',
    },
    {
      name: 'onSelect',
      type: '(event?: Event) => void',
      required: false,
      description: 'Called when the item is selected via click or keyboard.',
    },
    {
      name: 'onFocus',
      type: '() => void',
      required: false,
      description: 'Called when the item receives focus.',
    },
    {
      name: 'onBlur',
      type: '() => void',
      required: false,
      description: 'Called when the item loses focus.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description:
        'Text used for typeahead and native menus. Required when ItemTitle contains a React node instead of a string.',
    },
  ]}
/>

### Menu.ItemTitle

Renders the title of the menu item.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string | React.ReactNode',
      required: true,
      description: 'The title text or element to display.',
    },
  ]}
/>
<Notice>
  You can directly pass a text node to the ItemTitle. However, if you use a nested
  React node like `<Text>`, you need to pass `textValue` to the `<Item>` so that it
  works with native menus.
</Notice>

### Menu.ItemIcon

A component to render an icon. For non-native menus, you can pass an icon
component. For native menus, you can pass platform-specific icons to the
`android` and `ios` props.

On iOS, it renders the native
[SF Symbols](https://github.com/andrewtavis/sf-symbols-online) icons.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: false,
      description: 'Fallback icon for web when native icons are not available.',
    },
    {
      name: 'ios',
      type: 'object',
      required: false,
      platform: 'ios',
      description:
        'SF Symbol configuration: name, weight, scale, hierarchicalColor, paletteColors.',
    },
    {
      name: 'android',
      type: 'object',
      required: false,
      platform: 'android',
      description: 'Android resource drawable name.',
    },
  ]}
/>

```tsx line=1
<Menu.ItemIcon
  ios={{
    name: '0.circle.fill', // required
    pointSize: 5,
    weight: 'semibold',
    scale: 'medium',
    // can also be a color string. Requires iOS 15+
    hierarchicalColor: {
      dark: 'blue',
      light: 'green',
    },
    // alternative to hierarchical color. Requires iOS 15+
    paletteColors: [
      {
        dark: 'blue',
        light: 'green',
      },
    ],
  }}
>
  <CircleIcon />
</Menu.ItemIcon>
```

### Menu.ItemImage

A component to render an item image. For native menus, it only works on iOS. It
takes the same props as `@tamagui/image`.

### Menu.ItemSubtitle

A component to render a subtitle for the menu item. For native menus, it only
works on iOS.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string',
      required: true,
      description: 'The subtitle text to display below the title.',
    },
  ]}
/>

### Menu.Group

A component that groups multiple menu items together.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu items to group together.',
    },
  ]}
/>

### Menu.CheckboxItem

A menu item with a checkbox that can be toggled on and off.

<PropsTable
  data={[
    {
      name: 'key',
      type: 'string',
      required: true,
      description: 'Unique identifier for the checkbox item.',
    },
    {
      name: 'disabled',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Prevents interaction and dims the item.',
    },
    {
      name: 'destructive',
      type: 'boolean',
      required: false,
      platform: 'ios/android',
      description:
        'Renders the item in red on iOS to indicate a dangerous action. No effect on web.',
    },
    {
      name: 'hidden',
      type: 'boolean',
      required: false,
      description: 'Hides the item from the menu.',
    },
    {
      name: 'onFocus',
      type: '() => void',
      required: false,
      description: 'Called when the item receives focus.',
    },
    {
      name: 'onBlur',
      type: '() => void',
      required: false,
      description: 'Called when the item loses focus.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description:
        'Text for native menus. Required when ItemTitle contains a React node.',
    },
    {
      name: 'value',
      type: "'on' | 'off' | 'mixed'",
      required: false,
      platform: 'ios/android',
      description: 'Controlled checked state for native menus.',
    },
    {
      name: 'onValueChange',
      type: '(state, prevState) => void',
      required: false,
      platform: 'ios/android',
      description: 'Called when checked state changes on native menus.',
    },
    {
      name: 'checked',
      type: 'boolean',
      required: false,
      description: 'Controlled checked state for web menus.',
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
      required: false,
      description: 'Called when checked state changes on web.',
    },
  ]}
/>

### Menu.RadioGroup

Groups a set of `Menu.RadioItem` and manages the selected value. Works on web
and native. On native, the group is rendered as a native menu group and each
`RadioItem` is mapped onto the OS checkmark state so exactly one item shows as
selected at a time.

```tsx
const [color, setColor] = React.useState('blue')

<Menu.RadioGroup value={color} onValueChange={setColor}>
  <Menu.RadioItem key="red" value="red">
    <Menu.ItemIndicator>
      <Check size={16} />
    </Menu.ItemIndicator>
    <Menu.ItemTitle>Red</Menu.ItemTitle>
  </Menu.RadioItem>
  <Menu.RadioItem key="blue" value="blue">
    <Menu.ItemIndicator>
      <Check size={16} />
    </Menu.ItemIndicator>
    <Menu.ItemTitle>Blue</Menu.ItemTitle>
  </Menu.RadioItem>
</Menu.RadioGroup>
```

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'One or more Menu.RadioItem components.',
    },
    {
      name: 'value',
      type: 'string',
      required: false,
      description: 'The controlled value of the currently selected item.',
    },
    {
      name: 'onValueChange',
      type: '(value: string) => void',
      required: false,
      description: 'Called when the selected value changes.',
    },
  ]}
/>

### Menu.RadioItem

An item that can be selected inside a `Menu.RadioGroup`. Render a
`Menu.ItemIndicator` inside to show a checkmark for the active value on web;
on native the OS draws its own checkmark and the `ItemIndicator` child is
dropped automatically.

<PropsTable
  data={[
    {
      name: 'key',
      type: 'string',
      required: true,
      description: 'Unique identifier for the radio item.',
    },
    {
      name: 'value',
      type: 'string',
      required: true,
      description:
        'The value of this item. When it matches the parent RadioGroup value, the item is selected.',
    },
    {
      name: 'disabled',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Prevents interaction and dims the item.',
    },
    {
      name: 'hidden',
      type: 'boolean',
      required: false,
      description: 'Hides the item from the menu.',
    },
    {
      name: 'onFocus',
      type: '() => void',
      required: false,
      description: 'Called when the item receives focus.',
    },
    {
      name: 'onBlur',
      type: '() => void',
      required: false,
      description: 'Called when the item loses focus.',
    },
  ]}
/>

### Menu.ItemIndicator

Use inside `Menu.CheckboxItem` or `Menu.RadioItem` to indicate when an item is checked.
This allows you to conditionally render a checkmark.

```tsx line=1
<Menu.ItemIndicator>
  <CheckmarkIcon /> {/* This does not work with the native prop. */}
</Menu.ItemIndicator>
```

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: false,
      description: 'Custom checkmark icon. Only works on web.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description: 'Forces the indicator to stay mounted for animation control.',
    },
  ]}
/>

### Menu.Label

Renders a non-focusable label for a group of items. On native menus, only one
label is supported per menu and submenu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string',
      required: true,
      description: 'The label text.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description: 'Text for native menus when children is a React node.',
    },
  ]}
/>

### Menu.Arrow

Renders an arrow pointing to the trigger.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'number | SizeToken',
      required: false,
      description: 'Width and height of the arrow.',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      required: false,
      description: 'Removes default arrow styles.',
    },
  ]}
/>

### Menu.Separator

Renders a visual divider between menu items. Web only.

### Menu.Sub

A container for nested submenu components.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'SubTrigger, Portal, and SubContent components.',
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: 'Controlled open state for the submenu.',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: 'Called when the submenu opens or closes.',
    },
  ]}
/>

### Menu.SubContent

Renders the content of a submenu. Same props as `Menu.Content`.

### Menu.SubTrigger

A menu item that opens a submenu on hover or focus. Accepts the same props as
`Menu.Item`.

### Menu.ScrollView

A scrollable container for menu items. Use this inside `Menu.Content` when you have many items that may overflow. The menu automatically constrains to available viewport space (via `resize` prop), and ScrollView handles the overflow. Scrollbars are hidden by default.

```tsx
<Menu.Content>
  <Menu.ScrollView>
    {/* Many menu items */}
  </Menu.ScrollView>
</Menu.Content>
```

## Styling

### Item highlight behavior

Menu items use the `focus` condition for highlighting. Write it as a typed
object key or a `focus:` string clause. Focusing the highlighted item keeps
mouse and keyboard navigation in sync, with only one item highlighted at a time.

When you hover over an item, it receives focus, which activates the `focus:` clause. When you use arrow keys to navigate, focus moves to the new item, removing the highlight from the previous one.

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
// default highlight follows focus
<Menu.Item>
  <Menu.ItemTitle>Settings</Menu.ItemTitle>
</Menu.Item>

// customize the focus highlight
<Menu.Item backgroundColor={{ focus: 'blue-5' }}>
  <Menu.ItemTitle>Custom Highlight</Menu.ItemTitle>
</Menu.Item>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
// default highlight follows focus
<Menu.Item>
  <Menu.ItemTitle>Settings</Menu.ItemTitle>
</Menu.Item>

// customize the focus highlight
<Menu.Item backgroundColor="focus:blue-5">
  <Menu.ItemTitle>Custom Highlight</Menu.ItemTitle>
</Menu.Item>
```

</MDXTabs.Content>
</MDXTabs>

<Notice>
  Avoid using a `hover:` background clause on Menu.Item. This can cause "double
  highlighting" when switching between mouse and keyboard, where both the hovered item
  and the focused item appear highlighted simultaneously.
</Notice>


## components/inputs/1.0.0

---
title: Input & Textarea
name: inputs
description: Flexible form fields in styled and unstyled forms.
component: Input
demoName: Inputs
---

<HeroContainer demoMultiple>
  <InputsDemo />
</HeroContainer>

```tsx hero template=Inputs

```

Using the same base component TextInput, from [React Native](https://reactnative.dev/docs/textinput) or [React Native Web](https://necolas.github.io/react-native-web/docs/text-input/), Tamagui simply wraps these components to allow the full set of style props, as well as scaling all the styles up or down using the `size` property, much like Button.

## Installation

Input is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/input
```

## Input

A one-line input field:

```tsx
import { Input } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <Input size="4" borderWidth={2} />
)
```

## TextArea

For multi-line inputs:

```tsx
import { TextArea } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <TextArea size="4" borderWidth={2} />
)
```


## components/inputs/2.0.0

---
title: Input & TextArea
name: inputs
description: Flexible form fields in styled and unstyled forms
component: Input
package: input
demoName: Inputs
---

<IntroParagraph>
  Input and TextArea add Tamagui styling and shared sizing to the React Native
  text input API.
</IntroParagraph>

<HeroContainer demoMultiple>
  <InputsDemo />
</HeroContainer>

```tsx hero template=Inputs

```

Input and TextArea wrap React Native's `TextInput`, from [React Native](https://reactnative.dev/docs/textinput) or [React Native Web](https://necolas.github.io/react-native-web/docs/text-input/). That gives them the full set of style props and scales their styles up or down with the `size` prop, much like Button.

## Installation

Input is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/input
```

## Input

A one-line input field:

```tsx
import { Input } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <Input size="md" borderWidth={2} />
)
```

## TextArea

For multiline inputs:

```tsx
import { TextArea } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <TextArea size="md" borderWidth={2} />
)
```


## components/scroll-view/1.0.0

---
title: ScrollView
description: React Native ScrollView with Tamagui props.
name: scrollView
component: ScrollView
package: scroll-view
demoName: ScrollView
---

<HeroContainer>
  <ScrollViewDemo />
</HeroContainer>

```tsx hero template=ScrollView

```

<Highlights
  features={[
    `Full React Native ScrollView API`,
    `Full Tamagui style props`,
  ]}
/>

## Installation

ScrollView is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/scroll-view
```

## Usage

```tsx
import { ScrollView, YStack, ListItem } from 'tamagui'

export default () => (
  <ScrollView>
    <YStack>
      <ListItem>1</ListItem>
      <ListItem>2</ListItem>
      <ListItem>3</ListItem>
      <ListItem>4</ListItem>
    </YStack>
  </ScrollView>
)
```

## API Reference

### ScrollView

See [React Native ScrollView](https://reactnative.dev/docs/scrollview) and [Tamagui style props](https://tamagui.dev/docs/intro/props).


## components/scroll-view/2.0.0

---
title: ScrollView
description: React Native ScrollView with Tamagui props
name: scrollView
component: ScrollView
package: scroll-view
demoName: ScrollView
---

<HeroContainer>
  <ScrollViewDemo />
</HeroContainer>

```tsx hero template=ScrollView

```

<Highlights
  features={[
    `Full React Native ScrollView API`,
    `Full Tamagui style props`,
  ]}
/>

## Installation

ScrollView is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/scroll-view
```

## Usage

```tsx
import { ScrollView, YStack, ListItem } from 'tamagui'

export default () => (
  <ScrollView>
    <YStack>
      <ListItem>1</ListItem>
      <ListItem>2</ListItem>
      <ListItem>3</ListItem>
      <ListItem>4</ListItem>
    </YStack>
  </ScrollView>
)
```

## API Reference

### ScrollView

See [React Native ScrollView](https://reactnative.dev/docs/scrollview) and [Tamagui style props](https://tamagui.dev/docs/intro/props).


## components/scroll-view/3.0.0

---
title: ScrollView
description: Cross-platform ScrollView with Tamagui props
name: scrollView
component: ScrollView
package: scroll-view
demoName: ScrollView
---

<IntroParagraph>
  ScrollView brings the React Native scrolling API and Tamagui style props to
  native and web without a react-native-web dependency.
</IntroParagraph>

<HeroContainer>
  <ScrollViewDemo />
</HeroContainer>

```tsx hero template=ScrollView

```

<Highlights
  features={[
    `React Native ScrollView API`,
    `Web implementation with no react-native-web`,
    `Full Tamagui style props`,
  ]}
/>

In v3, `@tamagui/scroll-view` ships its own web implementation instead of
wrapping `react-native-web`. It supports the ScrollView surface Tamagui uses most:
`scrollTo`, `scrollToEnd`, `getScrollableNode`, React Native-shaped `onScroll`,
`contentContainerStyle`, `horizontal`, and scroll indicator props.

Props outside that mapped surface, such as momentum events, `snapTo*`, and
`keyboardDismissMode`, are not supported on web through the lite implementation.

## Installation

ScrollView is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/scroll-view
```

## Usage

```tsx
import { ListItem, ScrollView, YStack, style } from 'tamagui'

const contentContainer = style({
  padding: 16,
  gap: 8,
})

export default () => (
  <ScrollView contentContainerStyle={contentContainer}>
    <YStack>
      <ListItem>1</ListItem>
      <ListItem>2</ListItem>
      <ListItem>3</ListItem>
      <ListItem>4</ListItem>
    </YStack>
  </ScrollView>
)
```

## API reference

### ScrollView

`ScrollView` accepts Tamagui standard props and the mapped React Native ScrollView surface.

<PropsTable
  data={[
    {
      name: 'contentContainerStyle',
      type: 'StylePiece',
      description: `Styles applied to the inner scroll container. Accepts a style() piece.`,
    },
    {
      name: 'horizontal',
      type: 'boolean',
      description: `When true, scrolls horizontally instead of vertically.`,
    },
    {
      name: 'showsHorizontalScrollIndicator',
      type: 'boolean',
      description: `Whether to show the horizontal scroll indicator.`,
    },
    {
      name: 'showsVerticalScrollIndicator',
      type: 'boolean',
      description: `Whether to show the vertical scroll indicator.`,
    },
  ]}
/>

See [React Native ScrollView](https://reactnative.dev/docs/scrollview) and [Tamagui style props](/docs/intro/props). On web, prefer the mapped props documented above.


## components/portal/1.0.0

---
title: Portal
description: Send items to other areas of the tree.
name: portal
component: Portal
package: portal
---

Portal is included in `tamagui` as it's used by a few components. For now, it's simply using [@gorhom/portal](https://github.com/gorhom/react-native-portal).


## components/portal/2.0.0

---
title: Portal
description: Send items to other areas of the tree
name: portal
component: Portal
package: portal
---

<IntroParagraph>
  Portal sends content to another part of the rendered tree while preserving
  Tamagui theme and configuration context.
</IntroParagraph>

Portal is included in `tamagui` and is used by [Sheet](/ui/sheet),
[Dialog](/ui/dialog), [Popover](/ui/popover),
[Select](/ui/select), and [Toast](/ui/toast). See
[Stacking (zIndex)](/ui/z-index) for how overlay layering works.

## PortalProvider

`TamaguiProvider` from `tamagui` already wraps your app in a `PortalProvider`
with a root `PortalHost`, so most apps need no setup. Add one yourself only when
you render the bare `TamaguiProvider` from `@tamagui/core`:

```tsx
import { TamaguiProvider } from '@tamagui/core'
import { PortalProvider } from '@tamagui/portal'

export function App() {
  return (
    <TamaguiProvider config={config}>
      <PortalProvider shouldAddRootHost>{/* your app */}</PortalProvider>
    </TamaguiProvider>
  )
}
```

Render only one `PortalProvider` with a root host. Nesting a second one under
`TamaguiProvider` from `tamagui` mounts two root hosts and causes hydration
mismatches; pass `shouldAddRootHost={false}` if you need the nested provider.

## Native portal setup (recommended)

On web, React's built-in `createPortal` preserves context automatically. On
native, the default portal implementation doesn't preserve React context.
Tamagui automatically re-propagates its own contexts (theme, configuration), but
your custom contexts like navigation or app state won't be available inside
portaled content. The re-propagation also adds some overhead.

We recommend using
[react-native-teleport](https://github.com/kirillzyusko/react-native-teleport)
to solve this. It uses React Native's native portal API to preserve context
automatically.

### Step 1: install react-native-teleport

```bash
npm install react-native-teleport
```

### Step 2: import the setup module

In your app's entry file (index.js or App.tsx), before any Tamagui imports:

```tsx
import '@tamagui/native/setup-teleport'
```

That's it! All portal-using components will now preserve context automatically
on native. Without native portals, your custom context from parent components
won't be available inside portaled content:

```tsx
const MyContext = createContext('default')

function App() {
  return (
    <MyContext.Provider value="from-provider">
      <Sheet modal open>
        <Sheet.Container>
          <Sheet.Background />
          {/* Without native portal: you'd not have context here on native */}
          <MyConsumer />
        </Sheet.Container>
      </Sheet>
    </MyContext.Provider>
  )
}
```

## Alternative approaches

If you can't use react-native-teleport, there are other ways to handle context
in portals:

### Component scoping

For Dialog, Popover, and Tooltip, use the `scope` prop to mount a single
instance at your app root. This avoids portals entirely on native:

```tsx
// _layout.tsx - mount once at root with all your providers
<TamaguiProvider>
  <Tooltip scope="global">
    <Tooltip.Content>
      <Tooltip.Arrow />
      <Paragraph>{/* label set by trigger */}</Paragraph>
    </Tooltip.Content>

    {/* rest of your app */}
    <Slot />
  </Tooltip>
</TamaguiProvider>

// anywhere in your app - just the trigger
<Tooltip.Trigger scope="global" aria-label="Settings">
  <Button icon={Settings} />
</Tooltip.Trigger>
```

This pattern is also a performance win for lists or tables with many interactive
elements.

### Manual context re-propagation

Wrap portal children with the necessary providers:

```tsx
const theme = useTheme()
const myValue = useContext(MyContext)

<Sheet>
  <Sheet.Container>
    <Sheet.Background />
    <ThemeProvider theme={theme}>
      <MyContext.Provider value={myValue}>
        {/* content that needs context */}
      </MyContext.Provider>
    </ThemeProvider>
  </Sheet.Container>
</Sheet>
```

This is more verbose and error-prone as you need to remember to re-propagate
every context you use.

## API reference

### Portal

<PropsTable
  data={[
    {
      name: 'zIndex',
      type: 'number',
      description: `Fixed z-index value for the portal.`,
    },
    {
      name: 'stackZIndex',
      type: `boolean | number | 'global'`,
      description: (
        <span>
          Enable automatic z-index stacking. Tamagui intelligently stacks z-index both
          horizontally (based on mount order) and vertically (nested content is always
          above parent but below sibling content that comes after). <code>true</code>{' '}
          enables stacking, a number adds to the stacked value, <code>'global'</code> only
          stacks horizontally without nesting logic.
        </span>
      ),
    },
    {
      name: 'passThrough',
      type: 'boolean',
      description: `When true, renders children directly without portal behavior.`,
    },
  ]}
/>

This automatic stacking is already enabled by default in Dialog, Popover, Sheet, and other overlay
components. If you open a Popover from within a Dialog, the Popover will automatically have a
higher z-index than the Dialog without any configuration needed.

### PortalProvider

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      default: 'true',
      description: `Mounts a PortalHost at the end of the provider for portals to render into.`,
    },
    {
      name: 'rootHostName',
      type: 'string',
      default: `'root'`,
      description: `Name of the root PortalHost.`,
    },
  ]}
/>

## Technical details

[react-native-teleport](https://github.com/kirillzyusko/react-native-teleport)
uses `ReactNativeFabricUIManager.createPortal` (Fabric) or
`UIManager.createPortal` (Paper) to create true native portals that preserve the
React fiber tree.

The default portal implementation, by contrast, uses a JS-based approach with
context providers and a reducer to manage portal state. While compatible with
older RN versions, it breaks React context because it re-renders content in a
separate provider tree.

Tamagui includes a `needsPortalRepropagation()` helper that returns `true` when
using the default portal implementation and `false` when using native portals,
so library authors can conditionally re-propagate context only when needed.


## components/slider/1.0.0

---
title: Slider
description: A simple slider component
name: slider
component: Slider
package: slider
demoName: Slider
---

# Slider

<Description>Drag to set values, vertically or horizontally</Description>

<HeroContainer>
  <SliderDemo />
</HeroContainer>

```tsx hero template=Slider

```

<Highlights
  features={[
    `Sizing and theming with controlled or uncontrolled state`,
    `Multiple thumb support`,
    `Configurable steps and keyboard controls`,
    `Accessible, composable, and customizable`,
  ]}
/>

## Installation

Slider is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/slider
```

## Usage

Slider comes as multiple components that ship with default styles and are sizable. The `size` prop on `<Slider />` will automatically pass size down to all the sub-components.

```tsx
import { Slider } from 'tamagui'

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <Slider.Track>
      <Slider.TrackActive />
    </Slider.Track>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

You can also optionally style any component, either using inline style props or by wrapping with `styled`:

```tsx
import { Slider, styled } from 'tamagui'

const CustomSliderTrack = styled(Slider.Track, {
  backgroundColor: 'red',
})

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <CustomSliderTrack>
      <Slider.TrackActive />
    </CustomSliderTrack>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

## API Reference

### Slider

Contains every component for the slider.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens',
      description: `Control size of every component.`,
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: `For usage with forms.`,
    },
    {
      name: 'value',
      required: false,
      type: 'number[]',
      description: `Controlled value.`,
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'number[]',
      description: `Uncontrolled starting value.`,
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: number[]): void',
      description: ``,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Disable interaction.`,
    },
    {
      name: 'orientation',
      required: false,
      type: `"horizontal" | "vertical"`,
      default: 'horizontal',
      description: `Direction of the slider.`,
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      description: `Controls the side the active track appears on.`,
    },
    {
      name: 'min',
      required: false,
      type: 'number',
      description: `Minimum value.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value.`,
    },
    {
      name: 'step',
      required: false,
      type: 'number',
      description: `Minimum thumb move distance.`,
    },
    {
      name: 'minStepsBetweenThumbs',
      required: false,
      type: 'number',
      description: `Minimum steps between thumbs.`,
    },
  ]}
/>

### Slider.Track

`Slider.Track` Inherits `SizableStack`, extending all the default [props](/docs/intro/props).

### Slider.TrackActive

`Slider.Track` Inherits `View`, extending all the default [props](/docs/intro/props).

### Slider.Thumb

`Slider.Track` Inherits `SizableStack`, extending all the default [props](/docs/intro/props), adding:

<PropsTable
  data={[
    {
      name: 'index',
      required: true,
      type: 'number',
      description: `Corresponds to the index of \`value\` or \`defaultValue\`. Use to correlate thumbs to each value in the array.`,
    },
  ]}
/>


## components/slider/1.45.0

---
title: Slider
description: Drag to set values, vertically or horizontally.
name: slider
component: Slider
package: slider
demoName: Slider
---

<HeroContainer>
  <SliderDemo />
</HeroContainer>

```tsx hero template=Slider

```

<Highlights
  features={[
    `Sizing and theming with controlled or uncontrolled state`,
    `Multiple thumb support`,
    `Configurable steps and keyboard controls`,
    `Accessible, composable, and customizable`,
  ]}
/>

## Installation

Slider is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/slider
```

## Usage

Slider comes as multiple components that ship with default styles and are sizable. The `size` prop on `<Slider />` will automatically pass size down to all the sub-components.

```tsx
import { Slider } from 'tamagui'

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <Slider.Track>
      <Slider.TrackActive />
    </Slider.Track>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

You can also optionally style any component, either using inline style props or by wrapping with `styled`:

```tsx
import { Slider, styled } from 'tamagui'

const CustomSliderTrack = styled(Slider.Track, {
  backgroundColor: 'red',
})

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <CustomSliderTrack>
      <Slider.TrackActive />
    </CustomSliderTrack>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

## API Reference

### Slider

Contains every component for the slider.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens',
      description: `Control size of every component.`,
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: `For usage with forms.`,
    },
    {
      name: 'value',
      required: false,
      type: 'number[]',
      description: `Controlled value.`,
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'number[]',
      description: `Uncontrolled starting value.`,
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: number[]): void',
      description: ``,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Disable interaction.`,
    },
    {
      name: 'orientation',
      required: false,
      type: `"horizontal" | "vertical"`,
      default: 'horizontal',
      description: `Direction of the slider.`,
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      description: `Controls the side the active track appears on.`,
    },
    {
      name: 'min',
      required: false,
      type: 'number',
      description: `Minimum value.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value.`,
    },
    {
      name: 'step',
      required: false,
      type: 'number',
      description: `Minimum thumb move distance.`,
    },
    {
      name: 'minStepsBetweenThumbs',
      required: false,
      type: 'number',
      description: `Minimum steps between thumbs.`,
    },
    {
      name: 'onSlideStart',
      required: false,
      type: `(event: GestureReponderEvent, value: number, target: 'thumb' | 'track') => void`,
      description: `Called on slide start.`,
    },
    {
      name: 'onSlideMove',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide move.`,
    },
    {
      name: 'onSlideEnd',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide end.`,
    },
  ]}
/>

### Slider.Track

`Slider.Track` Inherits `SizableStack`, extending all the default [props](/docs/intro/props).

### Slider.TrackActive

`Slider.TrackActive` Inherits `View`, extending all the default [props](/docs/intro/props).

### Slider.Thumb

`Slider.Thumb` Inherits `SizableStack`, extending all the default [props](/docs/intro/props), adding:

<PropsTable
  data={[
    {
      name: 'index',
      required: true,
      type: 'number',
      description: `Corresponds to the index of \`value\` or \`defaultValue\`. Use to correlate thumbs to each value in the array.`,
    },
  ]}
/>


## components/slider/2.0.0

---
title: Slider
description: Drag to set values, vertically or horizontally
name: slider
component: Slider
package: slider
demoName: Slider
---

<HeroContainer>
  <SliderDemo />
</HeroContainer>

```tsx hero template=Slider

```

<Highlights
  features={[
    `Sizing and theming with controlled or uncontrolled state`,
    `Multiple thumb support`,
    `Configurable steps and keyboard controls`,
    `Accessible, composable, and customizable`,
  ]}
/>

## Installation

Slider is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/slider
```

## Usage

Slider comes as multiple components that ship with default styles and are sizable. The `size` prop on `<Slider />` will automatically pass size down to all the sub-components.

```tsx
import { Slider } from 'tamagui'

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <Slider.Track>
      <Slider.TrackActive />
    </Slider.Track>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

You can also optionally style any component, either using inline style props or by wrapping with `styled`:

```tsx
import { Slider, styled } from 'tamagui'

const CustomSliderTrack = styled(Slider.Track, {
  backgroundColor: 'red',
})

export default () => (
  <Slider size="4" width={200} defaultValue={[50]} max={100} step={1}>
    <CustomSliderTrack>
      <Slider.TrackActive />
    </CustomSliderTrack>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

## Vertical Slider on iOS

When using a vertical slider on iOS, you need to pass safe area insets to `TamaguiProvider` for proper pointer position calculation. Without this, the slider thumb may not track your finger correctly due to iOS safe area offsets.

```tsx
import { TamaguiProvider } from 'tamagui'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import { config } from './tamagui.config'

function App() {
  const insets = useSafeAreaInsets()

  return (
    <TamaguiProvider config={config} insets={insets}>
      {/* Your app content */}
    </TamaguiProvider>
  )
}
```

Then you can use vertical sliders normally:

```tsx
import { Slider, XStack } from 'tamagui'

export default () => (
  <XStack height={200} alignItems="center" gap="8">
    <Slider height={200} orientation="vertical" defaultValue={[50]} max={100} step={1}>
      <Slider.Track>
        <Slider.TrackActive />
      </Slider.Track>
      <Slider.Thumb size="2" index={0} circular />
    </Slider>
  </XStack>
)
```

<Notice theme="blue">
  This is only required on iOS. On Android and web, the slider works correctly without
  passing insets.
</Notice>

## API Reference

### Slider

Contains every component for the slider.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens',
      description: `Controls the size of every component.`,
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: `For usage with forms.`,
    },
    {
      name: 'value',
      required: false,
      type: 'number[]',
      description: `Controlled value.`,
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'number[]',
      description: `Uncontrolled starting value.`,
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: number[]): void',
      description: `Callback called when the value changes.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Disables interaction.`,
    },
    {
      name: 'orientation',
      required: false,
      type: `"horizontal" | "vertical"`,
      default: 'horizontal',
      description: `Direction of the slider.`,
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      description: `Controls the side the active track appears on.`,
    },
    {
      name: 'min',
      required: false,
      type: 'number',
      description: `Minimum value.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value.`,
    },
    {
      name: 'step',
      required: false,
      type: 'number',
      description: `Minimum thumb move distance.`,
    },
    {
      name: 'minStepsBetweenThumbs',
      required: false,
      type: 'number',
      description: `Minimum steps between thumbs.`,
    },
    {
      name: 'onSlideStart',
      required: false,
      type: `(event: GestureReponderEvent, value: number, target: 'thumb' | 'track') => void`,
      description: `Called on slide start.`,
    },
    {
      name: 'onSlideMove',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide move.`,
    },
    {
      name: 'onSlideEnd',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide end.`,
    },
  ]}
/>

### Slider.Track

Slider.Track inherits `SizableStack`, extending all the default [props](/docs/intro/props).

### Slider.TrackActive

Slider.TrackActive inherits `View`, extending all the default [props](/docs/intro/props).

### Slider.Thumb

Slider.Thumb inherits `SizableStack`, extending all the default [props](/docs/intro/props), adding:

<PropsTable
  data={[
    {
      name: 'index',
      required: true,
      type: 'number',
      description: `Corresponds to the index of \`value\` or \`defaultValue\`. Use to correlate thumbs to each value in the array.`,
    },
  ]}
/>


## components/slider/3.0.0

---
title: Slider
description: Drag to set values, vertically or horizontally
name: slider
component: Slider
package: slider
demoName: Slider
---

<IntroParagraph>
  Slider lets users set one or more values with pointer, touch, or keyboard
  input in horizontal and vertical layouts.
</IntroParagraph>

<HeroContainer>
  <SliderDemo />
</HeroContainer>

```tsx hero template=Slider

```

<Highlights
  features={[
    `Sizing and theming with controlled or uncontrolled state`,
    `Multiple thumb support`,
    `Configurable steps and keyboard controls`,
    `Accessible, composable, and customizable`,
  ]}
/>

## Installation

Slider is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/slider
```

## Usage

Slider comes as multiple components that ship with default styles and are sizable. The `size` prop on `<Slider />` will automatically pass size down to all the sub-components.

```tsx
import { Slider } from 'tamagui'

export default () => (
  <Slider size="md" width={200} defaultValue={[50]} max={100} step={1}>
    <Slider.Track>
      <Slider.TrackActive />
    </Slider.Track>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

You can also optionally style any component, either using inline style props or by wrapping with `styled`:

```tsx
import { Slider, styled } from 'tamagui'

const CustomSliderTrack = styled(Slider.Track, {
  backgroundColor: 'red',
})

export default () => (
  <Slider size="md" width={200} defaultValue={[50]} max={100} step={1}>
    <CustomSliderTrack>
      <Slider.TrackActive />
    </CustomSliderTrack>
    <Slider.Thumb circular index={0} />
  </Slider>
)
```

## Vertical slider on iOS

When using a vertical slider on iOS, you need to pass safe area insets to `TamaguiProvider` for proper pointer position calculation. Without this, the slider thumb may not track your finger correctly due to iOS safe area offsets.

```tsx
import { TamaguiProvider } from 'tamagui'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import { config } from './tamagui.config'

function App() {
  const insets = useSafeAreaInsets()

  return (
    <TamaguiProvider config={config} insets={insets}>
      {/* Your app content */}
    </TamaguiProvider>
  )
}
```

Then you can use vertical sliders normally:

```tsx
import { Slider, XStack } from 'tamagui'

export default () => (
  <XStack height={200} alignItems="center" gap="8">
    <Slider height={200} orientation="vertical" defaultValue={[50]} max={100} step={1}>
      <Slider.Track>
        <Slider.TrackActive />
      </Slider.Track>
      <Slider.Thumb size="sm" index={0} circular />
    </Slider>
  </XStack>
)
```

<Notice theme="blue">
  This is only required on iOS. On Android and web, the slider works correctly without
  passing insets.
</Notice>

## API reference

### Slider

Contains every component for the slider.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `Controls the size of every component.`,
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: `For usage with forms. On web, renders one hidden input per thumb under this name, so multi-thumb values submit as repeated entries readable via FormData.getAll(name).`,
    },
    {
      name: 'value',
      required: false,
      type: 'number[]',
      description: `Controlled value.`,
    },
    {
      name: 'defaultValue',
      required: false,
      type: 'number[]',
      description: `Uncontrolled starting value.`,
    },
    {
      name: 'onValueChange',
      required: false,
      type: '(value: number[]): void',
      description: `Callback called when the value changes.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Disables interaction.`,
    },
    {
      name: 'orientation',
      required: false,
      type: `"horizontal" | "vertical"`,
      default: 'horizontal',
      description: `Direction of the slider.`,
    },
    {
      name: 'dir',
      required: false,
      type: '"ltr" | "rtl"',
      description: `Controls the side the active track appears on.`,
    },
    {
      name: 'min',
      required: false,
      type: 'number',
      description: `Minimum value.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value.`,
    },
    {
      name: 'step',
      required: false,
      type: 'number',
      description: `Minimum thumb move distance.`,
    },
    {
      name: 'minStepsBetweenThumbs',
      required: false,
      type: 'number',
      description: `Minimum steps between thumbs.`,
    },
    {
      name: 'onSlideStart',
      required: false,
      type: `(event: GestureReponderEvent, value: number, target: 'thumb' | 'track') => void`,
      description: `Called on slide start.`,
    },
    {
      name: 'onSlideMove',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide move.`,
    },
    {
      name: 'onSlideEnd',
      required: false,
      type: `(event: GestureReponderEvent, value: number) => void`,
      description: `Called on slide end.`,
    },
  ]}
/>

### Slider.Track

Slider.Track inherits `YStack`, extending all the default [props](/docs/intro/props).

### Slider.TrackActive

Slider.TrackActive inherits `View`, extending all the default [props](/docs/intro/props).

### Slider.Thumb

Slider.Thumb inherits `YStack`, extending all the default [props](/docs/intro/props), adding:

<PropsTable
  data={[
    {
      name: 'index',
      required: true,
      type: 'number',
      description: `Corresponds to the index of \`value\` or \`defaultValue\`. Use to correlate thumbs to each value in the array.`,
    },
  ]}
/>


## components/group/1.7.0

---
title: Group
description: Render horizontal or vertical groups easily.
name: group
component: Group
demoName: Group
---

# Group

<Description>Layout buttons and more with groups.</Description>

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'One size prop for all styles',
    'Vertical or horizontal alignment',
    'Built-in spacing and disabled props',
    'Optional Item wrapper for finer control',
  ]}
/>

## Usage

You can use `Group` by itself with the `axis` property determining the direction it assumes.

By default, Groups will control the border radius of their children automatically - the first and last children will get their start/end radius set to match group radius. If it's a `YGroup`, it will adjust top/bottom radius. `XGroup` adjusts the left/right radius.

You can use Groups with or without `Group.Item`, depending on if you want to spacing and separators to be handled based on direct children, or on each Item rendered.

```tsx
import { Button, XGroup } from 'tamagui'

// usage with Item:
export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

For a simpler use case and backwards compat, you can also use it without `Group.Item`, which will just apply borders and spacing based on direct children. Note that Group will detect if any `Group.Item` is inside it, and automatically switch modes. If no Item, it spaces direct children:

```tsx
import { Button, XGroup } from 'tamagui'

// usage without Item:
export default () => (
  <XGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </XGroup>
)
```

## Sizing

The `size` property will use your tokens to grab the appropriate radius for borderRadius values which it will pass to the first and last child as style props for borderRadius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup size="6">
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Disabled

The `disabled` property will pass to children

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## Group API

### Group

`Group`, `XGroup`and`YGroup` extend [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'axis',
      required: false,
      type: '"horizontal" | "vertical"',
      description: `Forces applying the border radius styles to left/right vs top/bottom. Defaults to horizontal for XGroup and vertical for YGroup.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | SizeTokens',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Pass disabled down to children.`,
    },
    {
      name: 'disablePassBorderRadius',
      required: false,
      type: `boolean | 'bottom' | 'top' | 'start' | 'end'`,
      description: `Disables passing border radius to first/last children.`,
    },
    {
      name: 'forceUseItem',
      required: false,
      type: 'boolean',
      desctiption: `Can be used to force the group to assume it has Item components as children.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them.

Accepts only a `children` prop.


## components/group/1.0.0

---
title: Group
description: Render horizontal or vertical groups easily.
name: group
component: Group
demoName: Group
---

# Group

<Description>Layout buttons and more with groups.</Description>

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'One size prop for all styles',
    'Vertical or horizontal alignment',
    'Built-in spacing and disabled props',
    'Optional Item wrapper for finer control',
  ]}
/>

## Usage

Instead of a generic `Group`, Tamagui prefers `XGroup` and `YGroup` for consistency with stacks.

By default, Groups will control the border radius of their children automatically - the first and last children will get their start/end radius set to match group radius. If it's a `YGroup`, it will adjust top/bottom radius. `XGroup` adjusts the left/right radius.

You can use Groups with or without `Group.Item`, depending on if you want to spacing and separators to be handled based on direct children, or on each Item rendered.

```tsx
import { Button, XGroup } from 'tamagui'

// usage with Item:
export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

For a simpler use case and backwards compat, you can also use it without `Group.Item`, which will just apply borders and spacing based on direct children. Note that Group will detect if any `Group.Item` is inside it, and automatically switch modes. If no Item, it spaces direct children:

```tsx
import { Button, XGroup } from 'tamagui'

// usage without Item:
export default () => (
  <XGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </XGroup>
)
```

## Sizing

The `size` property will use your tokens to grab the appropriate radius for borderRadius values which it will pass to the first and last child as style props for borderRadius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup size="6">
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Disabled

The `disabled` property will pass to children

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## Group API

### Group

`XGroup` and `YGroup` extend [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | SizeTokens',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Pass disabled down to children.`,
    },
    {
      name: 'disablePassBorderRadius',
      required: false,
      type: 'boolean',
      description: `Disables passing border radius to first/last children.`,
    },
    {
      name: 'vertical',
      required: false,
      type: 'boolean',
      description: `Can be used to force an XGroup to render like a YGroup or vice-versa.`,
    },
    {
      name: 'forceUseItem',
      required: false,
      type: 'boolean',
      desctiption: `Can be used to force the group to assume it has Item components as children.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them.

Accepts only a `children` prop.


## components/group/1.56.1

---
title: Group
description: Render horizontal or vertical groups easily.
name: group
component: Group
demoName: Group
---

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'One size prop for all styles',
    'Vertical or horizontal alignment',
    'Built-in spacing and disabled props',
    'Optional Item wrapper for finer control',
  ]}
/>

## Installation

Group is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/group
```

## Usage

You can use `Group` by itself with the `orientation` property determining the direction it assumes.

By default, Groups will control the border radius of their children automatically - the first and last children will get their start/end radius set to match group radius. If it's a `YGroup`, it will adjust top/bottom radius. `XGroup` adjusts the left/right radius.

You can use Groups with or without `Group.Item`, depending on if you want to spacing and separators to be handled based on direct children, or on each Item rendered.

```tsx
import { Button, XGroup } from 'tamagui'

// usage with Item:
export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

For a simpler use case and backwards compat, you can also use it without `Group.Item`, which will just apply borders and spacing based on direct children. Note that Group will detect if any `Group.Item` is inside it, and automatically switch modes. If no Item, it spaces direct children:

```tsx
import { Button, XGroup } from 'tamagui'

// usage without Item:
export default () => (
  <XGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </XGroup>
)
```

## Sizing

The `size` property will use your tokens to grab the appropriate radius for borderRadius values which it will pass to the first and last child as style props for borderRadius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup size="6">
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Disabled

The `disabled` property will pass to children

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## API Reference

### Group

`Group`, `XGroup` and `YGroup` extend [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'orientation',
      required: false,
      type: '"horizontal" | "vertical"',
      description: `Forces applying the border radius styles to left/right vs top/bottom. Defaults to horizontal for XGroup and vertical for YGroup.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | SizeTokens',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Pass disabled down to children.`,
    },
    {
      name: 'disablePassBorderRadius',
      required: false,
      type: `boolean | 'bottom' | 'top' | 'start' | 'end'`,
      description: `Disables passing border radius to first/last children.`,
    },
    {
      name: 'forceUseItem',
      required: false,
      type: 'boolean',
      description: `Can be used to force the group to assume it has Item components as children.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them. It accepts the following props:

<PropsTable
  data={[
    {
      name: 'children',
      required: true,
      type: 'ReactNode',
    },
    {
      name: 'forcePlacement',
      required: false,
      type: '"first" | "center" | "last"',
      description: `Forces the item to be a starting, center or ending item and gets the respective styles`,
    },
  ]}
/>


## components/group/1.6.0

---
title: Group
description: Render horizontal or vertical groups easily.
name: group
component: Group
demoName: Group
---

# Group

<Description>Layout buttons and more with groups.</Description>

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'One size prop for all styles',
    'Vertical or horizontal alignment',
    'Built-in spacing and disabled props',
    'Optional Item wrapper for finer control',
  ]}
/>

## Usage

You can use `Group` by itself with the `axis` property determining the direction it assumes.

By default, Groups will control the border radius of their children automatically - the first and last children will get their start/end radius set to match group radius. If it's a `YGroup`, it will adjust top/bottom radius. `XGroup` adjusts the left/right radius.

You can use Groups with or without `Group.Item`, depending on if you want to spacing and separators to be handled based on direct children, or on each Item rendered.

```tsx
import { Button, XGroup } from 'tamagui'

// usage with Item:
export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

For a simpler use case and backwards compat, you can also use it without `Group.Item`, which will just apply borders and spacing based on direct children. Note that Group will detect if any `Group.Item` is inside it, and automatically switch modes. If no Item, it spaces direct children:

```tsx
import { Button, XGroup } from 'tamagui'

// usage without Item:
export default () => (
  <XGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </XGroup>
)
```

## Sizing

The `size` property will use your tokens to grab the appropriate radius for borderRadius values which it will pass to the first and last child as style props for borderRadius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup size="6">
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Disabled

The `disabled` property will pass to children

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## Group API

### Group

`Group`, `XGroup`and`YGroup` extend [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'axis',
      required: false,
      type: '"horizontal" | "vertical"',
      description: `Forces applying the border radius styles to left/right vs top/bottom. Defaults to horizontal for XGroup and vertical for YGroup.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | SizeTokens',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Pass disabled down to children.`,
    },
    {
      name: 'disablePassBorderRadius',
      required: false,
      type: 'boolean',
      description: `Disables passing border radius to first/last children.`,
    },
    {
      name: 'forceUseItem',
      required: false,
      type: 'boolean',
      desctiption: `Can be used to force the group to assume it has Item components as children.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them.

Accepts only a `children` prop.


## components/group/1.11.2

---
title: Group
description: Render horizontal or vertical groups easily.
name: group
component: Group
demoName: Group
---

# Group

<Description>Layout buttons and more with groups</Description>

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'One size prop for all styles',
    'Vertical or horizontal alignment',
    'Built-in spacing and disabled props',
    'Optional Item wrapper for finer control',
  ]}
/>

## Usage

You can use `Group` by itself with the `orientation` property determining the direction it assumes.

By default, Groups will control the border radius of their children automatically - the first and last children will get their start/end radius set to match group radius. If it's a `YGroup`, it will adjust top/bottom radius. `XGroup` adjusts the left/right radius.

You can use Groups with or without `Group.Item`, depending on if you want to spacing and separators to be handled based on direct children, or on each Item rendered.

```tsx
import { Button, XGroup } from 'tamagui'

// usage with Item:
export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

For a simpler use case and backwards compat, you can also use it without `Group.Item`, which will just apply borders and spacing based on direct children. Note that Group will detect if any `Group.Item` is inside it, and automatically switch modes. If no Item, it spaces direct children:

```tsx
import { Button, XGroup } from 'tamagui'

// usage without Item:
export default () => (
  <XGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </XGroup>
)
```

## Sizing

The `size` property will use your tokens to grab the appropriate radius for borderRadius values which it will pass to the first and last child as style props for borderRadius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup size="6">
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Disabled

The `disabled` property will pass to children

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## API Reference

### Group

`Group`, `XGroup` and `YGroup` extend [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'orientation',
      required: false,
      type: '"horizontal" | "vertical"',
      description: `Forces applying the border radius styles to left/right vs top/bottom. Defaults to horizontal for XGroup and vertical for YGroup.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | SizeTokens',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Pass disabled down to children.`,
    },
    {
      name: 'disablePassBorderRadius',
      required: false,
      type: `boolean | 'bottom' | 'top' | 'start' | 'end'`,
      description: `Disables passing border radius to first/last children.`,
    },
    {
      name: 'forceUseItem',
      required: false,
      type: 'boolean',
      desctiption: `Can be used to force the group to assume it has Item components as children.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them.

Accepts only a `children` prop.


## components/group/2.0.0

---
title: Group
description: Arrange controls in horizontal or vertical groups
name: group
component: Group
package: group
demoName: Group
---

<IntroParagraph>
  Group arranges related controls horizontally or vertically, squares off the
  border radius where items meet, and passes disabled state to its children.
</IntroParagraph>

<HeroContainer>
  <GroupDemo />
</HeroContainer>

```tsx hero template=Group

```

<Highlights
  features={[
    'Automatic border radius where items meet',
    'Vertical or horizontal alignment',
    'Independent sizing for each child',
    'Disabled state shared with children',
  ]}
/>

## Installation

Group is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/group
```

## Usage

Use `Group` with `Group.Item` wrapping each child. The `orientation` property determines the layout direction.

Group zeros out the border radius on connecting sides of children: the first child keeps its start radius, the last keeps its end radius, and middle items have no radius on connecting sides. For `YGroup`, this affects top/bottom radius. For `XGroup`, left/right radius.

```tsx
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup>
    <XGroup.Item>
      <Button>First</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button>Third</Button>
    </XGroup.Item>
  </XGroup>
)
```

## Sizing

Children control their own sizing. Apply size props directly to the child components. For responsive sizing, use media queries on the children:

```tsx
import { Activity, Airplay } from './components/icons' // your generated icons, see Lucide Icons
import { Button, XGroup } from 'tamagui'

export default () => (
  <XGroup>
    <XGroup.Item>
      <Button size="sm" height="gtSm:5" icon={Activity}>
        First
      </Button>
    </XGroup.Item>
    <XGroup.Item>
      <Button size="sm" height="gtSm:5" icon={Airplay}>
        Second
      </Button>
    </XGroup.Item>
  </XGroup>
)
```

## Separators

Add separators manually between items:

```tsx
import { ListItem, Separator, YGroup } from 'tamagui'

export default () => (
  <YGroup>
    <YGroup.Item>
      <ListItem title="First" />
    </YGroup.Item>
    <Separator />
    <YGroup.Item>
      <ListItem title="Second" />
    </YGroup.Item>
    <Separator />
    <YGroup.Item>
      <ListItem title="Third" />
    </YGroup.Item>
  </YGroup>
)
```

## Disabled

The `disabled` property will pass to children.

<HeroContainer>
  <GroupDisabledDemo />
</HeroContainer>

## Custom components & nested items

Automatic index detection only works when `Group.Item` is a **direct child** of `Group`. If you wrap `Group.Item` inside a custom component, the automatic first/last detection won't work.

You have a few options:

### Option 1: use `forcePlacement`

If you know the position ahead of time, use the `forcePlacement` prop:

```tsx
function MyFirstItem({ children }) {
  return <XGroup.Item forcePlacement="first">{children}</XGroup.Item>
}

export default () => (
  <XGroup>
    <MyFirstItem>
      <Button>First</Button>
    </MyFirstItem>
    <XGroup.Item>
      <Button>Second</Button>
    </XGroup.Item>
  </XGroup>
)
```

### Option 2: use `useGroupItem` hook

For full control, use the `useGroupItem` hook directly in your custom component:

```tsx
import { useGroupItem } from '@tamagui/group'

function MyItem({ children, forcePlacement }) {
  const groupItemProps = useGroupItem({ disabled: false }, forcePlacement)

  return React.cloneElement(children, groupItemProps)
}
```

### Option 3: pass placement from parent

Calculate positions in the parent and pass them down:

```tsx
const items = ['First', 'Second', 'Third']

export default () => (
  <XGroup>
    {items.map((item, i) => (
      <XGroup.Item
        key={item}
        forcePlacement={i === 0 ? 'first' : i === items.length - 1 ? 'last' : 'center'}
      >
        <Button>{item}</Button>
      </XGroup.Item>
    ))}
  </XGroup>
)
```

## API reference

### Group

`Group`, `XGroup` and `YGroup` extend [YStack](/ui/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'orientation',
      required: false,
      type: '"horizontal" | "vertical"',
      description: `Forces applying the border radius styles to left/right vs top/bottom. Defaults to horizontal for XGroup and vertical for YGroup.`,
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: `Passes disabled state down to children.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Group.Item

Wrap each of `XGroup` or `YGroup`'s children in one of these. It lets Tamagui apply the needed styles to them. It accepts the following props:

<PropsTable
  data={[
    {
      name: 'children',
      required: true,
      type: 'ReactNode',
      description: `The child element to wrap.`,
    },
    {
      name: 'forcePlacement',
      required: false,
      type: '"first" | "center" | "last"',
      description: `Forces the item to be a starting, center, or ending item and applies the respective styles.`,
    },
  ]}
/>


## components/field/1.0.0

---
title: Field
description: Accessible labels, messages, and validation state for form controls
name: field
component: Field
package: field
demoName: Field
---

<IntroParagraph>
  Field connects labels, controls, descriptions, validation, and error messages
  across web and native forms.
</IntroParagraph>

<HeroContainer>
  <FieldDemo />
</HeroContainer>

```tsx hero template=Field

```

<Highlights
  features={[
    `Automatic label, description, error, and control association`,
    `Validation functions and Standard Schema libraries`,
    `Shared validation state across web, iOS, and Android`,
    `Behavior-only components with app-owned styling`,
  ]}
/>

Field groups a control with its accessible name, supporting messages, and
validation state. It works on its own for common forms and can also sit under
React Hook Form or another form library.

The package has no visual defaults. Style its parts directly or copy a small
skin into your app.

## Installation

Field is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/field
```

## Usage

```tsx
import { Field, Form } from 'tamagui'

export function ProfileForm() {
  return (
    <Form onSubmit={(values) => console.log(values)}>
      <Field name="email" validationMode="onBlur">
        <Field.Label>Email</Field.Label>
        <EmailInput required />
        <Field.Description>Used for account recovery.</Field.Description>
        <Field.Error />
      </Field>

      <Form.Trigger />
    </Form>
  )
}
```

Controls integrate through `useFieldControl()`. The hook is also the extension
point for custom inputs:

```tsx
import { Field, Input } from 'tamagui'
import { useEffect, useRef } from 'react'

function EmailInput(props) {
  const field = Field.useFieldControl()
  const ref = useRef(null)
  const value = useRef('')

  useEffect(() => {
    return field.registerControl({
      id: field.ariaProps.id,
      controlRef: ref,
      inputRef: ref,
      getValue: () => value.current,
      required: props.required,
    })
  }, [field.ariaProps.id, field.registerControl, props.required])

  return (
    <Input
      {...props}
      {...field.ariaProps}
      {...field.dataProps}
      ref={ref}
      name={field.name}
      disabled={field.disabled || props.disabled}
      onFocus={field.onFocus}
      onBlur={() => field.onBlur(value.current)}
      onChange={(event) => {
        value.current = event.target.value
        field.onChange(value.current)
      }}
    />
  )
}
```

Outside a Field, `useFieldControl()` returns a stable no-op contract. A shared
control can consume it without adding a wrapper check or a second render path.

## Validation

Pass a function that returns one error, several errors, or `null`:

```tsx
<Field
  name="username"
  validate={(value, formValues) => {
    if (String(value).length < 3) {
      return 'Use at least 3 characters'
    }
    if (value === formValues.email) {
      return 'Username and email must differ'
    }
    return null
  }}
>
  {/* ... */}
</Field>
```

Async validators are supported. They never delay a submit. Field uses
monotonic validation commits, so a slow response for an old value cannot
replace a newer result.

Field also accepts a [Standard Schema](https://standardschema.dev/) directly.
Zod 4, Valibot, and ArkType implement this interface:

```tsx
import * as v from 'valibot'

const email = v.pipe(v.string(), v.email('Enter a valid email'))

<Field name="email" validate={email}>
  {/* ... */}
</Field>
```

`valid` is intentionally tri-state:

- `null` means the field has not been evaluated.
- `true` means the latest validation passed.
- `false` means the field is invalid.

Pristine fields do not emit valid or invalid state. A missing required value is
also suppressed until the user edits the field or tries to submit the form.

## Validation modes

`validationMode` can be set on Form and overridden by a Field:

- `onSubmit` is the default. After the first submit attempt, that field
  revalidates as its value changes.
- `onBlur` validates when focus leaves the control.
- `onChange` validates on every change. Use `validationDebounceTime` to delay
  expensive checks.

```tsx
<Form validationMode="onSubmit">
  <Field name="username" validationMode="onChange" validationDebounceTime={250}>
    {/* ... */}
  </Field>
</Form>
```

## Styling field state

Every Field part emits `data-valid`, `data-invalid`, `data-touched`,
`data-dirty`, `data-filled`, `data-focused`, and `data-disabled` on web.
The same keys are published through `FieldStyledContext` on native and web.

```tsx
import { Field, FieldStyledContext, Input, styled } from 'tamagui'

const FieldInput = styled(Input, {
  context: FieldStyledContext,

  variants: {
    invalid: {
      true: {
        borderColor: 'red-9',
      },
    },
  },
})
```

## Groups with Field.Item

Use `Field.Item` when one logical field owns several controls. Each item gets
its own label and description while sharing the root field state.

```tsx
<Field name="notifications">
  <Field.Label>Notifications</Field.Label>
  <Field.Description>Choose every channel you want to use.</Field.Description>

  <Field.Item>
    <Field.Label>Email</Field.Label>
    <NotificationCheckbox value="email" />
  </Field.Item>

  <Field.Item>
    <Field.Label>Push</Field.Label>
    <NotificationCheckbox value="push" />
  </Field.Item>

  <Field.Error />
</Field>
```

## Anatomy

```tsx
<Field>
  <Field.Label />
  {/* integrated control */}
  <Field.Description />
  <Field.Error />
  <Field.Item />
</Field>
```

## API reference

### Field

Contains the field state and validation behavior. It accepts
[Tamagui Props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'name',
      type: 'string',
      description: `The key used when Form projects submitted values and external errors.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      default: 'false',
      description: `Disables the field and its integrated controls.`,
    },
    {
      name: 'invalid',
      type: 'boolean',
      default: 'false',
      description: `Marks the field invalid without running its validator. Useful for errors known before validation runs.`,
    },
    {
      name: 'validate',
      type: 'FieldValidator | StandardSchemaV1',
      description: `Validates the field value. Functions receive (value, formValues).`,
    },
    {
      name: 'validationMode',
      type: `'onSubmit' | 'onBlur' | 'onChange'`,
      default: `'onSubmit'`,
      description: `Overrides the surrounding Form validation mode.`,
    },
    {
      name: 'validationDebounceTime',
      type: 'number',
      default: '0',
      description: `Milliseconds to debounce validation in onChange mode.`,
    },
  ]}
/>

### Field.Label

An accessible label. It is associated with the current item control
automatically. On native, pressing it focuses the registered control.

Accepts [Tamagui Props](/docs/intro/props).

### Field.Description

Supporting text added to the control description. Associations continue to
work when the message is rendered through a portal.

Accepts [Tamagui Props](/docs/intro/props).

### Field.Error

Renders the current validation or Form error when the field is invalid.

<PropsTable
  data={[
    {
      name: 'match',
      type: 'boolean | keyof FieldValidityState',
      description: `Shows for all errors by default, for one ValidityState key, or always when true.`,
    },
  ]}
/>

### Field.Item

Creates label and description scope for one member of a grouped field.

<PropsTable
  data={[
    {
      name: 'disabled',
      type: 'boolean',
      default: 'false',
      description: `Disables this item while retaining the root field state.`,
    },
  ]}
/>

### useFieldState

Returns the current value, errors, validity, and the `touched`, `dirty`,
`filled`, `focused`, and `disabled` flags.

### useFieldControl

Returns the control integration contract: `name`, `disabled`, `ariaProps`,
`dataProps`, focus/change reporters, and `registerControl`.


## components/surface/3.0.0

---
title: Surface
description: A panel, well, and toolbar primitive built from facets and theme levels
name: surface
component: Surface
---

<IntroParagraph>
  Surface is the starting point for panels, wells, and toolbars: a `YStack`
  with a `level` prop and composable visual and interaction facets.
</IntroParagraph>

Nothing is on by default. A bare `<Surface />` renders no chrome and no
interaction styling, and every facet is opt-in at the use site.

```tsx
import { Surface } from 'tamagui'

export default () => <Surface level={2} filled outlined rounded interactive />
```

<Highlights
  features={[
    `Plain YStack, level prop, and opt-in facets`,
    `Theme-generic facets, automatically restyled across themes and levels`,
    `Forkable recipe for app-specific Surface variants`,
  ]}
/>

## Installation

Surface is already installed in `tamagui`:

```tsx
import { Surface } from 'tamagui'
```

Surface is also a registry item you can copy into your own component layer and
own; see [Build your own](#build-your-own).

## Levels

`level` shifts the subtree through the relative `level2`, `level3`, or `level4`
sub-theme. Because facets read theme generics (`background`, `border-color`, …)
and the level theme re-binds those generics, a level restyles every facet
beneath it with no cooperation. Read [Surfaces and
levels](/docs/core/surfaces) for the full theming model.

```tsx
<Surface level={1} filled>Base panel</Surface>
<Surface level={2} filled>A step up</Surface>
<Surface level={3} filled>A step further</Surface>
<Surface level={4} filled>The highest default level</Surface>
```

`level` is a prop, not a variant, because a theme boundary can only be created by
the `theme` prop or `<Theme>` component. `<Surface level={2}>` renders
`<Theme name="level2">` around the frame.

## Facets

Facets are canonical boolean variants, each a pure function of theme generics plus
standard tokens. Chrome facets own one property family each and set static
styles only; the interaction facet owns pseudos only. Because family ownership
keeps them from colliding, any combination composes with zero coordination.

There are no preset combinations. The Material-style border-minus-fill look is just
`outlined` without `filled`: a documented composition, not a separate facet.

## Build your own

Most apps just import Surface. Copy it into your own component layer when you
want variants of your own: a card panel with different defaults than a toolbar
well, your own radius, or facets tuned to your design system. The copy is a plain
component: change it freely and nothing in the framework cares.

Copy it from the registry:

```bash
npx shadcn add surface
```

That installs `components/tamagui/Surface.tsx` plus its sibling
`components/tamagui/facets.tsx`, which holds the shared facet definitions.
`Surface.tsx` imports them through a relative `./facets` import, so keep the two
files together and adjust the path if your tree puts them elsewhere.

Surface is generated from a single definition. The `level` wrapper and the facet
set are all it is:

```tsx
import { type GetProps, styled, Theme } from '@tamagui/core'
import { YStack } from '@tamagui/stacks'
import { forwardRef } from 'react'

import { elevated, filled, interactive, outlined, rounded } from './facets'

export const SurfaceFrame = styled(YStack, {
  displayName: 'Surface',

  variants: {
    filled,
    outlined,
    elevated,
    roundedFacet: rounded,
    interactive,
  } as const,
})

export type SurfaceProps = Omit<
  GetProps<typeof SurfaceFrame>,
  'roundedFacet' | 'rounded'
> & {
  /** shift the subtree to a relative theme level. */
  level?: 1 | 2 | 3 | 4
  /** add the default component radius without depending on config shorthands. */
  rounded?: boolean
}

export const Surface = forwardRef<any, SurfaceProps>(function Surface(
  { level, rounded, ...props },
  ref
) {
  const frame = <SurfaceFrame ref={ref} roundedFacet={rounded} {...props} />
  if (!level || level === 1) return frame
  return <Theme name={`level${level}` as 'level2' | 'level3' | 'level4'}>{frame}</Theme>
})
```

The facets live in a sibling `facets.tsx` so any skin can compose the same chrome:

```tsx
export const filled = {
  true: { backgroundColor: 'background' },
} as const

export const outlined = {
  true: { borderWidth: 1, borderColor: 'border-color' },
} as const

export const elevated = {
  true: {
    shadowColor: 'shadow-color',
    shadowRadius: 8,
    shadowOffset: { width: 0, height: 2 },
  },
} as const

export const rounded = {
  true: { borderRadius: '4' },
} as const

export const interactive = {
  true: {
    backgroundColor: 'hover:background-hover press:background-press',
    borderColor: 'hover:border-color-hover press:border-color-press',
    scale: 'press:0.97',
    outlineColor: 'focus-visible:outline-color',
    outlineWidth: 'focus-visible:2px',
    outlineStyle: 'focus-visible:solid',
  },
} as const
```

Component skins like Card and ListItem do not extend Surface. They get their
family resemblance by styling against the same generics, so restyling a level
recolors them too. Fork the copy when you want a differently-shaped panel.

## API reference

### Surface

A `YStack` with a `level` prop and composable facets, plus all the
[Tamagui standard props](/docs/intro/props):

<PropsTable
  data={[
    {
      name: 'level',
      required: false,
      type: '1 | 2 | 3 | 4',
      description: `Shift the subtree through a relative level theme.`,
    },
    {
      name: 'filled',
      required: false,
      type: 'boolean',
      description: `Chrome: backgroundColor from background.`,
    },
    {
      name: 'outlined',
      required: false,
      type: 'boolean',
      description: `Chrome: 1px borderWidth with borderColor from border-color.`,
    },
    {
      name: 'elevated',
      required: false,
      type: 'boolean',
      description: `Chrome: a shadow read from shadow-color.`,
    },
    {
      name: 'rounded',
      required: false,
      type: 'boolean',
      description: `Chrome: the default component radius.`,
    },
    {
      name: 'interactive',
      required: false,
      type: 'boolean',
      description: `Interaction: hover, press, and focus-visible feedback read from the generics (background-hover, background-press, border-color*, and outline-color).`,
    },
  ]}
/>


## components/adapt/3.0.0

---
title: Adapt
description: Re-render a component's contents into a different container per breakpoint or platform
name: adapt
component: Adapt
package: adapt
---

<IntroParagraph>
  Adapt lets one component render its contents somewhere else. A Select that is a
  dropdown on desktop becomes a Sheet on touch devices, without duplicating the
  contents or the open state.
</IntroParagraph>

<Highlights
  features={[
    `Switch containers by media query, by platform, or both`,
    `Contents move, they are not re-declared`,
    `Open state, dismissal and exit animations hand off to the new container`,
    `Built into Dialog, Popover and Select`,
    `Scoped, so nested adapting components don't capture each other`,
  ]}
/>

## Installation

Adapt ships with `tamagui`, or you can install it independently:

```bash
npm install @tamagui/adapt
```

## How it works

Adapt is two markers used together:

- `<Adapt>` says **when** to adapt and **what to adapt into**.
- `<Adapt.Contents />` says **where** inside that new container the original
  contents should appear.

The contents are not re-rendered from scratch into the new tree. They are
published to a slot and read by `Adapt.Contents`, so state inside them survives
the switch, and the adapting component keeps owning `open` / `onOpenChange`.

```tsx
import { Adapt, Select, Sheet } from 'tamagui'

export default () => (
  <Select>
    <Select.Trigger>
      <Select.Value placeholder="Pick one" />
    </Select.Trigger>

    <Select.Content>{/* the desktop dropdown */}</Select.Content>

    <Adapt when="max-md" platform="touch">
      <Sheet modal dismissOnSnapToBottom>
        <Sheet.Overlay />
        <Sheet.Container>
          <Sheet.Background />
          <Sheet.ScrollView>
            {/* Select.Content lands here when adapted */}
            <Adapt.Contents />
          </Sheet.ScrollView>
        </Sheet.Container>
      </Sheet>
    </Adapt>
  </Select>
)
```

When the `max-md` media query is inactive, the `<Adapt>` subtree renders nothing
and `Select.Content` renders in place as usual. When it becomes active, the
Sheet mounts and `Select.Content` moves into it.

`<Adapt>` must be a child of a component that supports adapting. Rendering it
anywhere else throws. Dialog, Popover and Select also expose it as a static
property (`<Select.Adapt>`, `<Dialog.Adapt>`, `<Popover.Adapt>`), which is the
same component.

## Choosing when to adapt

`when` and `platform` are both optional, but at least one is required: with
neither set, Adapt is never active.

```tsx
{/* active below the md breakpoint */}
<Adapt when="max-md">

{/* active on any touch device, at any width */}
<Adapt platform="touch">

{/* active only on a touch device below md */}
<Adapt when="max-md" platform="touch">

{/* always active */}
<Adapt when={true}>
```

`when` takes any media query key from your config, or a boolean. `platform`
takes `'web'`, `'native'`, `'ios'`, `'android'` or `'touch'`.

When you set both, both must pass. `<Adapt when={true} platform="touch">` is on
for every width, but only on touch devices.

Because `when` reads media state, you can also drive it from your own logic:

```tsx
<Adapt when={useMedia().sm && !isEmbedded}>
  <Sheet>{/* ... */}</Sheet>
</Adapt>
```

## Adapting Dialog and Popover

Dialog and Popover use the same handoff. For both, put `Adapt.Contents` inside
the Sheet's scrollable area:

```tsx
import { Adapt, Popover, Sheet } from 'tamagui'

export default () => (
  <Popover>
    <Popover.Trigger asChild>
      <Button>Open</Button>
    </Popover.Trigger>

    <Popover.Content>
      <Popover.Arrow />
      {/* ... */}
    </Popover.Content>

    <Adapt when="max-md">
      <Sheet snapPointsMode="fit" modal dismissOnSnapToBottom>
        <Sheet.Overlay />
        <Sheet.Container>
          <Sheet.Background />
          <Sheet.ScrollView>
            <Adapt.Contents />
          </Sheet.ScrollView>
        </Sheet.Container>
      </Sheet>
    </Adapt>
  </Popover>
)
```

Adapted content stays mounted through the Sheet's exit animation and only
unmounts once the Sheet reports that it is fully hidden, so closing looks the
same whether or not the component is adapted.

Parts that only make sense in the unadapted layout drop out while adapted:
`Popover.Arrow`, `Dialog.Overlay` and `Dialog.Close` all render `null`, and
Dialog's content renders without its own frame, focus scope or dismissable
layer, so the Sheet's take over. `Dialog.Close` takes `displayWhenAdapted` if
you do want it inside the Sheet.

## Scoping

Leave `scope` off and `<Adapt>` binds to the nearest adapting parent, which is
what you want nearly always. Nesting is already safe: a parent only reads an
`<Adapt>` from its own direct children (descending into fragments), so a Dialog
rendered inside a Popover's content does not steal the Popover's adaptation, or
hand it its own.

The `scope` on `<Adapt>` is not the `scope` you pass to Dialog, Popover or
Select. It is that component's internal adapt scope, which is its own scope
prefixed by the component name:

| Component | Adapt scope            |
| --------- | ---------------------- |
| Dialog    | `DialogAdapt<scope>`   |
| Popover   | `PopoverAdapt<scope>`  |
| Select    | `AdaptSelect<scope>`   |

An unscoped Dialog is therefore `DialogAdapt`, and `<Dialog scope="settings">`
is `DialogAdaptsettings`. The same string goes on `<Adapt.Contents />` if you
scope it.

## Adapting into something other than a Sheet

Anything can be an adapt target. The render-callback form of `children` gives
you the contents plus the parent's open state, so you can render your own
container:

```tsx
import { Adapt } from 'tamagui'

;<Adapt when="max-md">
  {(contents, { open, onOpenChange }) => (
    <MyDrawer open={open} onOpenChange={onOpenChange}>
      {contents}
    </MyDrawer>
  )}
</Adapt>
```

If your container is a component of its own, read the same state with
`useAdaptTarget()` instead, which is what Sheet does:

```tsx
import { useAdaptTarget } from 'tamagui'

function MyDrawer(props) {
  const adapt = useAdaptTarget()

  // null when this drawer is not currently an adapt target
  if (!adapt) return <Inline {...props} />

  return (
    <Drawer
      open={adapt.open && !adapt.handoff.hidden}
      onOpenChange={adapt.onOpenChange}
      onAnimationComplete={adapt.handoff.onTransition}
    />
  )
}
```

`handoff` is how the parent and the target agree on timing. `handoff.hidden`
tells the target to play its exit, and calling `handoff.onTransition` with the
completed transition lets the parent unmount the contents at the right moment
instead of on a timer.

## API reference

### Adapt

<PropsTable
  data={[
    {
      name: 'when',
      type: 'MediaQueryKey | boolean | null',
      required: false,
      description: `A media query key from your config, or a boolean. Active when the query matches; true is always active.`,
    },
    {
      name: 'platform',
      type: `'web' | 'native' | 'ios' | 'android' | 'touch' | null`,
      required: false,
      description: `Restricts the adaptation to a platform. When combined with when, both must pass.`,
    },
    {
      name: 'scope',
      type: 'string',
      required: false,
      description: `Binds this Adapt to a specific adapting parent. Defaults to the nearest one.`,
    },
    {
      name: 'children',
      type: 'JSX.Element | ((contents: React.ReactNode, adapt: AdaptRenderState) => React.ReactNode)',
      required: true,
      description: `The container to adapt into, which should contain an Adapt.Contents. As a function, it receives the contents element and { active, open, onOpenChange, state, handoff } so you can render your own container.`,
    },
  ]}
/>

### Adapt.Contents

Marks where the adapted contents render inside the new container. Exactly one
should be rendered while an adaptation is active; in development, zero targets
or more than one logs an error.

<PropsTable
  data={[
    {
      name: 'scope',
      type: 'string',
      required: false,
      description: `Binds to a specific adapting parent, matching the scope on Adapt.`,
    },
  ]}
/>

### useAdaptIsActive

`useAdaptIsActive(scope?: string): boolean`

Whether an adaptation is currently active. Use it to branch rendering inside
content that is sometimes adapted.

### useAdaptTarget

`useAdaptTarget<State>(scope?: string): AdaptTarget<State> | null`

Returns `null` unless an adaptation is active and the caller is under its
`<Adapt>` element. Pass `scope` to target that adaptation explicitly from
outside the element. When it is a target, the hook returns
`{ open, onOpenChange, state, handoff }`. Calling it also registers the caller
as the adapt target for development-time validation.

`handoff` is `{ hidden: boolean, skipNextAnimation?: boolean, onTransition: (e) => void }`,
where the transition event is `{ phase: 'start' | 'end', cause: 'open' | 'close' | 'snap', finished?: boolean }`.

`state` is whatever the adapting component chose to pass through. Dialog passes
its internal context; Popover and Select pass nothing.

## Troubleshooting

**"You're rendering a Tamagui `<Adapt />` component without nesting it inside a
parent that is able to adapt."** `<Adapt>` or `<Adapt.Contents />` is outside
a Dialog, Popover or Select. If the component uses `scope`, pass the matching
`scope` to `<Adapt>` too.

**"Adapt is active but no target registered"** the adaptation turned on but
nothing consumed the contents. Add an `<Adapt.Contents />` inside the container
you adapt into.

**"Adapt expected exactly one target"** two containers are claiming the same
scope. Render one `<Adapt.Contents />` per active adaptation.


## components/context-menu/2.0.0

---
title: Context Menu
description: A menu component triggered by right-click on web and long press on touch devices
name: context-menu
component: ContextMenu
package: context-menu
demoName: ContextMenu
---

<IntroParagraph>
  ContextMenu opens an accessible menu from a right click on web or a long press
  on touch devices.
</IntroParagraph>

<HeroContainer>
  <ContextMenuDemo />
</HeroContainer>

```tsx hero template=ContextMenu

```

<Highlights
  features={[
    'Full keyboard navigation',
    'Items, icons, images, checkboxes, and groups',
    'Submenu support',
    'Modal and non-modal modes',
    'Platform-native menus on mobile',
    'Custom alignment, offsets, and positioning',
    'Native iOS and Android icons',
    'Native previews on iOS',
  ]}
/>

ContextMenu displays a menu triggered by right-click on web or long-press on mobile. It supports submenus, native platform menus with iOS previews, and [automatically stacks](/ui/z-index) above other content.

## Installation

ContextMenu is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/context-menu
```

For Expo 57 and React Native 0.86, use the Expo UI adapter:

```bash
npm install @expo/ui
```

Then add the setup import at your app entry point:

```tsx
import '@tamagui/native/setup-expo-ui-menu'
```

The Zeego adapter remains available for apps on compatible React Native versions:

```bash
npm install @react-native-menu/menu react-native-ios-context-menu react-native-ios-utilities zeego sf-symbols-typescript
```

```tsx
import '@tamagui/native/setup-zeego'
```

On native, `ContextMenu.Trigger` coordinates with parent Tamagui pressables
automatically. You should not need extra wrapper views or empty `onPress`
handlers just to prevent a parent `press:` clause from activating.

<Notice theme="yellow">
  **Expo Router users:** This import must run _before_ `expo-router/entry`. Create an `index.js` at your project root that imports the setup first, then expo-router, and update your `package.json` main field to `"index.js"`. See the [Expo guide](/docs/guides/expo) for details.
</Notice>

## Anatomy

Import all parts and piece them together.

```tsx
import { ContextMenu } from 'tamagui' // or '@tamagui/context-menu'

export default () => (
  <ContextMenu>
    <ContextMenu.Trigger asChild>
      <YStack>
        <Text>Right Click or longPress</Text>
      </YStack>
    </ContextMenu.Trigger>

    <ContextMenu.Portal zIndex={100}>
      <ContextMenu.Content>
        <ContextMenu.Item>
          <ContextMenu.ItemTitle>About Notes</ContextMenu.ItemTitle>
        </ContextMenu.Item>
        <ContextMenu.Item>
          <ContextMenu.ItemTitle>Settings</ContextMenu.ItemTitle>
        </ContextMenu.Item>
        {/* when title is nested inside a React element then you need to use `textValue` */}
        <ContextMenu.Item textValue="Calendar">
          <ContextMenu.ItemTitle>
            <Text>Calendar</Text>
          </ContextMenu.ItemTitle>
          <ContextMenu.ItemIcon>
            <Calendar color="gray" size="1" />
          </ContextMenu.ItemIcon>
        </ContextMenu.Item>
        <ContextMenu.Separator />
        <ContextMenu.Sub>
          <ContextMenu.SubTrigger>
            <ContextMenu.ItemTitle>Actions</ContextMenu.ItemTitle>
          </ContextMenu.SubTrigger>
          <ContextMenu.Portal zIndex={200}>
            <ContextMenu.SubContent>
              <ContextMenu.Label fontSize={'1'}>Note settings</ContextMenu.Label>
              <ContextMenu.Item onSelect={onSelect} key="create-note">
                <ContextMenu.ItemTitle>Create note</ContextMenu.ItemTitle>
              </ContextMenu.Item>
              <ContextMenu.Item onSelect={onSelect} key="delete-all">
                <ContextMenu.ItemTitle>Delete all notes</ContextMenu.ItemTitle>
              </ContextMenu.Item>
              <ContextMenu.Item onSelect={onSelect} key="sync-all">
                <ContextMenu.ItemTitle>Sync notes</ContextMenu.ItemTitle>
              </ContextMenu.Item>
            </ContextMenu.SubContent>
          </ContextMenu.Portal>
        </ContextMenu.Sub>
      </ContextMenu.Content>
    </ContextMenu.Portal>
  </ContextMenu>
)
```

## API reference

### ContextMenu

Contains every component for the ContextMenu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu parts: Trigger, Portal, Content, Items, etc.',
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `Where the menu appears relative to the trigger. Options: 'top' | 'right' | 'bottom' | 'left' with optional '-start' | '-end' alignment.`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: 'Controlled open state for the menu.',
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: 'Initial open state when uncontrolled.',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean, event?: { preventDefault: () => void }) => void',
      required: false,
      description: 'Called when the menu opens or closes. Call event.preventDefault() to cancel and allow the native context menu to show instead.',
    },
    {
      name: 'onOpenWillChange',
      type: '(open: boolean) => void',
      required: false,
      platform: 'ios',
      description: 'Called before the open/close animation begins.',
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description:
        'When true, traps focus inside the menu and blocks outside scroll/interactions.',
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: 'Shifts the menu horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).',
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: 'Flips the menu to the opposite side if there is insufficient space.',
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      default: '10',
      description: 'Distance between the menu and its trigger.',
    },
    {
      name: 'resize',
      type: 'boolean',
      default: 'true',
      required: false,
      description: 'Constrains the menu to fit within available viewport space.',
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: 'Removes all default Tamagui styles.',
    },
  ]}
/>

#### Allowing native context menu

You can call `event.preventDefault()` in `onOpenChange` to prevent the Tamagui menu from opening and allow the native browser context menu to appear instead:

```tsx
<ContextMenu
  onOpenChange={(open, event) => {
    if (someCondition) {
      // prevent Tamagui menu, let native context menu show
      event?.preventDefault()
    }
  }}
>
  {/* ... */}
</ContextMenu>
```

### ContextMenu.Portal

This is necessary for the ContextMenu.

<PropsTable
  data={[
    {
      name: 'zIndex',
      required: false,
      type: 'number',
      description: 'Stacking order of the portal layer.',
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Content to render inside the portal.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description:
        'Forces the portal to stay mounted, useful for controlling animations.',
    },
  ]}
/>

### ContextMenu.Trigger

The ContextMenu will only be triggered when the user right-clicks or
long-presses within the Trigger area.

<PropsTable
  data={[
    {
      name: 'action',
      required: false,
      type: 'press|longPress',
      default: 'longPress',
      platform: 'android/ios',
      description:
        "Works with the native prop and accepts 'press' or 'longPress'. The default is 'longPress' for ContextMenu.",
    },
  ]}
/>

### ContextMenu.Content

Contains the content of the ContextMenu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu items, groups, labels, separators, and submenus.',
    },
    {
      name: 'loop',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Whether keyboard navigation wraps from last to first item.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description:
        'Forces the content to stay mounted, useful for controlling animations.',
    },
    {
      name: 'onCloseAutoFocus',
      type: '(event: Event) => void',
      required: false,
      description: 'Called when focus returns to the trigger after closing.',
    },
    {
      name: 'onEscapeKeyDown',
      type: '(event: KeyboardEvent) => void',
      required: false,
      description: 'Called when the escape key is pressed. Can be prevented.',
    },
    {
      name: 'onPointerDownOutside',
      type: '(event: PointerEvent) => void',
      required: false,
      description: 'Called when a pointer event occurs outside the content.',
    },
    {
      name: 'onInteractOutside',
      type: '(event: Event) => void',
      required: false,
      description: 'Called when any interaction occurs outside the content.',
    },
  ]}
/>

### ContextMenu.Item

A selectable menu item that triggers an action when selected.

<PropsTable
  data={[
    {
      name: 'key',
      type: 'string',
      required: true,
      description: 'Unique identifier for the item.',
    },
    {
      name: 'disabled',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Prevents interaction and dims the item.',
    },
    {
      name: 'destructive',
      type: 'boolean',
      required: false,
      platform: 'ios/android',
      description:
        'Renders the item in red on iOS to indicate a dangerous action (e.g. delete). No effect on web.',
    },
    {
      name: 'hidden',
      type: 'boolean',
      required: false,
      description: 'Hides the item from the menu.',
    },
    {
      name: 'onSelect',
      type: '(event?: Event) => void',
      required: false,
      description: 'Called when the item is selected via click or keyboard.',
    },
    {
      name: 'onFocus',
      type: '() => void',
      required: false,
      description: 'Called when the item receives focus.',
    },
    {
      name: 'onBlur',
      type: '() => void',
      required: false,
      description: 'Called when the item loses focus.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description:
        'Text used for typeahead and native menus. Required when ItemTitle contains a React node instead of a string.',
    },
  ]}
/>

### ContextMenu.ItemTitle

Renders the title of the menu item.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string | React.ReactNode',
      required: true,
      description: 'The title text or element to display.',
    },
  ]}
/>
<Notice>
  You can directly pass a text node to the ItemTitle. However, if you use a nested
  React node like `<Text>`, you need to pass `textValue` to the `<Item>` so that it
  works with native menus.
</Notice>

### ContextMenu.ItemIcon

A component to render an icon. For non-native menus, you can pass an icon
component. For native menus, you can pass platform-specific icons to the
`android`/`ios` props.

On iOS, it renders the native
[SF Symbols](https://github.com/andrewtavis/sf-symbols-online) icons.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: false,
      description: 'Fallback icon for web when native icons are not available.',
    },
    {
      name: 'ios',
      type: 'object',
      required: false,
      platform: 'ios',
      description:
        'SF Symbol configuration: name, weight, scale, hierarchicalColor, paletteColors.',
    },
    {
      name: 'android',
      type: 'object',
      required: false,
      platform: 'android',
      description: 'Android resource drawable name.',
    },
  ]}
/>

```tsx line=1
<ContextMenu.ItemIcon
  ios={{
    name: '0.circle.fill', // required
    pointSize: 5,
    weight: 'semibold',
    scale: 'medium',
    // can also be a color string. Requires iOS 15+
    hierarchicalColor: {
      dark: 'blue',
      light: 'green',
    },
    // alternative to hierarchical color. Requires iOS 15+
    paletteColors: [
      {
        dark: 'blue',
        light: 'green',
      },
    ],
  }}
>
  <CircleIcon />
</ContextMenu.ItemIcon>
```

### ContextMenu.ItemImage

A component to render an item image. For native menus, it only works on iOS. It
takes the same properties as `@tamagui/image`.

### ContextMenu.ItemSubtitle

A component to render a subtitle for the menu item. For native menus, it only
works on iOS.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string',
      required: true,
      description: 'The subtitle text to display below the title.',
    },
  ]}
/>

### ContextMenu.Group

A component that groups multiple menu items together.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'Menu items to group together.',
    },
  ]}
/>

### ContextMenu.CheckboxItem

A menu item with a checkbox that can be toggled on/off.

<PropsTable
  data={[
    {
      name: 'key',
      type: 'string',
      required: true,
      description: 'Unique identifier for the checkbox item.',
    },
    {
      name: 'disabled',
      type: 'boolean',
      required: false,
      default: 'false',
      description: 'Prevents interaction and dims the item.',
    },
    {
      name: 'destructive',
      type: 'boolean',
      required: false,
      platform: 'ios/android',
      description:
        'Renders the item in red on iOS to indicate a dangerous action. No effect on web.',
    },
    {
      name: 'hidden',
      type: 'boolean',
      required: false,
      description: 'Hides the item from the menu.',
    },
    {
      name: 'onFocus',
      type: '() => void',
      required: false,
      description: 'Called when the item receives focus.',
    },
    {
      name: 'onBlur',
      type: '() => void',
      required: false,
      description: 'Called when the item loses focus.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description:
        'Text for native menus. Required when ItemTitle contains a React node.',
    },
    {
      name: 'value',
      type: "'on' | 'off' | 'mixed'",
      required: false,
      platform: 'ios/android',
      description: 'Controlled checked state for native menus.',
    },
    {
      name: 'onValueChange',
      type: '(state, prevState) => void',
      required: false,
      platform: 'ios/android',
      description: 'Called when checked state changes on native menus.',
    },
    {
      name: 'checked',
      type: 'boolean',
      required: false,
      description: 'Controlled checked state for web menus.',
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
      required: false,
      description: 'Called when checked state changes on web.',
    },
  ]}
/>

### ContextMenu.ItemIndicator

Use inside `CheckboxItem` or `RadioItem` to indicate when an item is checked.
This allows you to conditionally render a checkmark.

```tsx line=1
<ContextMenu.ItemIndicator>
  <CheckmarkIcon /> {/* This does not work with the native prop. */}
</ContextMenu.ItemIndicator>
```

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: false,
      description: 'Custom checkmark icon. Only works on web.',
    },
    {
      name: 'forceMount',
      type: 'true',
      required: false,
      description: 'Forces the indicator to stay mounted for animation control.',
    },
  ]}
/>

### ContextMenu.Label

Renders a non-focusable label for a group of items. On native menus, only one
label is supported per menu and submenu.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'string',
      required: true,
      description: 'The label text.',
    },
    {
      name: 'textValue',
      type: 'string',
      required: false,
      platform: 'ios/android',
      description: 'Text for native menus when children is a React node.',
    },
  ]}
/>

### ContextMenu.Arrow

Renders an arrow pointing to the trigger.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'number | SizeToken',
      required: false,
      description: 'Width and height of the arrow.',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      required: false,
      description: 'Removes default arrow styles.',
    },
  ]}
/>

### ContextMenu.Separator

Renders a visual divider between menu items. Web only.

### ContextMenu.Sub

A container for nested sub-menu components.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: 'SubTrigger, Portal, and SubContent components.',
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: 'Controlled open state for the sub-menu.',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
      description: 'Called when the sub-menu opens or closes.',
    },
  ]}
/>

### ContextMenu.SubContent

Renders the content of a sub-menu. Same props as `Content`.

### ContextMenu.SubTrigger

A menu item that opens a sub-menu on hover/focus. Accepts the same props as
`Item`.

### ContextMenu.Preview

When the ContextMenu is visible, this renders a custom preview component. Only
works with native iOS menus.

<Notice>Should be rendered as a child of `ContextMenu.Content`.</Notice>

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode | (() => React.ReactNode)',
      required: true,
      platform: 'ios',
      description: 'The preview content to render. Can be a function for lazy rendering.',
    },
    {
      name: 'size',
      type: '{ width?: number, height?: number }',
      required: false,
      platform: 'ios',
      description: 'Dimensions of the preview.',
    },
    {
      name: 'onPress',
      type: '() => void',
      required: false,
      platform: 'ios',
      description: 'Called when the preview is pressed.',
    },
    {
      name: 'backgroundColor',
      type: 'string | { dark: string, light: string }',
      required: false,
      platform: 'ios',
      description: 'Background color of the preview.',
    },
    {
      name: 'borderRadius',
      type: 'number',
      required: false,
      platform: 'ios',
      description: 'Border radius of the preview.',
    },
    {
      name: 'preferredCommitStyle',
      type: "'pop' | 'dismiss'",
      required: false,
      default: "'dismiss'",
      platform: 'ios',
      description:
        "Exit transition when preview is tapped. Use 'pop' when navigating to another screen.",
    },
  ]}
/>

```tsx line=1
<ContextMenu.Preview
  // optional props:
  preferredCommitStyle="pop" // or "dismiss"
  backgroundColor={{
    // or a color string directly
    dark: 'black',
    light: 'white',
  }}
>
  {() => <Preview />}
</ContextMenu.Preview>
```


## components/list-item/1.0.0

---
title: ListItem
description: A component for showing columns of items.
name: list-item
component: ListItem
package: list-item
demoName: ListItem
---

<HeroContainer>
  <ListItemDemo />
</HeroContainer>

```tsx hero template=ListItem

```

<Highlights
  features={[
    'One size prop for all styles',
    'Icons before or after content',
    'Themes, animations, and Group support',
  ]}
/>

## Installation

ListItem is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/list-item
```

## Usage

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem>Lorem ipsum</ListItem>
```

## Sizing

Sizing listItems provides a unique challenge especially for a compiler, because you need to adjust many different properties - not just on the outer frame, but on the text wrapped inside. Tamagui supports adjusting the padding, border radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem size="6">Lorem ipsum</ListItem>
```

Given your theme defines a size `6`, the listItem will adjust all of the properties appropriately. You can also pass a plain number to get an arbitrary size.

## Icon Theming

You can pass icons as either elements or components. If passing components, Tamagui will automatically pass the `size` and `color` prop to them based on your theme.

## Customization

ListItem only supports a limited subset of text props directly. If you need more control over state-specific text values, customize its text component with flat clauses:

```tsx
import { forwardRef } from 'react'
import {
  ListItemFrame,
  ListItemText,
  ListItemTitle,
  ListItemSubtitle,
  styled,
  themeable,
  useListItem,
} from 'tamagui'

const CustomListItemFrame = styled(ListItemFrame, {
  backgroundColor: 'orange', // or "color", etc.
})

const CustomListItemTitle = styled(ListItemTitle, {
  color: 'blue',
})

const CustomListItemSubtitle = styled(ListItemSubtitle, {
  color: 'pink',
})

const CustomListItemText = styled(ListItemText, {
  color: 'red',
})

export const ListItem = CustomListItemFrame.styleable((propsIn, ref) => {
  const { props } = useListItem(propsIn, {
    Title: CustomListItemTitle,
    Text: CustomListItemText,
    Subtitle: CustomListItemSubtitle,
  })

  return <CustomListItemFrame {...props} ref={ref} />
})
```

There are 3 different components you can customize: `ListItemText`, `ListItemSubtitle` and `ListItemTitle`.

You can include whichever one you want to customize specifically.

If you only want to customize the the text pieces, you don't have to include `CustomListItemFrame`:

```tsx
// all the text changes from above, with a default ListItemFrame
export const ListItem = themeable(
  forwardRef<TamaguiElement, ListItemProps>((propsIn, ref) => {
    const { props } = useListItem(propsIn, {
      Title: CustomListItemTitle,
      Text: CustomListItemText,
      Subtitle: CustomListItemSubtitle,
    })

    return <ListItemFrame {...props} ref={ref} />
  })
)
```

## API Reference

### ListItem

ListItems extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'title',
      required: false,
      type: 'React.ReactNode',
      description: `Can use either children or title + subTitle to set the contents.`,
    },
    {
      name: 'subTitle',
      required: false,
      type: 'React.ReactNode',
      description: `Sets a subTitle, recommended to use with title.`,
    },
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the listItem and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, ListItem won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon more than usual by this number.`,
    },
    {
      name: 'scaleSpace',
      required: false,
      type: 'number',
      description: `Scale the spacing more than usual by this number.`,
    },
    {
      name: 'spaceFlex',
      required: false,
      type: `boolean`,
      description: `Makes all space elements have a flex.`,
    },
    {
      name: 'color',
      required: false,
      type: `SizableTextProps['color']`,
      description: `Passes "color" down to the inner text component`,
    },
    {
      name: 'fontWeight',
      required: false,
      type: `SizableTextProps['fontWeight']`,
      description: `Passes "fontWeight" down to the inner text component`,
    },
    {
      name: 'letterSpacing',
      required: false,
      type: `SizableTextProps['letterSpacing']`,
      description: `Passes "letterSpacing" down to the inner text component`,
    },
    {
      name: 'textAlign',
      required: false,
      type: `SizableTextProps['textAlign']`,
      description: `Passes "textAlign" down to the inner text component`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### ListItem.Title

`ListItem.Title` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).

### ListItem.Subtitle

`ListItem.Subtitle` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).

### ListItem.Text

`ListItem.Text` extend `SizableText` inheriting all the [props](/docs/components/text#sizabletext).


## components/list-item/2.0.0

---
title: ListItem
description: A component for displaying rows of items
name: list-item
component: ListItem
package: list-item
demoName: ListItem
---

<HeroContainer>
  <ListItemDemo />
</HeroContainer>

```tsx hero template=ListItem

```

<Highlights
  features={[
    'One size prop for all styles',
    'Icons before or after content',
    'Themes, animations, and Group support',
    'Style variants, including outlined',
    'Child color, size, and variant through Apply',
  ]}
/>

## Installation

ListItem is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/list-item
```

## Usage

Basic usage involves providing children or using the `title` and `subTitle` props.

```tsx
import { ListItem, Separator, YGroup } from 'tamagui'
import { ChevronRight } from '@tamagui/lucide-icons-2' // Example icon

export default () => (
  <YGroup
    self="center"
    borderWidth={1}
    borderColor="border-color"
    rounded="4"
    width={240}
    size="4"
  >
    <YGroup.Item>
      <ListItem title="Star" icon={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem title="Moon" subTitle="Subtitle for Moon" iconAfter={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem>Custom children content</ListItem>
    </YGroup.Item>
  </YGroup>
)
```

## Sizing

The `size` prop adjusts various properties of the ListItem, including padding, minimum height, and the default size for text elements within it. It accepts theme size tokens (e.g., `"3"`, `"4"`).

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem size="5" title="Large List Item" />
```

## Title and SubTitle

Use the `title` and `subTitle` props for a structured layout. These props accept `ReactNode`, so you can pass strings or more complex JSX.

- If `title` or `subTitle` is provided, children will be rendered inside the main text area (under title/subtitle).
- `ListItem.Title` and `ListItem.Subtitle` components are used internally and can be targeted for styling (see Customization).

```tsx
import { ListItem, Avatar } from 'tamagui'
import { User } from '@tamagui/lucide-icons-2'

export default () => (
  <ListItem
    icon={
      <Avatar circular size="3">
        <Avatar.Image src="/placeholder.png" />
        <Avatar.Fallback bc="background-focus" />
      </Avatar>
    }
    title="User Profile"
    subTitle="View and edit your profile details."
    iconAfter={User}
    size="4"
  />
)
```

## Icon Theming

Icons can be passed to `icon` (before content) or `iconAfter` (after content) props.

- **Automatic Sizing & Spacing**: Icons are automatically sized based on the ListItem's `size` prop. You can override this with the `iconSize` prop (accepts `SizeTokens`). Spacing is applied using the frame `gap`, so it applies between all direct ListItem frame children, not only around icons.
- **Scaling**: Use `scaleIcon` (number, default: 1) to further adjust the icon size relative to its base size.
- **Component Props**: If you pass a component as an icon, it will receive `size` (the calculated pixel size) as a prop.

```tsx
import { ListItem } from 'tamagui'
import { Star, Settings } from '@tamagui/lucide-icons-2'

export default () => (
  <>
    <ListItem icon={Star} title="Default Icon Size" size="4" />
    <ListItem
      icon={Settings}
      iconSize="2"
      title="Explicit Icon Size"
      subTitle="iconSize='2'"
      size="5"
    />
    <ListItem
      icon={Star}
      scaleIcon={1.5}
      title="Scaled Icon"
      subTitle="scaleIcon={1.5}"
      size="4"
    />
  </>
)
```

## Variant

ListItem supports a `variant` prop for different visual styles:

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem variant="outlined" title="Outlined Style" />
```

Currently supports `outlined` (transparent background with border).

## Apply (Context)

Use `ListItem.Apply` to pass `color`, `size`, and `variant` to multiple children via context:

```tsx
import { ListItem, YGroup } from 'tamagui'
import { Trash } from '@tamagui/lucide-icons-2'

export default () => (
  <YGroup>
    <ListItem.Apply color="red-10">
      <YGroup.Item>
        <ListItem icon={Trash} title="Delete item" />
      </YGroup.Item>
      <YGroup.Item>
        <ListItem icon={Trash} title="Remove all" />
      </YGroup.Item>
    </ListItem.Apply>
  </YGroup>
)
```

The `color` prop passed to `Apply` will be inherited by icons within children.

## Customization

For customization, Tamagui exports the building blocks: `ListItem.Frame`, `ListItem.Text`, `ListItem.Title`, `ListItem.Subtitle`, and `ListItem.Icon`.

```tsx
import { YStack, ListItem as TamaguiListItem } from 'tamagui'
import { GetProps, styled } from '@tamagui/web'

const CustomFrame = styled(TamaguiListItem.Frame, {
  padding: '5',
  backgroundColor: 'background-hover',
})

const CustomTitle = styled(TamaguiListItem.Title, {
  color: 'red-10',
  fontWeight: 'bold',
})

const CustomSubtitle = styled(TamaguiListItem.Subtitle, {
  color: 'gray-10',
  fontStyle: 'italic',
})

// Recompose, for example, if you need a different internal structure
export const MyAdvancedListItem = ({
  icon,
  title,
  subTitle,
  children,
  ...frameProps
}) => {
  return (
    <CustomFrame {...frameProps}>
      {icon && <TamaguiListItem.Icon>{icon}</TamaguiListItem.Icon>}
      <YStack flex={1} justify="center">
        {title && <CustomTitle>{title}</CustomTitle>}
        {subTitle && <CustomSubtitle>{subTitle}</CustomSubtitle>}
        {children && <TamaguiListItem.Text>{children}</TamaguiListItem.Text>}
      </YStack>
      {/* iconAfter could go here */}
    </CustomFrame>
  )
}
```

## API Reference

### ListItem

ListItems extend View, inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'title',
      required: false,
      type: 'React.ReactNode',
      description: 'Main text content of the list item. Renders using `ListItem.Title`.',
    },
    {
      name: 'subTitle',
      required: false,
      type: 'React.ReactNode',
      description:
        'Secondary text content, rendered below the title. Renders using `ListItem.Subtitle`.',
    },
    {
      name: 'size',
      required: false,
      type: 'SizeTokens',
      description:
        'Adjusts padding, min-height, and default font/icon sizes. Uses theme size tokens (e.g., "3", "4").',
    },
    {
      name: 'color',
      required: false,
      type: 'ColorTokens | string',
      description:
        'Color token or CSS color inherited by `ListItem.Icon` children and icon props.',
    },
    {
      name: 'variant',
      required: false,
      type: "'outlined'",
      description:
        'Visual variant style. Currently supports "outlined" (transparent background with border).',
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element | React.ComponentType<{ size?: number }>',
      description:
        'Icon element or component displayed before the main content. Receives `size` prop if a component.',
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element | React.ComponentType<{ size?: number }>',
      description:
        'Icon element or component displayed after the main content. Receives `size` prop if a component.',
    },
    {
      name: 'iconSize',
      required: false,
      type: 'SizeTokens',
      description:
        'Explicitly set the size of the icon, overriding the default size derived from the ListItem\'s `size` prop. Uses theme size tokens (e.g., "2").',
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description:
        'Scale factor for the icon (default: 1). Applied after `iconSize` or default size calculation.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: 'If true, reduces opacity and disables pointer events.',
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description:
        'Removes all default Tamagui styles (padding, background, etc.). Default is `false` unless `TAMAGUI_HEADLESS` is set.',
    },
    {
      name: '// Styling Text',
      type: '---',
      description:
        'To style the `title`, `subTitle`, or general `children` text, use `styled(ListItem, { ... })` to target nested `ListItem.Title`, `ListItem.Subtitle`, or `ListItem.Text` components, or compose your own with these parts. Direct text styling props are not passed for simplicity and performance.',
    },
  ]}
/>

### ListItem.Apply

A context provider that passes `color`, `size`, and `variant` to all ListItem children.

<PropsTable
  data={[
    {
      name: 'color',
      required: false,
      type: 'ColorTokens | string',
      description: 'Color token to pass to icons in children ListItems.',
    },
    {
      name: 'size',
      required: false,
      type: 'SizeTokens',
      description: 'Size token to apply to children ListItems.',
    },
    {
      name: 'variant',
      required: false,
      type: "'outlined'",
      description: 'Variant to apply to children ListItems.',
    },
  ]}
/>

### ListItem.Frame

The base `View` component for the ListItem.

### ListItem.Text

Used for wrapping `children` when `title` or `subTitle` are not used. Extends `SizableText`.

### ListItem.Title

Used for rendering the `title` prop. Extends `SizableText`.

### ListItem.Subtitle

Used for rendering the `subTitle` prop. Extends `SizableText`. Its font size is automatically set to one step smaller than the ListItem's main `size`.

### ListItem.Icon

A helper component for rendering icons within ListItem, handling size and color.
Typically used internally but can be leveraged in custom compositions.


## components/list-item/3.0.0

---
title: ListItem
description: Display rows with titles, subtitles, and icons
name: list-item
component: ListItem
package: list-item
demoName: ListItem
---

<IntroParagraph>
  ListItem builds consistent rows from titles, subtitles, icons, images, and
  shared size or theme variants.
</IntroParagraph>

<HeroContainer>
  <ListItemDemo />
</HeroContainer>

```tsx hero template=ListItem

```

<Highlights
  features={[
    'One size prop for all styles',
    'Icons before or after content',
    'Themes, animations, and Group support',
    'Style variants, including outlined',
    'Child color, size, and variant through Apply',
  ]}
/>

## Installation

ListItem is already installed in `tamagui`:

```tsx
import { ListItem } from 'tamagui'
```

`@tamagui/list-item` holds the unstyled half: `useListItem` and the parts, with no
styled `ListItem` of its own. Import from it when you are building your own
list item rather than using ours; see [Build your own](#build-your-own).

## Usage

Basic usage involves providing children or using the `title` and `subTitle` props.

```tsx
import { ListItem, Separator, YGroup } from 'tamagui'
import { ChevronRight } from './components/icons' // Example icon (generate your own, see Lucide Icons)

export default () => (
  <YGroup
    self="center"
    borderWidth={1}
    borderColor="border-color"
    rounded="4"
    width={240}
    size="md"
  >
    <YGroup.Item>
      <ListItem title="Star" icon={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem title="Moon" subTitle="Subtitle for Moon" iconAfter={ChevronRight} />
    </YGroup.Item>
    <YGroup.Item>
      <ListItem>Custom children content</ListItem>
    </YGroup.Item>
  </YGroup>
)
```

## Sizing

The `size` prop adjusts padding, minimum height, and the default size for the text
and icons inside. It accepts theme size tokens (e.g., `"3"`, `"4"`).

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem size="lg" title="Large List Item" />
```

## Title and subTitle

Use the `title` and `subTitle` props for a structured layout. These props accept
`ReactNode`, so you can pass strings or more complex JSX.

- If `title` or `subTitle` is provided, children render inside the main text area,
  under the title and subtitle.
- Strings render through `ListItem.Title` and `ListItem.Subtitle`. Anything else
  renders as you passed it, so you can style it yourself.

```tsx
import { ListItem, Avatar } from 'tamagui'
import { User } from './components/icons'

export default () => (
  <ListItem
    icon={
      <Avatar circular size="sm">
        <Avatar.Image src="/placeholder.png" />
        <Avatar.Fallback backgroundColor="background-focus" />
      </Avatar>
    }
    title="User Profile"
    subTitle="View and edit your profile details."
    iconAfter={User}
    size="md"
  />
)
```

## Icon theming

Icons can be passed to `icon` (before content) or `iconAfter` (after content).

- **Automatic sizing and spacing**: icons are sized from the ListItem's `size`.
  Override with `iconSize`. Spacing comes from the frame `gap`, so it applies
  between all direct frame children, not only around icons.
- **Scaling**: `scaleIcon` (number, default `1`) adjusts the icon size relative to
  its base size.
- **Component props**: a component passed as an icon receives `size` (the
  calculated pixel size) and `color`.

```tsx
import { ListItem } from 'tamagui'
import { Star, Settings } from './components/icons'

export default () => (
  <>
    <ListItem icon={Star} title="Default Icon Size" size="md" />
    <ListItem
      icon={Settings}
      iconSize="2"
      title="Explicit Icon Size"
      subTitle="iconSize='2'"
      size="lg"
    />
    <ListItem
      icon={Star}
      scaleIcon={1.5}
      title="Scaled Icon"
      subTitle="scaleIcon={1.5}"
      size="md"
    />
  </>
)
```

## Variant

ListItem supports a `variant` prop for different visual styles:

```tsx
import { ListItem } from 'tamagui'

export default () => <ListItem variant="outlined" title="Outlined Style" />
```

Currently supports `outlined` (transparent background with border).

## Apply (context)

`ListItem.Apply` is the styled context every part reads. Use it to pass `color`,
`size`, and `variant` to a group of list items at once:

```tsx
import { ListItem, YGroup } from 'tamagui'
import { Trash } from './components/icons'

export default () => (
  <YGroup>
    <ListItem.Apply color="red-600">
      <YGroup.Item>
        <ListItem icon={Trash} title="Delete item" />
      </YGroup.Item>
      <YGroup.Item>
        <ListItem icon={Trash} title="Remove all" />
      </YGroup.Item>
    </ListItem.Apply>
  </YGroup>
)
```

A `ListItem` republishes whichever of these it was passed directly, so its own
icons and text pick them up without any wiring.

## Build your own

`@tamagui/list-item` exports the behavior and the parts separately, so you can put
your own skin on them. `useListItem` themes the icon props and assembles title,
subtitle, and children into the frame's child; everything else is yours. This is
exactly how `tamagui`'s own ListItem is built:

```tsx
import {
  createStyledHOC,
  ListItemContext,
  ListItemFrame as ListItemBehaviorFrame,
  type ListItemIconProps,
  ListItemSubtitle,
  ListItemText,
  ListItemTitle,
  styled,
  useListItem,
  withStaticProperties,
} from '@tamagui/ui'
import { useGetThemedIcon } from '@tamagui/helpers-tamagui'

const ListItemFrame = styled(ListItemBehaviorFrame, {
  context: ListItemContext,
  backgroundColor: 'background hover:background-hover',
  borderColor: 'border-color',
  color: 'color',
})

// the icon px is yours to decide; the behavior package only publishes color
const ListItemIcon = ({ children, size = 16 }: ListItemIconProps) => {
  const { color } = ListItemContext.useStyledContext()
  return useGetThemedIcon({ size, color })(children)
}

const ListItemComponent = createStyledHOC(ListItemFrame, function ListItem(props, ref) {
  const { props: listItemProps } = useListItem(props)
  return <ListItemFrame ref={ref} {...listItemProps} />
})

export const ListItem = withStaticProperties(ListItemComponent, {
  Apply: ListItemContext.Provider,
  Frame: ListItemFrame,
  Icon: ListItemIcon,
  Subtitle: ListItemSubtitle,
  Text: ListItemText,
  Title: ListItemTitle,
})
```

Because the frame declares `ListItemContext`, passing `size`, `color`, or
`variant` to it is what publishes them to the text and icons below. There is no
context to assemble by hand.

## API reference

### ListItem

ListItem extends View, inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'title',
      required: false,
      type: 'React.ReactNode',
      description:
        'Main text content of the list item. A string renders through `ListItem.Title`.',
    },
    {
      name: 'subTitle',
      required: false,
      type: 'React.ReactNode',
      description:
        'Secondary text content, rendered below the title. A string renders through `ListItem.Subtitle`.',
    },
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description:
        'A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: padding, font size, and icon size. Published to the parts through the ListItem context. Subtitles render one step below the title.',
    },
    {
      name: 'color',
      required: false,
      type: 'ColorTokens | string',
      description:
        'Color token or CSS color inherited by `ListItem.Icon` children and the icon props.',
    },
    {
      name: 'variant',
      required: false,
      type: "'outlined'",
      description:
        'Visual variant style. Currently supports "outlined" (transparent background with border).',
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element | React.ComponentType<{ size?: number; color?: any }>',
      description:
        'Icon element or component displayed before the main content. Receives `size` and `color` if a component.',
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element | React.ComponentType<{ size?: number; color?: any }>',
      description:
        'Icon element or component displayed after the main content. Receives `size` and `color` if a component.',
    },
    {
      name: 'iconSize',
      required: false,
      type: 'number | string',
      description:
        'Explicitly set the icon size, either in pixels or as a sizing-ladder name, overriding the one derived from `size`.',
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description:
        'Scale factor for the icon (default: 1). Applied after `iconSize` or the default size calculation.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description: 'If true, reduces opacity and disables pointer events.',
    },
    {
      name: '// Styling Text',
      type: '---',
      description:
        'Text style props are not forwarded from the frame. Style `ListItem.Title`, `ListItem.Subtitle`, or `ListItem.Text` directly, or pass JSX to `title` and `subTitle`.',
    },
  ]}
/>

### ListItem.Apply

The styled context provider. Passes `color`, `size`, and `variant` to every
ListItem and ListItem part beneath it.

<PropsTable
  data={[
    {
      name: 'color',
      required: false,
      type: 'ColorTokens | string',
      description: 'Color token to pass to icons in children ListItems.',
    },
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: 'Named size to apply to children ListItems.',
    },
    {
      name: 'variant',
      required: false,
      type: "'outlined'",
      description: 'Variant to apply to children ListItems.',
    },
  ]}
/>

### ListItem.Frame

The base `View` for the ListItem. Renders as `li` on web with
`role="listitem"`.

### ListItem.Text

Wraps `children` when `title` and `subTitle` are not used. Extends `SizableText`.

### ListItem.Title

Renders a string `title`. Extends `SizableText`.

### ListItem.Subtitle

Renders a string `subTitle`. Extends `SizableText`. Its font size is one step
smaller than the ListItem's `size`.

### ListItem.Icon

Sizes and colors an icon from the surrounding ListItem context.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | number",
      description: 'Overrides the size taken from context.',
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: 'Scale factor applied to the resolved size (default: 1).',
    },
  ]}
/>

### useListItem

Themes the `icon` and `iconAfter` props and assembles `title`, `subTitle`, and
`children` into a single child. Returns the props to spread onto a frame, with the
ones it consumed removed and everything else untouched.

```tsx
const { props } = useListItem(props)
```


## components/new-inputs/1.0.0

---
title: Input & Textarea
name: inputs
component: Input
demoName: Inputs
---

<HeroContainer demoMultiple>
  <NewInputsDemo />
</HeroContainer>

```tsx hero template=Inputs

```

Using Web APIs and relying on bare Tamagui with no `react-native-web` depedency on web compared to old Input component, support scaling all the styles up or down using the `size` property, and full `theme` support.

## Installation

LinearGradient is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/input
```

## Input

A one-line input field:

```tsx
import { Input } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <Input gap="4" borderWidth={2} />
)
```

## TextArea

For multi-line inputs:

```tsx
import { TextArea } from 'tamagui'

export const App = () => (
  // Accepts size and style properties directly
  <TextArea gap="4" borderWidth={2} />
)
```


## components/new-inputs/2.0.0

---
title: Input & TextArea
description: Single-line and multi-line text inputs with web-first API
name: inputs
component: Input
package: input
demoName: Inputs
---

<IntroParagraph>
  Input and TextArea use web-standard form APIs and translate them to React
  Native behavior on iOS and Android.
</IntroParagraph>

<HeroContainer demoMultiple>
  <NewInputsDemo />
</HeroContainer>

```tsx hero template=Inputs

```

## Installation

Input is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/input
```

## Usage

A single-line text input:

```tsx
import { Input } from 'tamagui'

export default () => <Input placeholder="Enter text..." size="md" />
```

For multi-line text input, use `TextArea`:

```tsx
import { TextArea } from 'tamagui'

export default () => <TextArea placeholder="Enter long text..." rows={4} />
```

## Web-first API

The v2 Input uses standard HTML input attributes.

### Input types

Use the standard HTML `type` attribute. On native, these automatically map to the appropriate keyboard and behavior:

```tsx
// Password input
<Input type="password" />

// Email input (shows email keyboard on native)
<Input type="email" />

// Phone number (shows phone pad on native)
<Input type="tel" />

// Number input (shows numeric keyboard on native)
<Input type="number" />

// URL input
<Input type="url" />

// Search input
<Input type="search" />
```

**Cross-platform mapping:**

| Web `type` | Native behavior                |
| ---------- | ------------------------------ |
| `password` | `secureTextEntry={true}`       |
| `email`    | `keyboardType="email-address"` |
| `tel`      | `keyboardType="phone-pad"`     |
| `number`   | `keyboardType="numeric"`       |
| `url`      | `keyboardType="url"`           |
| `search`   | `inputMode="search"`           |

### Enter key behavior

Use `enterKeyHint` to control the enter/return key label on virtual keyboards:

```tsx
<Input enterKeyHint="search" />
<Input enterKeyHint="send" />
<Input enterKeyHint="done" />
<Input enterKeyHint="go" />
<Input enterKeyHint="next" />
```

On native, this automatically maps to `returnKeyType`.

### Form attributes

Standard HTML form attributes work:

```tsx
<Input
  name="email"
  placeholder="Enter email"
  required
  maxLength={100}
  minLength={3}
  pattern="[a-z@.]+"
  autoComplete="email"
  autoFocus
  readOnly={false}
  disabled={false}
/>
```

### Events

Use standard web events:

```tsx
<Input
  onChange={(e) => console.log(e.target.value)}
  onFocus={(e) => console.log('focused')}
  onBlur={(e) => console.log('blurred')}
  onKeyDown={(e) => {
    if (e.key === 'Enter') {
      // handle enter
    }
  }}
/>
```

For convenience, `onChangeText` is still supported but deprecated:

```tsx
// Deprecated - use onChange instead
<Input onChangeText={(text) => setText(text)} />

// Preferred
<Input onChange={(e) => setText(e.target.value)} />
```

### Submit handling

To handle form submission on enter:

```tsx
<Input
  onSubmitEditing={(e) => {
    console.log('Submitted:', e.nativeEvent.text)
  }}
/>
```

## Styling

Input accepts all Tamagui style props and supports the `size` prop for consistent scaling:

```tsx
<Input
  size="md"
  borderWidth={2}
  borderColor="border-color hover:border-color-hover focus:border-color-focus"
  borderRadius="4"
  backgroundColor="background"
  color="color"
  placeholderTextColor="placeholder-color"
  selectionColor="accent-color"
/>
```

## Native-only props

Some props only apply on native platforms and have no web equivalent:

**keyboardAppearance (iOS)**: Controls the keyboard color scheme on iOS:

```tsx
<Input keyboardAppearance="dark" />
<Input keyboardAppearance="light" />
<Input keyboardAppearance="default" />
```

**textContentType (iOS)**: Provides hints for iOS autofill:

```tsx
<Input textContentType="emailAddress" />
<Input textContentType="password" />
<Input textContentType="newPassword" />
<Input textContentType="oneTimeCode" />
<Input textContentType="telephoneNumber" />
<Input textContentType="username" />
```

For web autofill, use the standard `autoComplete` attribute instead.

## Cross-platform text behavior

These props work on both web and native with automatic value conversion:

### autoCorrect

Controls automatic spelling correction:

```tsx
// Boolean values (work everywhere)
<Input autoCorrect={false} />
<Input autoCorrect={true} />

// String values (web-style, converted on native)
<Input autoCorrect="off" />
<Input autoCorrect="on" />
```

### autoCapitalize

Controls automatic text capitalization. Native values provide more granular control:

```tsx
// Native-style values (recommended - work everywhere)
<Input autoCapitalize="none" />        // No capitalization
<Input autoCapitalize="sentences" />   // Capitalize first letter of sentences
<Input autoCapitalize="words" />       // Capitalize first letter of each word
<Input autoCapitalize="characters" />  // Capitalize all characters

// Web-style values (mapped on native)
<Input autoCapitalize="off" />  // Maps to "none" on native
<Input autoCapitalize="on" />   // Maps to "sentences" on native
```

## Migration from v1

If you're migrating from v1 Input, here are the key changes:

| v1 (React Native style)        | v2 (Web style)               |
| ------------------------------ | ---------------------------- |
| `secureTextEntry`              | `type="password"`            |
| `keyboardType="email-address"` | `type="email"`               |
| `keyboardType="phone-pad"`     | `type="tel"`                 |
| `keyboardType="numeric"`       | `type="number"`              |
| `keyboardType="url"`           | `type="url"`                 |
| `returnKeyType="search"`       | `enterKeyHint="search"`      |
| `editable={false}`             | `readOnly` or `disabled`     |
| `onChangeText`                 | `onChange`                   |
| `multiline`                    | Use `TextArea` or `rows > 1` |
| `numberOfLines`                | `rows`                       |

The v1 props still work but are deprecated. We recommend updating to the web-standard props for better cross-platform consistency.

## API reference

### Input props

Accepts all HTML `<input>` attributes plus Tamagui style props.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | SizeTokens",
      description: 'Scale the input size consistently.',
    },
    {
      name: 'type',
      required: false,
      type: '"text" | "password" | "email" | "tel" | "number" | "url" | "search"',
      description: 'HTML input type. Automatically maps to native keyboard types.',
    },
    {
      name: 'enterKeyHint',
      required: false,
      type: '"enter" | "done" | "go" | "next" | "previous" | "search" | "send"',
      description: 'Hint for the enter key label. Maps to returnKeyType on native.',
    },
    {
      name: 'placeholderTextColor',
      required: false,
      type: 'ColorTokens',
      description: 'Color of placeholder text. Accepts Tamagui color tokens.',
    },
    {
      name: 'selectionColor',
      required: false,
      type: 'ColorTokens',
      description: 'Color of text selection. Accepts Tamagui color tokens.',
    },
    {
      name: 'onSubmitEditing',
      required: false,
      type: '(e: { nativeEvent: { text: string } }) => void',
      description: 'Called when enter/return is pressed.',
    },
    {
      name: 'keyboardAppearance',
      required: false,
      type: '"default" | "light" | "dark"',
      description: 'iOS only. Controls keyboard color scheme.',
    },
    {
      name: 'textContentType',
      required: false,
      type: 'string',
      description: 'iOS only. Hints for autofill. Use autoComplete for web.',
    },
  ]}
/>

### TextArea props

Accepts all Input props plus:

<PropsTable
  data={[
    {
      name: 'rows',
      required: false,
      type: 'number',
      description: 'Number of visible text lines.',
    },
  ]}
/>


## components/popover/1.43.0

---
title: Popover
description: A simple popover component
name: popover
component: Popover
package: popover
demoName: Popover
---

# Popover

<Description>Show content with a trigger in a floating pane</Description>

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.

<Notice>
  Support for native was contributed by a community member, but not guaranteed to work
  until we get time to fully test. We don't recommend the Popover pattern for phone-sized
  devices, and you can adapt it to a Sheet instead.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

## Anatomy

```tsx
import { Popover } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      {/* ScrollView is optional, can just put any contents inside if not scrollable */}
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
      {/* ... */}
    </Popover.Content>

    {/* optionally change to sheet when small screen */}
    <Popover.Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Popover.Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Popover.Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
  ]}
/>

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack, see [Stacks](/docs/components/stacks).

### Popover.Content

Renders as SizableStack which is just a YStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the contents given to `Popover.Content`

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove this ScrollView when swapping into the Sheet, as the Sheet must use it's own ScrollView that handles special logic for interactions with dragging.


## components/popover/1.0.0

---
title: Popover
description: A simple popover component
name: popover
component: Popover
package: popover
demoName: Popover
---

# Popover

<Description>Show content with a trigger in a floating pane.</Description>

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.

<Notice>
  Support for native was contributed by a community member, but not guaranteed to work
  until we get time to fully test and improve native interactions. We don't recommend the
  Popover pattern for phone-sized devices either way, and instead you can adapt it to a
  Sheet.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

## Anatomy

```tsx
import { Popover } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      {/* ScrollView is optional, can just put any contents inside if not scrollable */}
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
      {/* ... */}
    </Popover.Content>

    {/* optionally change to sheet when small screen */}
    <Popover.Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Popover.Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Popover.Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack, see [Stacks](/docs/components/stacks).

### Popover.Content

Renders as SizableStack which is just a YStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

Used to display the content of the popover.

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the contents given to `Popover.Content`

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove this ScrollView when swapping into the Sheet, as the Sheet must use it's own ScrollView that handles special logic for interactions with dragging.


## components/popover/1.83.0

---
title: Popover
description: A simple popover component
name: popover
component: Popover
package: popover
demoName: Popover
---

# Popover

<Description>Show content with a trigger in a floating pane</Description>

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      {/* ScrollView is optional, can just put any contents inside if not scrollable */}
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
      {/* ... */}
    </Popover.Content>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      required: false,
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/popover/1.83.0#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element. In order for the Arrow to show you must have a Trigger element within your Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack, see [Stacks](/docs/components/stacks).

### Popover.Content

Renders as SizableStack which is just a YStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the contents given to `Popover.Content`

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove this ScrollView when swapping into the Sheet, as the Sheet must use it's own ScrollView that handles special logic for interactions with dragging.


## components/popover/1.129.0

---
title: Popover
description: Show content with a trigger in a floating pane.
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is
pressed, floating above the current content.

<Notice>
  Note: Popovers are not a recommended pattern for mobile apps, and so aren't supported on
  native. Instead you can use Adapt and render them as a Sheet, or just conditionally
  render them. We landed support for them at one point, but we need the community to
  contribute tests in order to support them for mobile again.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install
the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    {/* Optional: Control focus behavior */}
    <Popover.FocusScope loop trapped focusOnIdle={true}>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Close />
        {/* ScrollView is optional, can just put any contents inside if not scrollable */}
        <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
        {/* ... */}
      </Popover.Content>
    </Popover.FocusScope>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean | "lazy"',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render. The "lazy" value will only initially mount the children after a React startTransition, and then keep them mounted thereafter.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
  ]}
/>

For most of these properties, you'll want to reference the
[floating-ui docs](https://floating-ui.com/docs/getting-started).

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/popover/1.83.0#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element.
In order for the Arrow to show you must have a Trigger element within your
Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack,
see [Stacks](/docs/components/stacks).

### Popover.Content

Extends PopperContent which extends SizableStack which extends a YStack (see
[Stacks](/docs/components/stacks)).

Also extends

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'enableAnimationForPositionChange',
      type: 'boolean',
      description:
        'Disabled animate presence animations in favor of regular animation, useful for doing sliding popovers.',
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: 'Controls default padding/borderRadius when unstyled is false.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      default: false,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'trapFocus',
      type: 'boolean',
      default: false,
      description: 'Whether focus should be trapped within the `Popover`',
    },
    {
      name: 'disableFocusScope',
      type: 'boolean',
      default: false,
      description: 'Whether popover should not focus contents on open',
    },
    {
      name: 'onOpenAutoFocus',
      type: `FocusScopeProps['onMountAutoFocus']`,
      default: false,
      description: 'Event handler called when auto-focusing on open. Can be prevented.',
    },
    {
      name: 'onCloseAutoFocus',
      type: `FocusScopeProps['onUnmountAutoFocus'] | false`,
      default: false,
      description: 'Event handler called when auto-focusing on close. Can be prevented.',
    },
    {
      name: 'lazyMount',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover
attaches, use Anchor. When used, Anchor is where the Popover will attach, while
Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is
active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the
contents given to `Popover.Content`

### Popover.FocusScope

Provides access to the underlying FocusScope component used by Popover for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use it's own
ScrollView that handles special logic for interactions with dragging.


## components/popover/1.128.0

---
title: Popover
description: Show content with a trigger in a floating pane.
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is
pressed, floating above the current content.

<Notice>
  Note: Popovers are not a recommended pattern for mobile apps, and so aren't supported on
  native. Instead you can use Adapt and render them as a Sheet, or just conditionally
  render them. We landed support for them at one point, but we need the community to
  contribute tests in order to support them for mobile again.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install
the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    {/* Optional: Control focus behavior */}
    <Popover.FocusScope loop trapped focusOnIdle={true}>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Close />
        {/* ScrollView is optional, can just put any contents inside if not scrollable */}
        <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
        {/* ... */}
      </Popover.Content>
    </Popover.FocusScope>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
  ]}
/>

For most of these properties, you'll want to reference the
[floating-ui docs](https://floating-ui.com/docs/getting-started).

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/popover/1.83.0#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element.
In order for the Arrow to show you must have a Trigger element within your
Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack,
see [Stacks](/docs/components/stacks).

### Popover.Content

Extends PopperContent which extends SizableStack which extends a YStack (see
[Stacks](/docs/components/stacks)).

Also extends

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'enableAnimationForPositionChange',
      type: 'boolean',
      description:
        'Disabled animate presence animations in favor of regular animation, useful for doing sliding popovers.',
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: 'Controls default padding/borderRadius when unstyled is false.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      default: false,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'trapFocus',
      type: 'boolean',
      default: false,
      description: 'Whether focus should be trapped within the `Popover`',
    },
    {
      name: 'disableFocusScope',
      type: 'boolean',
      default: false,
      description: 'Whether popover should not focus contents on open',
    },
    {
      name: 'onOpenAutoFocus',
      type: `FocusScopeProps['onMountAutoFocus']`,
      default: false,
      description: 'Event handler called when auto-focusing on open. Can be prevented.',
    },
    {
      name: 'onCloseAutoFocus',
      type: `FocusScopeProps['onUnmountAutoFocus'] | false`,
      default: false,
      description: 'Event handler called when auto-focusing on close. Can be prevented.',
    },
    {
      name: 'lazyMount',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover
attaches, use Anchor. When used, Anchor is where the Popover will attach, while
Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is
active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the
contents given to `Popover.Content`

### Popover.FocusScope

Provides access to the underlying FocusScope component used by Popover for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use it's own
ScrollView that handles special logic for interactions with dragging.


## components/popover/1.131.0

---
title: Popover
description: Show content with a trigger in a floating pane.
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is
pressed, floating above the current content. Be sure to open the code example
above for a copy-paste implementation.

<Notice>
  Note: Popovers are not a recommended pattern for mobile apps. Instead you can use Adapt
  and render them as a Sheet, or just conditionally render them to some native UI.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

_Only_ if you are not using `tamagui` and installing popover independently -
you'll need to set up the portal for it with the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    {/* Optional: Control focus behavior */}
    <Popover.FocusScope loop trapped focusOnIdle={true}>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Close />
        {/* ScrollView is optional, can just put any contents inside if not scrollable */}
        <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
        {/* ... */}
      </Popover.Content>
    </Popover.FocusScope>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## Scoping

Popover supports scoping which lets you mount one or more Popover instances at
the root of your app, while having a deeply nested child Trigger or Content
attach to the proper parent Popover instance.

In performance sensitive areas you may want to take advantage of this as it allows
you to only render the Popover.Trigger inside the sensitive area.
Popover isn't the cheapest component - it has a lot of functionality
inside of it like scroll management, focus management, and tracking position.

Here's the basic anatomy of using `scope` and placing your Popover higher up
for performance:

```tsx fileName=_layout.tsx
import { Popover } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Popover scope="user-avatar">
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
    </Popover.Content>

    {/* the rest of your app, note that it's inside of Popover */}
    {children}
  </Popover>
)
```

```tsx fileName=UserAvatar.tsx
export default () => (
  <Popover.Trigger scope="user-avatar">
    <Avatar />
  </Popover.Trigger>
)
```

Note that the `Trigger` scope ties to the `Popover` scope.

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean | "lazy"',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render. The "lazy" value will only initially mount the children after a React startTransition, and then keep them mounted thereafter.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
  ]}
/>

For most of these properties, you'll want to reference the
[floating-ui docs](https://floating-ui.com/docs/getting-started).

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element.
In order for the Arrow to show you must have a Trigger element within your
Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack,
see [Stacks](/docs/components/stacks).

### Popover.Content

Extends PopperContent which extends SizableStack which extends a YStack (see
[Stacks](/docs/components/stacks)).

Also extends

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'enableAnimationForPositionChange',
      type: 'boolean',
      description:
        'Disabled animate presence animations in favor of regular animation, useful for doing sliding popovers.',
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: 'Controls default padding/borderRadius when unstyled is false.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      default: false,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'trapFocus',
      type: 'boolean',
      default: false,
      description: 'Whether focus should be trapped within the `Popover`',
    },
    {
      name: 'disableFocusScope',
      type: 'boolean',
      default: false,
      description: 'Whether popover should not focus contents on open',
    },
    {
      name: 'onOpenAutoFocus',
      type: `FocusScopeProps['onMountAutoFocus']`,
      default: false,
      description: 'Event handler called when auto-focusing on open. Can be prevented.',
    },
    {
      name: 'onCloseAutoFocus',
      type: `FocusScopeProps['onUnmountAutoFocus'] | false`,
      default: false,
      description: 'Event handler called when auto-focusing on close. Can be prevented.',
    },
    {
      name: 'lazyMount',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover
attaches, use Anchor. When used, Anchor is where the Popover will attach, while
Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is
active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the
contents given to `Popover.Content`

### Popover.FocusScope

Provides access to the underlying FocusScope component used by Popover for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use its own
ScrollView that handles special logic for interactions with dragging.


## components/popover/1.125.0

---
title: Popover
description: Show content with a trigger in a floating pane.
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.

<Notice>
  Note: Popovers are not a recommended pattern for mobile apps, and so aren't supported on
  native. Instead you can use Adapt and render them as a Sheet, or just conditionally
  render them. We landed support for them at one point, but we need the community to
  contribute tests in order to support them for mobile again.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      {/* ScrollView is optional, can just put any contents inside if not scrollable */}
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
      {/* ... */}
    </Popover.Content>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
  ]}
/>

For most of these properties, you'll want to reference the [floating-ui docs](https://floating-ui.com/docs/getting-started).

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/popover/1.83.0#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element. In order for the Arrow to show you must have a Trigger element within your Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack, see [Stacks](/docs/components/stacks).

### Popover.Content

Renders as SizableStack which is just a YStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the contents given to `Popover.Content`

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove this ScrollView when swapping into the Sheet, as the Sheet must use it's own ScrollView that handles special logic for interactions with dragging.


## components/popover/2.0.0

---
title: Popover
description: Show content with a trigger in a floating pane
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is
pressed, floating above the current content. They [automatically stack](/ui/z-index) above other content. Be sure to open the code example above for a copy-paste implementation.

<Notice>
  Note: Popovers are not a recommended pattern for mobile apps. Instead you can use Adapt
  and render them as a Sheet, or just conditionally render them to some native UI.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/docs/components/portal#native-portal-setup-recommended) to preserve React
  context inside Popover content.
</Notice>

## Anatomy

```tsx
import { Popover, Adapt, Sheet } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    {/* Optional: Control focus behavior */}
    <Popover.FocusScope loop trapped focusOnIdle={true}>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Close />
        {/* ScrollView is optional, can just put any contents inside if not scrollable */}
        <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
        {/* ... */}
      </Popover.Content>
    </Popover.FocusScope>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="max-md">
      <Sheet>
        <Sheet.Overlay />
        <Sheet.Frame>
          <Sheet.ScrollView>
            <Adapt.Contents />
          </Sheet.ScrollView>
        </Sheet.Frame>
      </Sheet>
    </Adapt>
  </Popover>
)
```

## Scoping

Popover supports scoping which lets you mount one or more Popover instances at
the root of your app, while having a deeply nested child Trigger or Content
attach to the proper parent Popover instance.

In performance sensitive areas you may want to take advantage of this as it allows
you to only render the Popover.Trigger inside the sensitive area.
Popover isn't the cheapest component - it has a lot of functionality
inside of it like scroll management, focus management, and tracking position.

Here's the basic anatomy of using `scope` and placing your Popover higher up
for performance:

```tsx fileName=_layout.tsx
import { Popover } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Popover scope="user-avatar">
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
    </Popover.Content>

    {/* the rest of your app, note that it's inside of Popover */}
    {children}
  </Popover>
)
```

```tsx fileName=UserAvatar.tsx
export default () => (
  <Popover.Trigger scope="user-avatar">
    <Avatar />
  </Popover.Trigger>
)
```

Note that the `Trigger` scope ties to the `Popover` scope.

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `Controlled open state of the popover.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `Initial open state when uncontrolled.`,
    },
    {
      name: 'onOpenChange',
      type: `(open: boolean, via?: 'hover' | 'press') => void`,
      required: false,
      description: `Called when the popover opens or closes. The optional second argument indicates how it was triggered - 'hover' for hover events (when using the hoverable prop) or 'press' for click/press events.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean | "lazy"',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render. The "lazy" value will only initially mount the children after a React startTransition, and then keep them mounted thereafter.`,
    },
    {
      name: 'disableDismissable',
      type: 'boolean',
      required: false,
      description: `Disables the dismissable layer (escape key, outside click handling). Useful when using keepChildrenMounted for popovers that stay mounted but are visually hidden - set this to true when the popover is hidden to prevent it from capturing escape key presses.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: `Shifts the popover horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
    {
      name: 'zIndex',
      type: 'number',
      required: false,
      description: `Override the automatic z-index stacking. By default, Tamagui automatically stacks overlays so later-opened content appears above earlier content. Only set this if you need to override the automatic behavior.`,
    },
  ]}
/>

For most of these properties, you'll want to reference the
[floating-ui docs](https://floating-ui.com/docs/getting-started).

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element.
In order for the Arrow to show you must have a Trigger element within your
Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

<PropsTable
  data={[
    {
      name: 'animatePosition',
      type: 'boolean',
      description: 'Enable smooth animation when the arrow position changes.',
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: 'Size of the arrow.',
    },
    {
      name: 'offset',
      type: 'number',
      description: 'Offset from the content edge.',
    },
  ]}
/>

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack,
see [Stacks](/docs/components/stacks).

### Popover.Content

Extends PopperContent which extends SizableStack which extends a YStack (see
[Stacks](/docs/components/stacks)). Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'animatePosition',
      type: "boolean | 'even-when-repositioning'",
      description:
        'Enable smooth animation when the content position changes (e.g., when flipping sides).',
    },
    {
      name: 'transformOrigin',
      type: 'boolean',
      default: 'true',
      description:
        'Automatically sets CSS transform-origin based on placement and arrow position. Updates when the popover flips. Enables natural scale animations that grow from the arrow point.',
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: 'Controls default padding/borderRadius when unstyled is false.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      default: false,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'trapFocus',
      type: 'boolean',
      default: false,
      description: 'Whether focus should be trapped within the `Popover`',
    },
    {
      name: 'disableFocusScope',
      type: 'boolean',
      default: false,
      description: 'Whether popover should not focus contents on open',
    },
    {
      name: 'onOpenAutoFocus',
      type: `FocusScopeProps['onMountAutoFocus']`,
      default: false,
      description: 'Event handler called when auto-focusing on open. Can be prevented.',
    },
    {
      name: 'onCloseAutoFocus',
      type: `FocusScopeProps['onUnmountAutoFocus'] | false`,
      default: false,
      description: 'Event handler called when auto-focusing on close. Can be prevented.',
    },
    {
      name: 'lazyMount',
      required: false,
      type: `boolean`,
      description: `Delays mounting content until first open.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover
attaches, use Anchor. When used, Anchor is where the Popover will attach, while
Trigger will open it.

### Sheet (with Adapt)

When used with `Adapt`, you can render a Sheet when that breakpoint is
active. Import `Sheet` directly from `tamagui` or `@tamagui/sheet`.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Sheet.Frame` to insert the
contents given to `Popover.Content`

### Popover.FocusScope

Provides access to the underlying FocusScope component used by Popover for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use its own
ScrollView that handles special logic for interactions with dragging.

## Utility Functions

These functions allow you to programmatically manage open popovers.

```tsx
import {
  closeOpenPopovers,
  closeLastOpenedPopover,
  hasOpenPopovers,
} from '@tamagui/popover'
```

### closeOpenPopovers

Closes all currently open popovers. Returns `true` if any popovers were closed, `false` if none were open.

```tsx
const didClose = closeOpenPopovers()
```

### closeLastOpenedPopover

Closes only the most recently opened popover. Returns `true` if a popover was closed, `false` if none were open.

```tsx
const didClose = closeLastOpenedPopover()
```

### hasOpenPopovers

Returns `true` if there are any open popovers, `false` otherwise.

```tsx
if (hasOpenPopovers()) {
  // handle open popovers
}
```


## components/popover/3.0.0

---
title: Popover
description: Show content with a trigger in a floating pane
name: popover
component: Popover
package: popover
demoName: Popover
---

<IntroParagraph>
  Popover positions focused content around a trigger and can adapt the same
  content into a Sheet on smaller screens.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
    `Shared Sheet handoff with Dialog and Select`,
  ]}
/>

Popover shows content only while its trigger is pressed, floating above the
current content. It [automatically stacks](/ui/z-index) above other content.

<Notice>
  Popovers are not a recommended pattern for mobile apps. Use Adapt to render
  them as a Sheet instead, or conditionally render native UI.
</Notice>

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/ui/portal#native-portal-setup-recommended) to preserve React
  context inside Popover content.
</Notice>

## Anatomy

```tsx
import { Popover, Adapt, Sheet } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    {/* Optional: Control focus behavior */}
    <Popover.FocusScope loop trapped focusOnIdle={true}>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Close />
        {/* ScrollView is optional, can just put any contents inside if not scrollable */}
        <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
        {/* ... */}
      </Popover.Content>
    </Popover.FocusScope>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="max-md">
      <Sheet>
        <Sheet.Overlay />
        <Sheet.Container>
          <Sheet.Background />
          <Sheet.ScrollView>
            <Adapt.Contents />
          </Sheet.ScrollView>
        </Sheet.Container>
      </Sheet>
    </Adapt>
  </Popover>
)
```

## Scoping

Popover supports scoping which lets you mount one or more Popover instances at
the root of your app, while having a deeply nested child Trigger or Content
attach to the proper parent Popover instance.

In performance sensitive areas you may want to take advantage of this as it allows
you to only render the Popover.Trigger inside the sensitive area.
Popover isn't the cheapest component - it has a lot of functionality
inside of it like scroll management, focus management, and tracking position.

Here's the basic anatomy of using `scope` and placing your Popover higher up
for performance:

```tsx fileName=_layout.tsx
import { Popover } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Popover scope="user-avatar">
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
    </Popover.Content>

    {/* the rest of your app, note that it's inside of Popover */}
    {children}
  </Popover>
)
```

```tsx fileName=UserAvatar.tsx
export default () => (
  <Popover.Trigger scope="user-avatar">
    <Avatar />
  </Popover.Trigger>
)
```

Note that the `Trigger` scope ties to the `Popover` scope.

## API reference

In v3, Popover uses the same Adapt handoff path as Dialog. Adapted content stays
mounted through the sheet exit animation and unmounts after the sheet reports
that it is fully hidden.

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: `Controlled open state of the popover.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
      description: `Initial open state when uncontrolled.`,
    },
    {
      name: 'onOpenChange',
      type: `(open: boolean, via?: 'hover' | 'press') => void`,
      required: false,
      description: `Called when the popover opens or closes. The optional second argument indicates how it was triggered - 'hover' for hover events (when using the hoverable prop) or 'press' for click/press events.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean | "lazy"',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render. The "lazy" value will only initially mount the children after a React startTransition, and then keep them mounted thereafter.`,
    },
    {
      name: 'disableDismissable',
      type: 'boolean',
      required: false,
      description: `Disables the dismissable layer (escape key, outside click handling). Useful when using keepChildrenMounted for popovers that stay mounted but are visually hidden - set this to true when the popover is hidden to prevent it from capturing escape key presses.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      default: '{ padding: 10 }',
      description: `Shifts the popover horizontally to stay within viewport bounds. Pass an object to customize shift behavior (mainAxis, crossAxis, padding).`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
    {
      name: 'disableFocus',
      type: 'boolean',
      default: '!hoverable',
      description: 'Disable opening when the trigger receives keyboard focus. Ordinary popovers open on click, Enter, or Space. Set false to open on focus; hoverable popovers enable this behavior by default.',
    },
    {
      name: 'resize',
      type: 'SizeProps | boolean',
      required: false,
      description: `Will set maxWidth and maxHeight of Content to fit inside outer window when it won't fit, see floating-ui size().`,
    },
    {
      name: 'zIndex',
      type: 'number',
      required: false,
      description: `Override the automatic z-index stacking. By default, Tamagui automatically stacks overlays so later-opened content appears above earlier content. Only set this if you need to override the automatic behavior.`,
    },
  ]}
/>

For most of these properties, you'll want to reference the
[floating-ui docs](https://floating-ui.com/docs/getting-started).

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element.
In order for the Arrow to show you must have a Trigger element within your
Popover. Arrows extend YStack, see [Stacks](/ui/stacks).

<PropsTable
  data={[
    {
      name: 'animatePosition',
      type: 'boolean',
      description: 'Enable smooth animation when the arrow position changes.',
    },
    {
      name: 'size',
      type: 'number',
      description: 'Size of the arrow in pixels.',
    },
    {
      name: 'offset',
      type: 'number',
      description: 'Offset from the content edge.',
    },
  ]}
/>

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack,
see [Stacks](/ui/stacks).

### Popover.Content

Extends PopperContent which extends a YStack (see
[Stacks](/ui/stacks)). Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'animatePosition',
      type: "boolean | 'even-when-repositioning'",
      description:
        'Enable smooth animation when the content position changes (e.g., when flipping sides).',
    },
    {
      name: 'transformOrigin',
      type: 'boolean',
      default: 'true',
      description:
        'Automatically sets CSS transform-origin based on placement and arrow position. Updates when the popover flips. Enables natural scale animations that grow from the arrow point.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      default: false,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'trapFocus',
      type: 'boolean',
      default: false,
      description: 'Whether focus should be trapped within the `Popover`',
    },
    {
      name: 'disableFocusScope',
      type: 'boolean',
      default: false,
      description: 'Whether popover should not focus contents on open',
    },
    {
      name: 'onOpenAutoFocus',
      type: `FocusScopeProps['onMountAutoFocus']`,
      default: false,
      description: 'Event handler called when auto-focusing on open. Can be prevented.',
    },
    {
      name: 'onCloseAutoFocus',
      type: `FocusScopeProps['onUnmountAutoFocus'] | false`,
      default: false,
      description: 'Event handler called when auto-focusing on close. Can be prevented.',
    },
    {
      name: 'lazyMount',
      required: false,
      type: `boolean`,
      description: `Delays mounting content until first open.`,
    },
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Disables part presence gating so the content stays mounted. Matches Dialog forceMount semantics.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/ui/stacks).

When you want the Trigger to be in another location from where the Popover
attaches, use Anchor. When used, Anchor is where the Popover will attach, while
Trigger will open it.

### Sheet (with Adapt)

When used with [Adapt](/ui/adapt), you can render a Sheet when that breakpoint
is active. Import `Sheet` directly from `tamagui` or `@tamagui/sheet`.

See [Sheet](/ui/sheet) for more props.

Must use `Adapt.Contents` inside the `Sheet.Container` to insert the
contents given to `Popover.Content`

### Popover.FocusScope

Provides access to the underlying FocusScope component used by Popover for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'noFocus',
      type: 'boolean',
      default: 'false',
      description: `Zero focus mode. While active, focus is allowed neither inside nor outside the scope. Web only.`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'true',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If
used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove
this ScrollView when swapping into the Sheet, as the Sheet must use its own
ScrollView that handles special logic for interactions with dragging.

## Utility functions

These functions allow you to programmatically manage open popovers.

```tsx
import {
  closeOpenPopovers,
  closeLastOpenedPopover,
  hasOpenPopovers,
} from '@tamagui/popover'
```

### closeOpenPopovers

Closes all currently open popovers. Returns `true` if any popovers were closed, `false` if none were open.

```tsx
const didClose = closeOpenPopovers()
```

### closeLastOpenedPopover

Closes only the most recently opened popover. Returns `true` if a popover was closed, `false` if none were open.

```tsx
const didClose = closeLastOpenedPopover()
```

### hasOpenPopovers

Returns `true` if there are any open popovers, `false` otherwise.

```tsx
if (hasOpenPopovers()) {
  // handle open popovers
}
```


## components/popover/1.110.0

---
title: Popover
description: Show content in a floating pane.
name: popover
component: Popover
package: popover
demoName: Popover
---

<HeroContainer showAnimationDriverControl>
  <PopoverDemo />
</HeroContainer>

```tsx hero template=Popover

```

<Highlights
  features={[
    `Optional arrow pointing to content`,
    `Positioning within page bounds`,
    `Twelve anchor positions`,
  ]}
/>

Popovers are a great way to show content that's only visible when trigger is pressed, floating above the current content.

## Installation

Popover is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/popover
```

### PortalProvider

When rendering into root of app instead of inline, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Anatomy

```tsx
import { Popover, Adapt } from 'tamagui' // or '@tamagui/popover'

export default () => (
  <Popover>
    <Popover.Trigger />

    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      {/* ScrollView is optional, can just put any contents inside if not scrollable */}
      <Popover.ScrollView>{/* ... */}</Popover.ScrollView>
      {/* ... */}
    </Popover.Content>

    {/* optionally change to sheet when small screen */}
    {/* you can also use <Popover.Adapt /> */}
    <Adapt when="maxMd">
      <Popover.Sheet>
        <Popover.Sheet.Overlay />
        <Popover.Sheet.Frame>
          <Popover.Sheet.ScrollView>
            <Adapt.Contents />
          </Popover.Sheet.ScrollView>
        </Popover.Sheet.Frame>
      </Popover.Sheet>
    </Adapt>
  </Popover>
)
```

## API Reference

### Popover

Contains every component for the popover.

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Popover.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'placement',
      type: 'Placement',
      required: false,
      description: `'top' | 'right' | 'bottom' | 'left' | 'top-start' | 'top-end' | 'right-start' | 'right-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end'`,
    },
    {
      name: 'open',
      type: 'boolean',
      required: false,
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      required: false,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      required: false,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      required: false,
      description: `By default, Popover removes children from DOM/rendering when fully hidden. Setting true will keep children mounted even when hidden. This can be beneficial for performance if your popover content is expensive to render.`,
    },
    {
      name: 'stayInFrame',
      type: 'ShiftProps | boolean',
      required: false,
      description: `Keeps the Popover inside the frame, see floating-ui shift().`,
    },
    {
      name: 'allowFlip',
      type: 'FlipProps | boolean',
      required: false,
      description: `Moves the Popover to other sides when space allows it, see floating-ui flip().`,
    },
    {
      name: 'offset',
      type: 'OffsetOptions',
      required: false,
      description: `Determines the distance the Popover appears from the target, see floating-ui offset().`,
    },
    {
      name: 'hoverable',
      type: 'boolean | UseFloatingProps',
      required: false,
      description: `Allows hovering on the trigger to open the popover. See UseFloatingProps from floating-ui: accepts boolean or object of { delay: number, restMs: number, handleClose: Function, mouseOnly: boolean, move: boolean }`,
    },
  ]}
/>

<Notice>
  If using `modal={true}` (which is `true` by default), refer to the [PortalProvider
  installation](/ui/popover/1.83.0#portalprovider) for more information.
</Notice>

### Popover.Arrow

Popover.Arrow can be used to show an arrow that points at the Trigger element. In order for the Arrow to show you must have a Trigger element within your Popover. Arrows extend YStack, see [Stacks](/docs/components/stacks).

### Popover.Trigger

Used to trigger opening of the popover when uncontrolled, just renders a YStack, see [Stacks](/docs/components/stacks).

### Popover.Content

Renders as SizableStack which is just a YStack (see [Stacks](/docs/components/stacks)) with an extra `size` prop that accepts any `SizeTokens`.

Used to display the content of the popover.

<PropsTable
  data={[
    {
      name: 'size',
      type: 'SizeTokens',
      required: false,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Popover.Anchor

Renders as YStack, see [Stacks](/docs/components/stacks).

When you want the Trigger to be in another location from where the Popover attaches, use Anchor. When used, Anchor is where the Popover will attach, while Trigger will open it.

### Popover.Sheet

When used with `Adapt`, Popover will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Popover.Sheet.Frame` to insert the contents given to `Popover.Content`

### Popover.ScrollView

Must be nested inside Content. Renders as a plain React Native ScrollView. If used alongside `<Adapt />` and Sheet, Tamagui will automatically know to remove this ScrollView when swapping into the Sheet, as the Sheet must use it's own ScrollView that handles special logic for interactions with dragging.


## components/separator/1.0.0

---
title: Separator
description: Create borders between components.
name: separator
component: Separator
package: separator
demoName: Separator
---

<HeroContainer>
  <SeparatorDemo />
</HeroContainer>

```tsx hero template=Separator

```

<Highlights features={[`Horizontal and vertical orientation`]} />

## Installation

Separator is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/separator
```

## Usage

Separator uses the `borderWidth` and `borderColor` attribute for its style, so be sure to override those when extending it.

```tsx
export default () => (
  <XStack alignItems="center">
    <Paragraph>Blog</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Docs</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Source</Paragraph>
  </XStack>
)
```

## API Reference

### Separator props

Separators extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'vertical',
      required: false,
      type: 'boolean',
      description: `Show vertical separator.`,
    },
  ]}
/>


## components/separator/2.0.0

---
title: Separator
description: Create borders between components
name: separator
component: Separator
package: separator
demoName: Separator
---

<HeroContainer>
  <SeparatorDemo />
</HeroContainer>

```tsx hero template=Separator

```

<Highlights features={[`Horizontal and vertical orientation`]} />

## Installation

Separator is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/separator
```

## Usage

Separator uses the `borderWidth` and `borderColor` attribute for its style, so be sure to override those when extending it.

```tsx
export default () => (
  <XStack alignItems="center">
    <Paragraph>Blog</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Docs</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Source</Paragraph>
  </XStack>
)
```

## API Reference

### Separator

Separator extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'vertical',
      required: false,
      type: 'boolean',
      description: `Shows the separator vertically.`,
    },
  ]}
/>


## components/separator/3.0.0

---
title: Separator
description: Create borders between components
name: separator
component: Separator
package: separator
demoName: Separator
---

<IntroParagraph>
  Separator draws an accessible horizontal or vertical boundary between groups
  of content.
</IntroParagraph>

<HeroContainer>
  <SeparatorDemo />
</HeroContainer>

```tsx hero template=Separator

```

<Highlights
  features={[
    `Horizontal and vertical orientation`,
    `Web separator role and aria-orientation`,
  ]}
/>

## Installation

Separator is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/separator
```

## Usage

Separator uses the `borderWidth` and `borderColor` attributes for its style, so override those when extending it.

```tsx
export default () => (
  <XStack alignItems="center">
    <Paragraph>Blog</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Docs</Paragraph>
    <Separator alignSelf="stretch" vertical />
    <Paragraph>Source</Paragraph>
  </XStack>
)
```

## API reference

### Separator

Separator extends View, inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'vertical',
      required: false,
      type: 'boolean',
      description: `Shows the separator vertically.`,
    },
  ]}
/>


## components/focus-scope/1.128.0

---
title: FocusScope
description: Manage focus behavior within elements accessibly.
name: focus-scope
component: FocusScope
package: focus-scope
---

<IntroParagraph marginTop={-5} marginBottom={30}>
  A utility component for managing keyboard focus within a container. Controls focus
  trapping, auto-focus behavior, and focus cycling for accessible interactive components.
</IntroParagraph>

Note that this is a web-only component, on native it is a no-op.

<Highlights
  features={[
    'Focus trapping within a container',
    'Autofocus on mount, focus restoration on unmount',
    'Focus looping between first and last tabbable elements',
    'Animation reflow prevention with focusOnIdle',
  ]}
/>

## Installation

FocusScope is already installed in `tamagui`, or you can install it
independently:

```bash
npm install @tamagui/focus-scope
```

## Usage

Wrap any content that needs focus management:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope loop trapped>
    <XStack space="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </XStack>
  </FocusScope>
)
```

## Focus Trapping

Use `trapped` to prevent focus from escaping the scope:

```tsx
import { Button, Dialog, FocusScope, XStack, YStack } from 'tamagui'

export default () => (
  <Dialog>
    <Dialog.Trigger asChild>
      <Button>Open Dialog</Button>
    </Dialog.Trigger>

    <Dialog.Portal>
      <Dialog.Overlay />
      {/* key used by AnimatePresence to animate */}
      <Dialog.Content key="content">
        <FocusScope trapped>
          <YStack space="4">
            <Dialog.Title>Focused Content</Dialog.Title>
            <XStack space="2">
              <Button>Cancel</Button>
              <Button>Confirm</Button>
            </XStack>
          </YStack>
        </FocusScope>
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
```

## Focus Looping

Enable `loop` to cycle focus between first and last elements:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope loop>
    <XStack space="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Last</Button>
      {/* Tab from "Last" goes to "First" */}
    </XStack>
  </FocusScope>
)
```

## Animation-Friendly Focusing

Use `focusOnIdle` to prevent reflows during animations:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope
    focusOnIdle={true} // Wait for idle callback
    // or focusOnIdle={200} // Wait 200ms
  >
    <XStack space="4">
      <Button>Animated</Button>
      <Button>Content</Button>
    </XStack>
  </FocusScope>
)
```

## Advanced Control with FocusScopeController

Use the controller pattern for managing focus from parent components:

```tsx
import { Button, FocusScope, XStack, YStack } from 'tamagui'
import { useState } from 'react'

export default () => {
  const [trapped, setTrapped] = useState(false)

  return (
    <YStack space="4">
      <Button onPress={() => setTrapped(!trapped)}>
        {trapped ? 'Disable' : 'Enable'} Focus Trap
      </Button>

      <FocusScope.Controller trapped={trapped} loop>
        <FocusScope>
          <XStack space="4">
            <Button>Controlled</Button>
            <Button>Focus</Button>
            <Button>Behavior</Button>
          </XStack>
        </FocusScope>
      </FocusScope.Controller>
    </YStack>
  )
}
```

## Function as Children

For advanced use cases, pass a function to get access to focus props:

```tsx
import { FocusScope, View } from 'tamagui'

export default () => (
  <FocusScope loop>
    {({ onKeyDown, tabIndex, ref }) => (
      <View
        ref={ref}
        tabIndex={tabIndex}
        onKeyDown={onKeyDown}
        padding="4"
        borderWidth={1}
        borderColor="border-color"
      >
        Custom focus container
      </View>
    )}
  </FocusScope>
)
```

## API Reference

### FocusScope

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: 'Whether focus management is enabled',
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description:
        'When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable',
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description:
        'When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number | { min?: number; max?: number }',
      default: 'false',
      description:
        'When true, waits for idle before focusing using requestIdleCallback. When a number, waits that many ms. Object sets a lower and upper bound. Helps to prevent reflows during animations, as focusing inputs easily blocks main thread.',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on mount. Can be prevented',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on unmount. Can be prevented',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      default: 'false',
      description:
        'If unmount is animated, you want to force re-focus at start of animation not after',
    },
    {
      name: 'children',
      type: 'React.ReactNode | ((props: FocusProps) => React.ReactNode)',
      description:
        'Content to apply focus management to, or function that receives focus props',
    },
  ]}
/>

### FocusScope.Controller

Provides context-based control over FocusScope behavior:

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      description:
        'Override enabled state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'loop',
      type: 'boolean',
      description:
        'Override loop state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'trapped',
      type: 'boolean',
      description:
        'Override trapped state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      description:
        'Override focusOnIdle behavior for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onMountAutoFocus handler for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onUnmountAutoFocus handler for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      description:
        'Override forceUnmount behavior for all child FocusScope.Controller.Scope components',
    },
  ]}
/>

The FocusScope component automatically inherits props from the nearest
FocusScope.Controller, with controller props taking precedence over direct
props.

## Usage in Other Components

Many Tamagui components export FocusScope for advanced focus control:

```tsx
import { Dialog, Popover, Select } from 'tamagui'

// Available on:
<Dialog.FocusScope />
<Popover.FocusScope />
<Select.FocusScope />
// And more...
```

## Accessibility

FocusScope follows accessibility best practices:

- Manages `tabindex` appropriately for focus flow
- Respects user's reduced motion preferences
- Maintains focus visible indicators
- Provides proper ARIA support when used with other components
- Handles edge cases like disabled elements and hidden content

<Notice>
  FocusScope is primarily designed for web platforms. On React Native, it renders children
  without focus management since native platforms handle focus differently.
</Notice>

## Examples

### Modal Focus Management

```tsx
import { Button, Dialog, FocusScope, Input, XStack, YStack } from 'tamagui'

export default () => (
  <Dialog>
    <Dialog.Trigger asChild>
      <Button>Open Modal</Button>
    </Dialog.Trigger>

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <FocusScope trapped loop focusOnIdle={100}>
          <YStack space="4" padding="4">
            <Dialog.Title>User Details</Dialog.Title>
            <Input placeholder="Name" />
            <Input placeholder="Email" />
            <XStack space="2">
              <Dialog.Close asChild>
                <Button variant="outlined">Cancel</Button>
              </Dialog.Close>
              <Button>Save</Button>
            </XStack>
          </YStack>
        </FocusScope>
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
```

### Custom Focus Container

```tsx
import { Button, FocusScope, styled, XStack } from 'tamagui'

const FocusContainer = styled(XStack, {
  borderWidth: 2,
  borderColor: 'transparent',
  borderRadius: '4',
  padding: '4',

  variants: {
    focused: {
      true: {
        borderColor: 'blue-10',
        shadowColor: 'blue-10',
        shadowRadius: 10,
        shadowOpacity: 0.3,
      },
    },
  },
})

export default () => (
  <FocusScope loop>
    {({ onKeyDown, tabIndex, ref }) => (
      <FocusContainer
        ref={ref}
        tabIndex={tabIndex}
        onKeyDown={onKeyDown}
        space="4"
        focused
      >
        <Button>Action 1</Button>
        <Button>Action 2</Button>
        <Button>Action 3</Button>
      </FocusContainer>
    )}
  </FocusScope>
)
```


## components/focus-scope/2.0.0

---
title: FocusScope
description: Manage focus behavior within elements accessibly.
name: focus-scope
component: FocusScope
package: focus-scope
---

<IntroParagraph marginTop={-5} marginBottom={30}>
  A utility component for managing keyboard focus within a container. Controls focus
  trapping, auto-focus behavior, and focus cycling for accessible interactive components.
</IntroParagraph>

Note that this is a web-only component, on native it is a no-op.

<Highlights
  features={[
    'Focus trapping within a container',
    'Autofocus on mount, focus restoration on unmount',
    'Focus looping between first and last tabbable elements',
    'Animation reflow prevention with focusOnIdle',
  ]}
/>

## Installation

FocusScope is already installed in `tamagui`, or you can install it
independently:

```bash
npm install @tamagui/focus-scope
```

## Usage

Wrap any content that needs focus management:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope loop trapped>
    <XStack space="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </XStack>
  </FocusScope>
)
```

## Focus Trapping

Use `trapped` to prevent focus from escaping the scope:

```tsx
import { Button, Dialog, FocusScope, XStack, YStack } from 'tamagui'

export default () => (
  <Dialog>
    <Dialog.Trigger asChild>
      <Button>Open Dialog</Button>
    </Dialog.Trigger>

    <Dialog.Portal>
      <Dialog.Overlay />
      {/* key used by AnimatePresence to animate */}
      <Dialog.Content key="content">
        <FocusScope trapped>
          <YStack space="4">
            <Dialog.Title>Focused Content</Dialog.Title>
            <XStack space="2">
              <Button>Cancel</Button>
              <Button>Confirm</Button>
            </XStack>
          </YStack>
        </FocusScope>
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
```

## Focus Looping

Enable `loop` to cycle focus between first and last elements:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope loop>
    <XStack space="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Last</Button>
      {/* Tab from "Last" goes to "First" */}
    </XStack>
  </FocusScope>
)
```

## Animation-Friendly Focusing

Use `focusOnIdle` to prevent reflows during animations:

```tsx
import { Button, FocusScope, XStack } from 'tamagui'

export default () => (
  <FocusScope
    focusOnIdle={true} // Wait for idle callback
    // or focusOnIdle={200} // Wait 200ms
  >
    <XStack space="4">
      <Button>Animated</Button>
      <Button>Content</Button>
    </XStack>
  </FocusScope>
)
```

## Advanced Control with FocusScopeController

Use the controller pattern for managing focus from parent components:

```tsx
import { Button, FocusScope, XStack, YStack } from 'tamagui'
import { useState } from 'react'

export default () => {
  const [trapped, setTrapped] = useState(false)

  return (
    <YStack space="4">
      <Button onPress={() => setTrapped(!trapped)}>
        {trapped ? 'Disable' : 'Enable'} Focus Trap
      </Button>

      <FocusScope.Controller trapped={trapped} loop>
        <FocusScope>
          <XStack space="4">
            <Button>Controlled</Button>
            <Button>Focus</Button>
            <Button>Behavior</Button>
          </XStack>
        </FocusScope>
      </FocusScope.Controller>
    </YStack>
  )
}
```

## Function as Children

For advanced use cases, pass a function to get access to focus props:

```tsx
import { FocusScope, html } from 'tamagui'

export default () => (
  <FocusScope loop>
    {({ onKeyDown, tabIndex, ref }) => (
      <html.div
        ref={ref}
        tabIndex={tabIndex}
        onKeyDown={onKeyDown}
        padding="4"
        borderWidth={1}
        borderColor="border-color"
      >
        Custom focus container
      </html.div>
    )}
  </FocusScope>
)
```

## API Reference

### FocusScope

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: 'Whether focus management is enabled',
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description:
        'When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable',
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description:
        'When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number | { min?: number; max?: number }',
      default: 'false',
      description:
        'When true, waits for idle before focusing using requestIdleCallback. When a number, waits that many ms. Object sets a lower and upper bound. Helps to prevent reflows during animations, as focusing inputs easily blocks main thread.',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on mount. Can be prevented',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on unmount. Can be prevented',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      default: 'false',
      description:
        'If unmount is animated, you want to force re-focus at start of animation not after',
    },
    {
      name: 'children',
      type: 'React.ReactNode | ((props: FocusProps) => React.ReactNode)',
      description:
        'Content to apply focus management to, or function that receives focus props',
    },
  ]}
/>

### FocusScope.Controller

Provides context-based control over FocusScope behavior:

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      description:
        'Override enabled state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'loop',
      type: 'boolean',
      description:
        'Override loop state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'trapped',
      type: 'boolean',
      description:
        'Override trapped state for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      description:
        'Override focusOnIdle behavior for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onMountAutoFocus handler for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onUnmountAutoFocus handler for all child FocusScope.Controller.Scope components',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      description:
        'Override forceUnmount behavior for all child FocusScope.Controller.Scope components',
    },
  ]}
/>

The FocusScope component automatically inherits props from the nearest
FocusScope.Controller, with controller props taking precedence over direct
props.

## Usage in Other Components

Many Tamagui components export FocusScope for advanced focus control:

```tsx
import { Dialog, Popover, Select } from 'tamagui'

// Available on:
<Dialog.FocusScope />
<Popover.FocusScope />
<Select.FocusScope />
// And more...
```

## Accessibility

FocusScope follows accessibility best practices:

- Manages `tabindex` appropriately for focus flow
- Respects user's reduced motion preferences
- Maintains focus visible indicators
- Provides proper ARIA support when used with other components
- Handles edge cases like disabled elements and hidden content

<Notice>
  FocusScope is primarily designed for web platforms. On React Native, it renders children
  without focus management since native platforms handle focus differently.
</Notice>

## Examples

### Modal Focus Management

```tsx
import { Button, Dialog, FocusScope, Input, XStack, YStack } from 'tamagui'

export default () => (
  <Dialog>
    <Dialog.Trigger asChild>
      <Button>Open Modal</Button>
    </Dialog.Trigger>

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <FocusScope trapped loop focusOnIdle={100}>
          <YStack space="4" padding="4">
            <Dialog.Title>User Details</Dialog.Title>
            <Input placeholder="Name" />
            <Input placeholder="Email" />
            <XStack space="2">
              <Dialog.Close asChild>
                <Button variant="outlined">Cancel</Button>
              </Dialog.Close>
              <Button>Save</Button>
            </XStack>
          </YStack>
        </FocusScope>
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
```

### Custom Focus Container

```tsx
import { Button, FocusScope, styled, XStack } from 'tamagui'

const FocusContainer = styled(XStack, {
  borderWidth: 2,
  borderColor: 'transparent',
  borderRadius: '4',
  padding: '4',

  variants: {
    focused: {
      true: {
        borderColor: 'blue-10',
        shadowColor: 'blue-10',
        shadowRadius: 10,
        shadowOpacity: 0.3,
      },
    },
  },
})

export default () => (
  <FocusScope loop>
    {({ onKeyDown, tabIndex, ref }) => (
      <FocusContainer
        ref={ref}
        tabIndex={tabIndex}
        onKeyDown={onKeyDown}
        space="4"
        focused
      >
        <Button>Action 1</Button>
        <Button>Action 2</Button>
        <Button>Action 3</Button>
      </FocusContainer>
    )}
  </FocusScope>
)
```


## components/focus-scope/3.0.0

---
title: FocusScope
description: Manage keyboard focus trapping and roving navigation accessibly
name: focus-scope
component: FocusScope
package: focus-scope
---

<IntroParagraph marginTop={-5} marginBottom={30}>
  Components for managing keyboard focus: **FocusScope** for trapping and containing focus
  within modals and dialogs, and **RovingFocusGroup** for arrow-key roving tabindex navigation across composite widgets.
</IntroParagraph>

These are web-only components. On native they render their children with no
keyboard navigation management.

<Highlights
  features={[
    'Focus trapping for modal dialogs and overlays',
    'Composite-widget arrow navigation with one tab stop',
    'Autofocus on mount, focus restoration on unmount',
    'Focus looping between first and last tabbable elements',
    'Focus-inert content with noFocus',
    'Animation reflow prevention with focusOnIdle',
  ]}
/>

## Installation

FocusScope and RovingFocusGroup ship in their own packages:

```bash
npm install @tamagui/focus-scope @tamagui/roving-focus
```

## Focus trapping (FocusScope)

Wrap any content that needs focus containment or trapping:

```tsx
import { Button, XStack } from 'tamagui'
import { FocusScope } from '@tamagui/focus-scope'

export default () => (
  <FocusScope loop trapped>
    <XStack gap="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </XStack>
  </FocusScope>
)
```

In v3, FocusScope renders a `display: contents` wrapper so it does not add an extra layout box around its children.

### Trapped focus

Use `trapped` to prevent focus from escaping the scope (ideal for modals, dialogs, and sheets):

```tsx
import { Button, Dialog, XStack, YStack } from 'tamagui'
import { FocusScope } from '@tamagui/focus-scope'

export default () => (
  <Dialog>
    <Dialog.Trigger asChild>
      <Button>Open Dialog</Button>
    </Dialog.Trigger>

    <Dialog.Portal>
      <Dialog.Overlay />
      {/* key used by AnimatePresence to animate */}
      <Dialog.Content key="content">
        <FocusScope trapped>
          <YStack gap="4">
            <Dialog.Title>Focused Content</Dialog.Title>
            <XStack gap="2">
              <Button>Cancel</Button>
              <Button>Confirm</Button>
            </XStack>
          </YStack>
        </FocusScope>
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)
```

### Zero focus mode

Use `noFocus` to disallow focus entirely while the scope is active: focus can land neither inside nor outside the scope. Any element that receives focus is immediately blurred, so `document.activeElement` settles on `document.body`. This takes precedence over `trapped` and auto-focus behavior:

```tsx
import { Button, Input, XStack } from 'tamagui'
import { FocusScope } from '@tamagui/focus-scope'

export default () => (
  <FocusScope noFocus>
    <XStack gap="4">
      <Input placeholder="Cannot be focused" />
      <Button>Cannot be focused either</Button>
    </XStack>
  </FocusScope>
)
```

### Focus looping

Enable `loop` to cycle focus between first and last elements:

```tsx
import { Button, XStack } from 'tamagui'
import { FocusScope } from '@tamagui/focus-scope'

export default () => (
  <FocusScope loop>
    <XStack gap="4">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Last</Button>
      {/* Tab from "Last" goes to "First" */}
    </XStack>
  </FocusScope>
)
```

### Animation-friendly focusing

Use `focusOnIdle` to prevent reflows during animations:

```tsx
import { Button, XStack } from 'tamagui'
import { FocusScope } from '@tamagui/focus-scope'

export default () => (
  <FocusScope
    focusOnIdle={true} // Wait for idle callback
    // or focusOnIdle={200} // Wait 200ms
  >
    <XStack gap="4">
      <Button>Animated</Button>
      <Button>Content</Button>
    </XStack>
  </FocusScope>
)
```

### Advanced control with FocusScopeController

Use the controller pattern for managing focus from parent components:

```tsx
import { Button, XStack, YStack } from 'tamagui'
import { FocusScope, FocusScopeController } from '@tamagui/focus-scope'
import { useState } from 'react'

export default () => {
  const [trapped, setTrapped] = useState(false)

  return (
    <YStack gap="4">
      <Button onPress={() => setTrapped(!trapped)}>
        {trapped ? 'Disable' : 'Enable'} Focus Trap
      </Button>

      <FocusScopeController trapped={trapped} loop>
        <FocusScope>
          <XStack gap="4">
            <Button>Controlled</Button>
            <Button>Focus</Button>
            <Button>Behavior</Button>
          </XStack>
        </FocusScope>
      </FocusScopeController>
    </YStack>
  )
}
```

### FocusScope props

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: 'Whether focus management is enabled',
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description:
        'When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable',
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description:
        'When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus',
    },
    {
      name: 'noFocus',
      type: 'boolean',
      default: 'false',
      description:
        'Zero focus mode: while active, focus is allowed neither inside nor outside the scope. Anything that receives focus is immediately blurred. Takes precedence over trapped and auto-focus. Web only',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number | { min?: number; max?: number }',
      default: 'true',
      description:
        'When true, waits for idle before focusing using requestIdleCallback. When a number, waits that many ms. Object sets a lower and upper bound. Helps to prevent reflows during animations, as focusing inputs easily blocks main thread.',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on mount. Can be prevented',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: 'Event handler called when auto-focusing on unmount. Can be prevented',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      default: 'false',
      description:
        'If unmount is animated, you want to force re-focus at start of animation not after',
    },
    {
      name: 'children',
      type: 'React.ReactNode',
      description: 'Content to apply focus management to',
    },
  ]}
/>

### FocusScopeController props

Provides context-based control over FocusScope behavior:

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      description:
        'Override enabled state for all child FocusScope components',
    },
    {
      name: 'loop',
      type: 'boolean',
      description:
        'Override loop state for all child FocusScope components',
    },
    {
      name: 'trapped',
      type: 'boolean',
      description:
        'Override trapped state for all child FocusScope components',
    },
    {
      name: 'noFocus',
      type: 'boolean',
      description:
        'Override noFocus (zero focus mode) for all child FocusScope components',
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      description:
        'Override focusOnIdle behavior for all child FocusScope components',
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onMountAutoFocus handler for all child FocusScope components',
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description:
        'Override onUnmountAutoFocus handler for all child FocusScope components',
    },
    {
      name: 'forceUnmount',
      type: 'boolean',
      description:
        'Override forceUnmount behavior for all child FocusScope components',
    },
  ]}
/>

The FocusScope component automatically inherits props from the nearest FocusScopeController, with controller props taking precedence over direct props.

## Roving focus (RovingFocusGroup)

The roving tabindex pattern manages focus across a group of interactive elements (like toolbars, tab lists, or radio groups) so that the entire group acts as a single tab stop. Arrow keys move focus between items within the group, and pressing Tab moves focus out of the group.

```tsx
import { Button, XStack } from 'tamagui'
import { RovingFocusGroup } from '@tamagui/roving-focus'

export default () => (
  <RovingFocusGroup orientation="horizontal" loop>
    <XStack gap="2">
      <RovingFocusGroup.Item asChild>
        <Button>First</Button>
      </RovingFocusGroup.Item>
      <RovingFocusGroup.Item asChild>
        <Button>Second</Button>
      </RovingFocusGroup.Item>
      <RovingFocusGroup.Item asChild>
        <Button>Third</Button>
      </RovingFocusGroup.Item>
    </XStack>
  </RovingFocusGroup>
)
```

### Orientation

Set `orientation` to `"horizontal"` or `"vertical"` to control which arrow keys navigate:

```tsx
import { Button, YStack } from 'tamagui'
import { RovingFocusGroup } from '@tamagui/roving-focus'

export default () => (
  // Up/Down arrows navigate, Left/Right are ignored
  <RovingFocusGroup orientation="vertical">
    <YStack gap="2">
      <RovingFocusGroup.Item asChild>
        <Button>Option 1</Button>
      </RovingFocusGroup.Item>
      <RovingFocusGroup.Item asChild>
        <Button>Option 2</Button>
      </RovingFocusGroup.Item>
      <RovingFocusGroup.Item asChild>
        <Button>Option 3</Button>
      </RovingFocusGroup.Item>
    </YStack>
  </RovingFocusGroup>
)
```

### Looping navigation

Enable `loop` to wrap focus from the last item back to the first:

```tsx
<RovingFocusGroup loop orientation="horizontal">
  {/* items */}
</RovingFocusGroup>
```

### Controlled tab stop

Control which item is the current tab stop via `currentTabStopId` and `onCurrentTabStopIdChange`:

```tsx
import { Button, XStack } from 'tamagui'
import { RovingFocusGroup } from '@tamagui/roving-focus'
import { useState } from 'react'

export default () => {
  const [currentId, setCurrentId] = useState<string | null>('item-2')

  return (
    <RovingFocusGroup
      currentTabStopId={currentId}
      onCurrentTabStopIdChange={setCurrentId}
    >
      <XStack gap="2">
        <RovingFocusGroup.Item tabStopId="item-1" asChild>
          <Button>First</Button>
        </RovingFocusGroup.Item>
        <RovingFocusGroup.Item tabStopId="item-2" asChild>
          <Button>Second (default)</Button>
        </RovingFocusGroup.Item>
        <RovingFocusGroup.Item tabStopId="item-3" asChild>
          <Button>Third</Button>
        </RovingFocusGroup.Item>
      </XStack>
    </RovingFocusGroup>
  )
}
```

### Non-focusable items

Give an item a negative `tabIndex` to make it non-focusable and skip it during keyboard navigation:

```tsx
<RovingFocusGroup.Item tabIndex={-1} asChild>
  <Button disabled>Disabled</Button>
</RovingFocusGroup.Item>
```

### RovingFocusGroup props

<PropsTable
  data={[
    {
      name: 'orientation',
      type: '"horizontal" | "vertical"',
      description:
        'The orientation of the group. Determines which arrow keys are used for navigation (left/right vs up/down).',
    },
    {
      name: 'dir',
      type: '"ltr" | "rtl"',
      description:
        'The reading direction. When set to rtl, left and right arrow keys are reversed.',
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description:
        'When true, keyboard navigation will loop from last to first and vice versa.',
    },
    {
      name: 'currentTabStopId',
      type: 'string | null',
      description: 'The controlled id of the current tab stop.',
    },
    {
      name: 'defaultCurrentTabStopId',
      type: 'string',
      description: 'The default id of the current tab stop for uncontrolled usage.',
    },
    {
      name: 'onCurrentTabStopIdChange',
      type: '(tabStopId: string | null) => void',
      description: 'Callback when the current tab stop changes.',
    },
    {
      name: 'onEntryFocus',
      type: '(details: RovingFocusEntryDetails) => void',
      description:
        'Callback when focus enters the group via keyboard. Call details.cancel() to prevent the default focus behavior.',
    },
    {
      name: 'asChild',
      type: 'boolean',
      default: 'false',
      description: 'When true, renders as a Slot, merging props onto the child element.',
    },
  ]}
/>

### RovingFocusGroup.Item props

<PropsTable
  data={[
    {
      name: 'tabStopId',
      type: 'string',
      description: 'A unique identifier for this item. Auto-generated if not provided.',
    },
    {
      name: 'tabIndex',
      type: 'number',
      default: '0',
      description:
        'Items with a negative tabIndex are skipped during keyboard navigation.',
    },
    {
      name: 'active',
      type: 'boolean',
      default: 'false',
      description:
        'Whether this item is considered active. Active items receive focus priority when the group is entered.',
    },
    {
      name: 'asChild',
      type: 'boolean',
      default: 'false',
      description: 'When true, renders as a Slot, merging props onto the child element.',
    },
  ]}
/>

### Keyboard navigation

| Key | Action |
| --- | --- |
| `Tab` | Move focus into/out of the group |
| `Arrow Left/Right` | Move focus between items (horizontal orientation) |
| `Arrow Up/Down` | Move focus between items (vertical orientation) |
| `Home` / `Page Up` | Move focus to first item |
| `End` / `Page Down` | Move focus to last item |

## Internal usage in Tamagui

FocusScope and RovingFocusGroup power accessibility throughout Tamagui:

- **FocusScope** handles focus trapping in [Dialog](/ui/dialog), [AlertDialog](/ui/alert-dialog), [Sheet](/ui/sheet), and [Popover](/ui/popover).
- **RovingFocusGroup** manages roving arrow-key navigation in [Tabs](/ui/tabs), [RadioGroup](/ui/radio-group), and [ToggleGroup](/ui/toggle-group).

<Notice>
  Both components are primarily designed for web platforms. On React Native, they render
  children directly without web focus management since native platforms manage focus and touch interaction natively.
</Notice>


## components/label/1.0.0

---
title: Label
description: Label form elements with accessibility.
name: label
component: Label
package: label
demoName: Label
---

<HeroContainer>
  <LabelDemo />
</HeroContainer>

```tsx hero template=Label

```

<Highlights
  features={[
    `Nested and custom control support`,
    `Inline sizing and styling`,
    `Web accessibility with aria-labelledby`,
  ]}
/>

## Installation

Label is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/label
```

## Usage

```tsx
import { Label } from 'tamagui'

export default () => (
  <>
    <Label htmlFor="name">Name</Label>
    <Input id="name" defaultValue="Nate Wienert" />
  </>
)
```

## Accessibility

Use with Input or other form elements to automatically get correct labelling by id and aria-labelledby. You can also use the provided `useLabelContext` hook to build your own controls.

## API Reference

### Label

Labels extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'htmlFor',
      type: 'string',
      required: true,
      description: `Matching to a Tamagui form element id.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/label/2.0.0

---
title: Label
description: Label form elements with accessibility
name: label
component: Label
package: label
demoName: Label
---

<IntroParagraph>
  Label associates text with form controls and preserves that relationship for
  assistive technology.
</IntroParagraph>

<HeroContainer>
  <LabelDemo />
</HeroContainer>

```tsx hero template=Label

```

<Highlights
  features={[
    `Nested and custom control support`,
    `Inline sizing and styling`,
    `Web accessibility with aria-labelledby`,
  ]}
/>

## Installation

Label is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/label
```

## Usage

```tsx
import { Label } from 'tamagui'

export default () => (
  <>
    <Label htmlFor="name">Name</Label>
    <Input id="name" defaultValue="Nate Wienert" />
  </>
)
```

## Accessibility

Use with Input or other form elements to automatically get correct labelling by id and aria-labelledby. You can also use the provided `useLabelContext` hook to build your own controls.

Label supports all standard ARIA attributes for form accessibility. These work on both web and React Native. See the [React Native Accessibility docs](https://reactnative.dev/docs/accessibility) for native behavior.

### Required fields

```tsx
<Label htmlFor="email" aria-required>
  Email
</Label>
<Input id="email" aria-required />
```

### Invalid state

```tsx
<Label htmlFor="email" aria-invalid={hasError}>
  Email
</Label>
<Input id="email" aria-invalid={hasError} aria-errormessage="email-error" />
{hasError && <html.span id="email-error">Please enter a valid email</html.span>}
```

### With description

```tsx
<Label htmlFor="password" aria-describedby="password-hint">
  Password
</Label>
<Input id="password" aria-describedby="password-hint" />
<html.span id="password-hint">Must be at least 8 characters</html.span>
```

## API reference

### Label

Labels extend SizableText inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'htmlFor',
      type: 'string',
      required: true,
      description: `Matches the \`id\` of a form element to associate with.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Accessibility props

Label passes through all ARIA attributes. These are the most commonly used for form labeling:

<PropsTable
  data={[
    {
      name: 'aria-required',
      type: 'boolean',
      description: `Indicates user input is required before form submission.`,
    },
    {
      name: 'aria-invalid',
      type: 'boolean',
      description: `Indicates the associated field has a validation error.`,
    },
    {
      name: 'aria-disabled',
      type: 'boolean',
      description: `Indicates the associated control is disabled.`,
    },
    {
      name: 'aria-describedby',
      type: 'string',
      description: `References an element providing additional description such as hint text or error messages.`,
    },
    {
      name: 'aria-labelledby',
      type: 'string',
      description: `References another element that labels this one. \`Label\` sets this automatically on the target input.`,
    },
    {
      name: 'aria-details',
      type: 'string',
      description: `References an element providing extended description or instructions.`,
    },
  ]}
/>

These props work cross-platform. On web they render as standard ARIA attributes. On
React Native they map to the native accessibility system. See the [React Native
Accessibility docs](https://reactnative.dev/docs/accessibility) for details.


## components/stacks/1.0.0

---
title: Stacks
description: An optional base for creating flex-based layouts.
name: stacks
component: Stacks
package: stacks
demoName: Stacks
---

<HeroContainer>
  <StacksDemo />
</HeroContainer>

```tsx hero template=Stacks

```

<Highlights
  features={[
    'X, Y, and Z flex stacks',
    'Spacing between elements with gap',
    'Press, focus, and layout events',
  ]}
/>

Tamagui Components includes optional stack views - XStack, YStack and ZStack. They extend directly off the [View](/docs/core/view-and-text) from `@tamagui/core`.

They accept [every prop from react-native-web's View](https://necolas.github.io/react-native-web/docs/view/), as well as all [the style properties Tamagui supports](/docs/intro/props).

In this example you'd show three `YStack` elements spaced out.

## Installation

Stacks is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/stacks
```

```tsx
import { XStack, YStack } from 'tamagui'

export default () => (
  <XStack gap="2">
    <YStack />
    <YStack />
    <YStack />
  </XStack>
)
```

To see all the style properties supported, see the [Props](/docs/intro/props) documentation.

### Fuller example

An example using a wide variety of style properties:

```tsx
import { Text, XStack, YStack } from 'tamagui'

export default () => (
  <XStack
    flex={1}
    flexWrap="wrap"
    backgroundColor="#fff hover:red"
    flexDirection="gtSm:column"
    flexWrap="wrap gtSm:nowrap"
  >
    <YStack gap="3">
      <Text>Hello</Text>
      <Text>World</Text>
    </YStack>
  </XStack>
)
```

## API Reference

### XStack, YStack, ZStack

Stacks accept all standard [Tamagui Props](/docs/intro/props).



## components/stacks/2.0.0

---
title: Stacks
description: An optional base for creating flex-based layouts
name: stacks
component: Stacks
package: stacks
demoName: Stacks
---

<IntroParagraph>
  XStack, YStack, and ZStack provide styled flex layouts for horizontal,
  vertical, and overlapping content.
</IntroParagraph>

<HeroContainer>
  <StacksDemo />
</HeroContainer>

```tsx hero template=Stacks

```

<Highlights
  features={[
    'X, Y, and Z flex stacks',
    'Spacing between elements with gap',
    'Press, focus, and layout events',
  ]}
/>

Tamagui components include optional stack views: XStack, YStack and ZStack. They
extend the [View](/docs/core/view-and-text) from `@tamagui/core`,
so they accept all [style properties](/docs/intro/props).

## Installation

Stacks is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/stacks
```

## Usage

```tsx
import { XStack, YStack } from 'tamagui'

export default () => (
  <XStack gap="2">
    <YStack />
    <YStack />
    <YStack />
  </XStack>
)
```

To see all the style properties supported, see the [Props](/docs/intro/props)
documentation.

### Fuller example

An example using a wide variety of style properties:

```tsx
import { Text, XStack, YStack } from 'tamagui'

export default () => (
  <XStack
    flex={1}
    flexWrap="wrap"
    backgroundColor="#fff hover:red"
    flexDirection="gtSm:column"
    flexWrap="wrap gtSm:nowrap"
  >
    <YStack gap="3">
      <Text>Hello</Text>
      <Text>World</Text>
    </YStack>
  </XStack>
)
```

## API reference

### XStack, YStack, ZStack

Stacks accept all standard [Tamagui Props](/docs/intro/props).


## components/lucide-icons/1.0.0

---
title: Lucide Icons
description: Cross-platform compatible SVG based icons
demoName: LucideIcons
---

<HeroContainer noPad>
  <LucideIconsDemo />
</HeroContainer>

## Installation

```sh
yarn add react-native-svg @tamagui/lucide-icons-2
```

## Usage

Use them as regular React components

```tsx
import { Button } from 'tamagui'
import { Plus } from '@tamagui/lucide-icons-2'

// Button will automatically pass size/theme to icon
export default () => <Button icon={Plus}>Hello world</Button>

// or you can control it
export default () => <Button icon={<Plus size="4" />}>Hello world</Button>
```

They accept your tokens/theme keys for color and size.

## Credit

The great [Lucide Icons](https://lucide.dev/), a superset of the wonderful [Feather Icons](https://feathericons.com/).


## components/lucide-icons/2.0.0

---
title: Lucide Icons
description: Cross-platform compatible SVG-based icons
name: lucide-icons
component: LucideIcons
package: lucide-icons
demoName: LucideIcons
---

<HeroContainer noPad>
  <LucideIconsDemo />
</HeroContainer>

## Installation

```sh
yarn add react-native-svg @tamagui/lucide-icons-2
```

<Notice>
  If you're using icons in a monorepo, install `react-native-svg` in the parent
  app or workspace root rather than a leaf package.
</Notice>

## Usage

Use them as regular React components:

```tsx
import { Button } from 'tamagui'
import { Plus } from '@tamagui/lucide-icons-2'

// Button will automatically pass size/theme to icon
export default () => <Button icon={Plus}>Hello world</Button>

// or you can control it
export default () => <Button icon={<Plus size="4" />}>Hello world</Button>
```

They accept your tokens/theme keys for color and size.

## Credit

The great [Lucide Icons](https://lucide.dev/), a superset of the wonderful [Feather Icons](https://feathericons.com/).


## components/lucide-icons/3.0.0

---
title: Lucide Icons
description: Generate only the icons you use, typed and themed for Tamagui
name: lucide-icons
component: LucideIcons
package: lucide-icons
demoName: LucideIcons
---

<IntroParagraph>
  Tamagui v3 ships no bundled icon package. Instead you generate typed SVG
  icon components for only the icons you use, rendering consistently on web
  and native.
</IntroParagraph>

<HeroContainer noPad>
  <LucideIconsDemo />
</HeroContainer>

The browser above is a generated Lucide set, built with the command on this
page. v2's `@tamagui/lucide-icons-2` shipped all ~1700 Lucide icons as
one dependency; most apps use a few dozen, so v3 replaces it with
generation: one tree-shakeable file per icon, typed `IconProps`, and the same
`themed` size/color behavior through `@tamagui/helpers-icon`.

## Setup

Install the runtime dependencies:

```bash
npm install react-native-svg @tamagui/helpers-icon
```

<Notice>
  If you're using icons in a monorepo, install `react-native-svg` in the parent
  app or workspace root rather than a leaf package.
</Notice>

Then generate the icons you use. Each one becomes a file in
`components/icons`, and `components/icons/index.ts` exports all of them:

```bash
npx @tamagui/cli icons add Plus Search X
```

Run it again whenever you need another icon; it adds to the folder and rewrites
the index. `--out` picks a different folder. The same command generates
[Phosphor](https://phosphoricons.com/) and [Heroicons](https://heroicons.com/)
icons, or components from your own svg files, see
[the CLI reference](/docs/core/cli#icons).

The Tamagui repo generates its Lucide set from
`code/packages/local-icons/icons.json`, and this site's own Phosphor icons from
`code/tamagui.dev/components/icons/icons.json`.

## Usage

Use them as regular React components:

```tsx
import { Button } from 'tamagui'
import { Plus } from './components/icons'

// Button will automatically pass size/theme to icon
export default () => <Button icon={Plus}>Hello world</Button>

// or you can control it
export default () => <Button icon={<Plus size="4" />}>Hello world</Button>
```

They accept your theme keys for color and your font size tokens for size. In v3,
`size="4"` resolves through the current font's `font.size.4` scale so icons
line up with `4` text. Raw numeric sizes are unchanged.

```tsx
<Plus size="4" color="color" />
<Plus size={18} color="blue-500" />
```

Themed icons no longer run full Tamagui style resolution, so media and pseudo
props are not accepted directly on the icon. Wrap the icon when you need those
styles:

```tsx
import { View, styled } from 'tamagui'

const IconFrame = styled(View, {
  opacity: 'sm:0.6',
  scale: 'hover:1.05',
})

<IconFrame>
  <Plus size="4" />
</IconFrame>
```

## Migrating from v2

Replace `@tamagui/lucide-icons-2` imports with your generated directory and
generate every icon you use. The command stops on unknown names and lists
them; Lucide keeps most renamed icons under their old names, but a few were
removed (brand icons such as `Figma`), so check current names on
[lucide.dev](https://lucide.dev/) when it does.

## Credit

The great [Lucide Icons](https://lucide.dev/), a superset of the wonderful [Feather Icons](https://feathericons.com/).


## components/checkbox/1.85.0

---
title: Checkbox
description: A simple checkbox component
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---

# Checkbox

<Description>Toggle state in forms.</Description>

<YStack className="is-sticky" />

<Tabs id="type" defaultValue="styled">
<Tabs.List>
  <TooltipSimple label="With Tamagui's default styles">
    <Tabs.Tab value="styled">Styled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No default styles, easy to customize">
    <Tabs.Tab value="unstyled">Unstyled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No dependency on Tamagui's core">
    <Tabs.Tab value="headless" label="No styles and no dependency on Tamagui's styling">Headless</Tabs.Tab>
  </TooltipSimple>
</Tabs.List>

<HeroContainer showAnimationDriverControl>
  <Tabs.Content value="styled" justifyContent="center" alignItems="center" width="100%">
    <CheckboxDemo />
  </Tabs.Content>
  <Tabs.Content value="unstyled" justifyContent="center" alignItems="center" width="100%">
    <CheckboxDemo />
  </Tabs.Content>
  <Tabs.Content value="headless" justifyContent="center" alignItems="center" width="100%">
    <CheckboxHeadlessDemo />
  </Tabs.Content>
</HeroContainer>

<Tabs.Content value="styled">
```tsx hero template=Checkbox

```
</Tabs.Content>
<Tabs.Content value="unstyled">
```tsx hero template=Checkbox

```

</Tabs.Content>
  <Tabs.Content value="headless">
```tsx hero template=CheckboxHeadless

```
</Tabs.Content>

<Highlights
features={[
  `Indeterminate state support`,
  `Accessible, composable, and customizable`,
  `Sizing with controlled or uncontrolled state`,
  `Optional native HTML checkbox on web`,
]}
/>

## Installation

<Tabs.Content value="styled">
Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

</Tabs.Content>

<Tabs.Content value="unstyled">
Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

</Tabs.Content>

<Tabs.Content value="headless">

To use the headless switch, you want to import it from the
`@tamagui/switch-headless` package. This package has no dependency on
`@tamagui/core`, but still works off the react-native APIs.
This means can bring your own style library.

```bash
npm install @tamagui/switch-headless
```

</Tabs.Content>

## Usage

<Tabs.Content value="styled">

```tsx
import { Check } from '@tamagui/lucide-icons-2'
import { Checkbox } from 'tamagui'

export default () => (
  <Checkbox size="4">
    <Checkbox.Indicator>
      <Check />
    </Checkbox.Indicator>
  </Checkbox>
)
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Use the `createCheckbox` export to create a fully custom checkbox that still
uses the Tamagui styling system. This is similar to setting `unstyled`, but goes
a bit further. It doesn't add any types for `size` or `unstyled`, and it won't
automatically apply the `active` theme. If does pass the `checked` prop down as
indicated in the types of `createCheckbox`.

```tsx template=Checkbox

```

</Tabs.Content>

<Tabs.Content value="headless">

Using the `useCheckbox` API, you can make your own Checkbox from scratch.

```tsx template=CheckboxHeadless

```

</Tabs.Content>

## API Reference

### Checkbox

`Checkbox` extend ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native checkbox input on web.`,
      default: false,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean | "indeterminate") => void',
      description: 'Callback that fires when the checkbox state is changed.',
    },
    {
      name: 'sizeAdjust',
      type: 'number',
      description: `Adjust the checkbox size scaling by this number.`,
    },
    {
      name: 'scaleIcon',
      type: 'number',
      description: `Scale the indicator icon more than usual by this number.`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Checkbox.Indicator

`Checkbox.Indicator` extend ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Used to force mounting when more control is needed.`,
    },
    {
      name: 'disablePassStyles',
      required: false,
      type: 'boolean',
      description: `Used to disable passing styles down to children.`,
    },
  ]}
/>

</Tabs>


## components/checkbox/1.3.0

---
title: Checkbox
description: A simple checkbox component
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---

# Checkbox

<Description>Use in forms to toggle between two states.</Description>

<HeroContainer>
  <CheckboxDemo />
</HeroContainer>

```tsx hero template=Checkbox

```

<Highlights
  features={[
    `Indeterminate state support`,
    `Accessible, composable, and customizable`,
    `Sizing with controlled or uncontrolled state`,
    `Optional native HTML checkbox on web`,
  ]}
/>

## Installation

Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

## Usage

```tsx
import { Check } from '@tamagui/lucide-icons-2'
import { Checkbox } from 'tamagui'

export default () => (
  <Checkbox size="4">
    <Checkbox.Indicator>
      <Check />
    </Checkbox.Indicator>
  </Checkbox>
)
```

## API Reference

### Checkbox

`Checkbox` extend ThemeableStack inheriting all the [props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native checkbox input on web.`,
      default: false,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean | "indeterminate") => void',
      description: 'Callback that fires when the checkbox state is changed.',
    },
    {
      name: 'sizeAdjust',
      type: 'number',
      description: `Adjust the checkbox size scaling by this number.`,
    },
    {
      name: 'scaleIcon',
      type: 'number',
      description: `Scale the indicator icon more than usual by this number.`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Checkbox.Indicator

`Checkbox.Indicator` extend ThemeableStack inheriting all the [props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Used to force mounting when more control is needed.`,
    },
    {
      name: 'disablePassStyles',
      required: false,
      type: 'boolean',
      description: `Used to disable passing styles down to children.`,
    },
  ]}
/>


## components/checkbox/1.89.0

---
title: Checkbox
description: Toggle state in forms.
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---

<YStack className="is-sticky" />

<Tabs id="type" defaultValue="styled">
<Tabs.List>
  <TooltipSimple label="With Tamagui's default styles">
    <Tabs.Tab value="styled">Styled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No default styles, easy to customize">
    <Tabs.Tab value="unstyled">Unstyled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No dependency on Tamagui's core">
    <Tabs.Tab value="headless" label="No styles and no dependency on Tamagui's styling">Headless</Tabs.Tab>
  </TooltipSimple>
</Tabs.List>

<HeroContainer showAnimationDriverControl>
  <Tabs.Content value="styled" justifyContent="center" alignItems="center" width="100%">
    <CheckboxDemo />
  </Tabs.Content>
  <Tabs.Content value="unstyled" justifyContent="center" alignItems="center" width="100%">
    <CheckboxDemo />
  </Tabs.Content>
  <Tabs.Content value="headless" justifyContent="center" alignItems="center" width="100%">
    <CheckboxHeadlessDemo />
  </Tabs.Content>
</HeroContainer>

<Tabs.Content value="styled">
```tsx hero template=Checkbox

```
</Tabs.Content>
<Tabs.Content value="unstyled">
```tsx hero template=Checkbox

```

</Tabs.Content>
  <Tabs.Content value="headless">
```tsx hero template=CheckboxHeadless

```
</Tabs.Content>

<Highlights
features={[
  `Indeterminate state support`,
  `Accessible, composable, and customizable`,
  `Sizing with controlled or uncontrolled state`,
  `Optional native HTML checkbox on web`,
]}
/>

## Installation

<Tabs.Content value="styled">
Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

</Tabs.Content>

<Tabs.Content value="unstyled">
Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

</Tabs.Content>

<Tabs.Content value="headless">

To use the headless checkbox, you want to import it from the
`@tamagui/checkbox-headless` package. This package has no dependency on
`@tamagui/core`, but still works off the react-native APIs.
This means you can bring your own style library.

```bash
npm install @tamagui/checkbox-headless
```

</Tabs.Content>

## Usage

<Tabs.Content value="styled">

```tsx
import { Check } from '@tamagui/lucide-icons-2'
import { Checkbox } from 'tamagui'

export default () => (
  <Checkbox size="4">
    <Checkbox.Indicator>
      <Check />
    </Checkbox.Indicator>
  </Checkbox>
)
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Use the `createCheckbox` export to create a fully custom checkbox that still
uses the Tamagui styling system. This is similar to setting `unstyled`, but goes
a bit further. It doesn't add any types for `size` or `unstyled`, and it won't
automatically apply the `active` theme. It does pass the `checked` prop down as
indicated in the types of `createCheckbox`.

```tsx template=Checkbox

```

</Tabs.Content>

<Tabs.Content value="headless">

Using the `useCheckbox` API, you can make your own Checkbox from scratch.

```tsx template=CheckboxHeadless

```

</Tabs.Content>

## API Reference

### Checkbox

`Checkbox` extend ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native checkbox input on web.`,
      default: false,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean | "indeterminate") => void',
      description: 'Callback that fires when the checkbox state is changed.',
    },
    {
      name: 'sizeAdjust',
      type: 'number',
      description: `Adjust the checkbox size scaling by this number.`,
    },
    {
      name: 'scaleIcon',
      type: 'number',
      description: `Scale the indicator icon more than usual by this number.`,
    },
    {
      name: 'scaleSize',
      type: 'number',
      default: '0.5',
      description: `The Tamagui size tokens should map to the height of a button at any given step. This means you want somewhat smaller checkboxes typically.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Checkbox.Indicator

`Checkbox.Indicator` extend ThemeableStack inheriting all the
[props](/docs/components/stacks#themeablestack), plus:

<PropsTable
  data={[
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Used to force mounting when more control is needed.`,
    },
    {
      name: 'disablePassStyles',
      required: false,
      type: 'boolean',
      description: `Used to disable passing styles down to children.`,
    },
  ]}
/>

</Tabs>


## components/checkbox/2.0.0

---
title: Checkbox
description: Toggle state in forms
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---

<HeroContainer showAnimationDriverControl>
  <CheckboxDemo />
</HeroContainer>

```tsx hero template=Checkbox

```

<Highlights
features={[
  `Indeterminate state support`,
  `Accessible, composable, and customizable`,
  `Sizing with controlled or uncontrolled state`,
  `Optional native HTML checkbox on web`,
]}
/>

## Installation

Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

## Usage

```tsx
import { Check } from '@tamagui/lucide-icons-2'
import { Checkbox } from 'tamagui'

export default () => (
  <Checkbox size="md">
    <Checkbox.Indicator>
      <Check />
    </Checkbox.Indicator>
  </Checkbox>
)
```

### Headless Usage

The `useCheckbox` hook provides all the state and accessibility props needed to build a custom checkbox with any styling solution:

```bash
npm install @tamagui/checkbox-headless
```

```tsx
import { useCheckbox } from '@tamagui/checkbox-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

function MyCheckbox({ defaultChecked, onCheckedChange, ...props }) {
  const [checked, setChecked] = useState(defaultChecked || false)

  const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
    props,
    [checked, setChecked],
    null
  )

  return (
    <>
      <Pressable
        ref={checkboxRef}
        {...checkboxProps}
        style={{
          width: 24,
          height: 24,
          borderRadius: 4,
          borderWidth: 2,
          borderColor: checked ? '#3b82f6' : '#d1d5db',
          backgroundColor: checked ? '#3b82f6' : 'transparent',
          justifyContent: 'center',
          alignItems: 'center',
        }}
      >
        {checked && <View style={{ width: 12, height: 12, backgroundColor: 'white' }} />}
      </Pressable>
      {bubbleInput}
    </>
  )
}
```

## API Reference

### Checkbox

`Checkbox` extends YStack inheriting all the
[props](/ui/stacks), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native checkbox input on web.`,
      default: false,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean | "indeterminate") => void',
      description: 'Callback that fires when the checkbox state is changed.',
    },
    {
      name: 'sizeAdjust',
      type: 'number',
      description: `Adjust the checkbox size scaling by this number.`,
    },
    {
      name: 'scaleIcon',
      type: 'number',
      description: `Scale the indicator icon more than usual by this number.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'activeStyle',
      required: false,
      type: `StylePiece`,
      description: `Styles to apply when the checkbox is checked. Accepts a style() piece.`,
    },
    {
      name: 'activeTheme',
      required: false,
      type: `string | null`,
      description: `Theme to apply when the checkbox is checked. Set to null for no theme change.`,
    },
  ]}
/>

### Checkbox.Indicator

`Checkbox.Indicator` extends YStack inheriting all the
[props](/ui/stacks), plus:

<PropsTable
  data={[
    {
      name: 'activeStyle',
      required: false,
      type: `StylePiece`,
      description: `Styles to apply when the indicator is active. Accepts a style() piece.`,
    },
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Used to force mounting when more control is needed.`,
    },
  ]}
/>

### useCheckbox

The `useCheckbox` hook accepts three arguments:

```tsx
const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
  props, // CheckboxProps
  state, // [checked: CheckedState, setChecked: (checked: CheckedState) => void]
  ref // React.Ref
)
```

#### CheckedState

The checkbox supports three states:

- `true` - checked
- `false` - unchecked
- `'indeterminate'` - indeterminate/mixed state (useful for "select all" patterns)

#### Props (first argument)

<PropsTable
  data={[
    {
      name: 'labelledBy',
      type: 'string',
      description: `Set aria-labelledby for accessibility.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Whether the checkbox is disabled.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Form input name for the hidden input.`,
    },
    {
      name: 'value',
      type: 'string',
      default: '"on"',
      description: `Form input value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Whether the checkbox is required in a form.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: CheckedState) => void',
      description: `Called when checked state changes.`,
    },
    {
      name: 'onPress',
      type: '(event) => void',
      description: `Called when checkbox is pressed (composed with internal handler).`,
    },
  ]}
/>

#### State (second argument)

A tuple of `[checked, setChecked]` where:

- `checked`: Current state (`boolean | 'indeterminate'`)
- `setChecked`: React state setter function

#### Return Value

| Property        | Type                | Description                                                                  |
| --------------- | ------------------- | ---------------------------------------------------------------------------- |
| `checkboxProps` | `object`            | Props to spread on your checkbox element (role, aria-checked, onPress, etc.) |
| `checkboxRef`   | `Ref`               | Composed ref to attach to your checkbox element                              |
| `bubbleInput`   | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only)            |



## components/checkbox/3.0.0

---
title: Checkbox
description: Toggle state in forms
name: checkbox
component: Checkbox
package: checkbox
demoName: Checkbox
---

<IntroParagraph>
  Checkbox provides accessible checked and indeterminate states with controlled
  or uncontrolled state on web and native.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <CheckboxDemo />
</HeroContainer>

```tsx hero template=Checkbox

```

<Highlights
  features={[
    `Indeterminate state support`,
    `Accessible, composable, and customizable`,
    `Sizing with controlled or uncontrolled state`,
    `Optional native HTML checkbox on web`,
  ]}
/>

## Installation

Checkbox is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/checkbox
```

## Usage

```tsx
import { Check } from './components/icons' // your generated icons, see Lucide Icons
import { Checkbox } from 'tamagui'

export default () => (
  <Checkbox size="md">
    <Checkbox.Indicator>
      <Check />
    </Checkbox.Indicator>
  </Checkbox>
)
```

### Headless usage

The `useCheckbox` hook provides all the state and accessibility props needed to build a custom checkbox with any styling solution:

```bash
npm install @tamagui/checkbox-headless
```

```tsx
import { useCheckbox } from '@tamagui/checkbox-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

function MyCheckbox({ defaultChecked, onCheckedChange, ...props }) {
  const [checked, setChecked] = useState(defaultChecked || false)

  const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
    props,
    [checked, setChecked],
    null
  )

  return (
    <>
      <Pressable
        ref={checkboxRef}
        {...checkboxProps}
        style={{
          width: 24,
          height: 24,
          borderRadius: 4,
          borderWidth: 2,
          borderColor: checked ? '#3b82f6' : '#d1d5db',
          backgroundColor: checked ? '#3b82f6' : 'transparent',
          justifyContent: 'center',
          alignItems: 'center',
        }}
      >
        {checked && <View style={{ width: 12, height: 12, backgroundColor: 'white' }} />}
      </Pressable>
      {bubbleInput}
    </>
  )
}
```

## API reference

### Checkbox

`Checkbox` extends View, inheriting all the
[View props](/docs/core/view-and-text). Sizes come from the shared
[Sizing](/docs/core/sizing) ladder.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: the box is the ladder's square derivation at the rung's radius.`,
    },
    {
      name: 'labelledBy',
      type: 'string',
      description: `Set the aria-labelledby attribute.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'native',
      type: 'boolean',
      description: `Renders native checkbox input on web.`,
      default: false,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean | "indeterminate") => void',
      description: 'Callback that fires when the checkbox state is changed.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'activeStyle',
      required: false,
      type: `StylePiece`,
      description: `Styles to apply when the checkbox is checked. Accepts a style() piece.`,
    },
    {
      name: 'activeTheme',
      required: false,
      type: `string | null`,
      description: `Theme to apply when the checkbox is checked. Set to null for no theme change.`,
    },
  ]}
/>

### Checkbox.Indicator

`Checkbox.Indicator` extends View, inheriting all the
[View props](/docs/core/view-and-text), plus:

<PropsTable
  data={[
    {
      name: 'activeStyle',
      required: false,
      type: `StylePiece`,
      description: `Styles to apply when the indicator is active. Accepts a style() piece.`,
    },
    {
      name: 'forceMount',
      required: false,
      type: `boolean`,
      description: `Used to force mounting when more control is needed.`,
    },
  ]}
/>

### useCheckbox

The `useCheckbox` hook accepts three arguments:

```tsx
const { checkboxProps, checkboxRef, bubbleInput } = useCheckbox(
  props, // CheckboxProps
  state, // [checked: CheckedState, setChecked: (checked: CheckedState) => void]
  ref // React.Ref
)
```

#### CheckedState

The checkbox supports three states:

- `true` - checked
- `false` - unchecked
- `'indeterminate'` - indeterminate/mixed state (useful for "select all" patterns)

#### Props (first argument)

<PropsTable
  data={[
    {
      name: 'labelledBy',
      type: 'string',
      description: `Set aria-labelledby for accessibility.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Whether the checkbox is disabled.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Form input name for the hidden input.`,
    },
    {
      name: 'value',
      type: 'string',
      default: '"on"',
      description: `Form input value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Whether the checkbox is required in a form.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: CheckedState) => void',
      description: `Called when checked state changes.`,
    },
    {
      name: 'onPress',
      type: '(event) => void',
      description: `Called when checkbox is pressed (composed with internal handler).`,
    },
  ]}
/>

#### State (second argument)

A tuple of `[checked, setChecked]` where:

- `checked`: Current state (`boolean | 'indeterminate'`)
- `setChecked`: React state setter function

#### Return value

| Property        | Type                | Description                                                                  |
| --------------- | ------------------- | ---------------------------------------------------------------------------- |
| `checkboxProps` | `object`            | Props to spread on your checkbox element (role, aria-checked, onPress, etc.) |
| `checkboxRef`   | `Ref`               | Composed ref to attach to your checkbox element                              |
| `bubbleInput`   | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only)            |


## components/progress/1.0.0

---
title: Progress
description: Display a bar to indicate percent completion.
name: progress
component: Progress
package: progress
demoName: Progress
---

# Progress

<Description>Show percent completion with a progress bar</Description>

<HeroContainer showAnimationDriverControl>
  <ProgressDemo />
</HeroContainer>

```tsx hero template=Progress

```

<Highlights
  features={[
    'Sizing, theming, and animation support',
    'Compound component API for full control',
    <span>
      <a href="https://www.w3.org/TR/wai-aria-1.2/#progressbar">
        ARIA progressbar role compliance
      </a>
    </span>,
  ]}
/>

## Installation

Progress is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/progress
```

## Usage

The `value` property controls the percent, but you can override it by adjusting the `x` property.

```tsx
import { Button, Progress } from 'tamagui'

export default () => (
  <Progress value={60}>
    <Progress.Indicator animation="bouncy" />
  </Progress>
)
```

## API Reference

### Progress

Progress extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: '"small" | "large"',
    },
    {
      name: 'value',
      required: false,
      type: 'number | null',
      description: `Control the percent progress.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
    },
  ]}
/>

### Progress.Indicator

`Progress.Indicator` extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props).


## components/progress/2.0.0

---
title: Progress
description: Show percent completion with a progress bar
name: progress
component: Progress
package: progress
demoName: Progress
---

<HeroContainer showAnimationDriverControl>
  <ProgressDemo />
</HeroContainer>

```tsx hero template=Progress

```

<Highlights
  features={[
    'Sizing, theming, and animation support',
    'Compound component API for full control',
    <span>
      <Link href="https://www.w3.org/TR/wai-aria-1.2/#progressbar">
        ARIA progressbar role compliance
      </Link>
    </span>,
  ]}
/>

## Installation

Progress is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/progress
```

## Usage

The `value` property controls the percent, but you can override it by adjusting the `x` property.

```tsx
import { Button, Progress } from 'tamagui'

export default () => (
  <Progress value={60}>
    <Progress.Indicator transition="bouncy" />
  </Progress>
)
```

## API Reference

### Progress

Progress extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: '"small" | "large"',
      description: `Size preset for the progress bar.`,
    },
    {
      name: 'value',
      required: false,
      type: 'number | null',
      description: `Controls the percent progress.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value for calculating the percentage.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true, removes all default styles.`,
    },
  ]}
/>

### Progress.Indicator

`Progress.Indicator` extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props).

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true, removes all default styles.`,
    },
  ]}
/>


## components/progress/3.0.0

---
title: Progress
description: Show percent completion with a progress bar
name: progress
component: Progress
package: progress
demoName: Progress
---

<IntroParagraph>
  Progress displays determinate completion with accessible values and
  independently styled track and indicator parts.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <ProgressDemo />
</HeroContainer>

```tsx hero template=Progress

```

<Highlights
  features={[
    'Sizing, theming, and animation support',
    'Compound component API for full control',
    <span>
      <Link href="https://www.w3.org/TR/wai-aria-1.2/#progressbar">
        ARIA progressbar role compliance
      </Link>
    </span>,
  ]}
/>

## Installation

Progress is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/progress
```

## Usage

The `value` property controls the percent, but you can override it by adjusting the `x` property.

```tsx
import { Button, Progress } from 'tamagui'

export default () => (
  <Progress value={60}>
    <Progress.Indicator transition="bouncy" />
  </Progress>
)
```

## API reference

### Progress

Progress extends [YStack](/ui/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: `'xs' | 'sm' | 'md' | 'lg' | 'xl' | SizeTokens | number`,
      description: `A named size ("xs" to "xl", default true which matches "md") is a row in the track height table; a size token or number keeps the historical quarter-scale height.`,
    },
    {
      name: 'value',
      required: false,
      type: 'number | null',
      description: `Controls the percent progress.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
      description: `Maximum value for calculating the percentage.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true, removes all default styles.`,
    },
  ]}
/>

### Progress.Indicator

`Progress.Indicator` extends [YStack](/ui/stacks), getting [Tamagui standard props](/docs/intro/props).

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true, removes all default styles.`,
    },
  ]}
/>


## components/progress/1.48.0

---
title: Progress
description: Show percent completion with a progress bar.
name: progress
component: Progress
package: progress
demoName: Progress
---

<HeroContainer showAnimationDriverControl>
  <ProgressDemo />
</HeroContainer>

```tsx hero template=Progress

```

<Highlights
  features={[
    'Sizing, theming, and animation support',
    'Compound component API for full control',
    <span>
      <Link href="https://www.w3.org/TR/wai-aria-1.2/#progressbar">
        ARIA progressbar role compliance
      </Link>
    </span>,
  ]}
/>

## Installation

Progress is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/progress
```

## Usage

The `value` property controls the percent, but you can override it by adjusting the `x` property.

```tsx
import { Button, Progress } from 'tamagui'

export default () => (
  <Progress value={60}>
    <Progress.Indicator animation="bouncy" />
  </Progress>
)
```

## API Reference

### Progress

Progress extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: '"small" | "large"',
    },
    {
      name: 'value',
      required: false,
      type: 'number | null',
      description: `Control the percent progress.`,
    },
    {
      name: 'max',
      required: false,
      type: 'number',
    },
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true will remove all default styles`,
    },
  ]}
/>

### Progress.Indicator

`Progress.Indicator` extends [ThemeableStack](/docs/components/stacks#themeablestack), getting [Tamagui standard props](/docs/intro/props).

<PropsTable
  data={[
    {
      name: 'unstyled',
      required: false,
      type: 'boolean',
      description: `When true will remove all default styles`,
    },
  ]}
/>


## components/z-index/2.0.0

---
title: Stacking (zIndex)
description: How Tamagui automatically stacks overlays and floating content
name: z-index
---

<IntroParagraph>
  Tamagui automatically stacks dialogs, popovers, sheets, tooltips, and nested
  overlays in the order they open.
</IntroParagraph>

## How it works

When you open overlay components, Tamagui automatically assigns z-index values so that:

- **Later-opened content appears above earlier content** - Open two dialogs? The second one stacks above the first.
- **Nested content appears above its parent** - A tooltip inside a dialog automatically renders above the dialog.
- **Closing restores order** - When content closes, z-index values are reclaimed.

This means you typically don't need to think about z-index at all.

## When to set zIndex

Only set `zIndex` when you need to override the automatic stacking. Common cases:

- **Fixed headers/footers** - If you have a sticky header at `z-index: 100`, overlays need to appear above it (they do by default).
- **Third-party libraries** - If integrating with libraries that use high z-index values.
- **Custom stacking requirements** - When you need specific layering that differs from open-order.

```tsx
// Only if you need to override automatic stacking
<Dialog zIndex={200000}>
  ...
</Dialog>
```

## Component defaults

All overlay components use the automatic stacking system. Here's where to set `zIndex` if needed:

| Component | Where to set zIndex |
|-----------|---------------------|
| [Dialog](/ui/dialog) | `<Dialog zIndex={...}>` |
| [AlertDialog](/ui/alert-dialog) | `<AlertDialog zIndex={...}>` |
| [Sheet](/ui/sheet) | `<Sheet zIndex={...}>` |
| [Select](/ui/select) | `<Select zIndex={...}>` |
| [Popover](/ui/popover) | `<Popover zIndex={...}>` |
| [Tooltip](/ui/tooltip) | `<Tooltip zIndex={...}>` |
| [Menu](/ui/menu) | `<Menu.Portal zIndex={...}>` |
| [ContextMenu](/ui/context-menu) | `<ContextMenu.Portal zIndex={...}>` |
| [Toast](/ui/toast) | Via `position` on `<Toast>` |

## Stacking hierarchy

By default, components stack in this order (lowest to highest):

1. **Popover, Tooltip, Menu** - pure auto-stacking from a low base
2. **Dialog, AlertDialog, Select, Sheet** - add a 100000 base to ensure they appear above most UI

Within each category, **mount order determines stacking** - open a popover, then another, the second is on top.

## Nested stacking

Nested floating elements automatically stack above their parent:

```tsx
<Dialog>
  <Dialog.Content>
    {/* This tooltip will appear above the dialog */}
    <Tooltip>
      <Tooltip.Trigger>
        <Button>Hover me</Button>
      </Tooltip.Trigger>
      <Tooltip.Content>
        I appear above the dialog!
      </Tooltip.Content>
    </Tooltip>
  </Dialog.Content>
</Dialog>
```

The system tracks parent-child relationships through React context, so nested portals always stack correctly.

## Technical details

The stacking system uses two mechanisms:

### Horizontal stacking (siblings)

When multiple overlays open at the same level, each gets an incrementing z-index:
- First dialog: 100001
- Second dialog: 100002
- Third dialog: 100003

### Vertical stacking (nested)

When content opens inside another portal, it reads the parent's z-index from context and adds 1:
- Dialog opens at 100001
- Popover inside dialog: 100002
- Tooltip inside that popover: 100003

This ensures nested content is always visible above its parent, but sibling content opened later can still stack above.

## Portal component

The [Portal](/ui/portal) component powers this stacking system. If building custom overlay components, you can use Portal's `stackZIndex` prop:

```tsx
import { Portal } from 'tamagui'

// Enable automatic stacking
<Portal stackZIndex>
  {/* content */}
</Portal>

// Or use a high base value (like Dialog does)
<Portal stackZIndex={100000}>
  {/* content */}
</Portal>
```

See the [Portal documentation](/ui/portal) for more details.


## components/shapes/1.0.0

---
title: Shapes
description: Easy to use Square and Circle.
name: shapes
component: Square
package: shapes
demoName: Shapes
---

<HeroContainer>
  <ShapesDemo />
</HeroContainer>

```tsx hero template=Shapes

```

<Highlights
  features={[
    'Numeric or token-based sizes',
    'Minimum and maximum width and height',
  ]}
/>

## Installation

Shapes is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/shapes
```

## Usage

Tamagui supports sizing shapes using your `size` tokens, or plain numbers.

```tsx
import { Circle, Square } from 'tamagui'

export default () => (
  <>
    <Square size="4" />
    <Square size={100} />
    <Circle size="4" />
    <Circle size={100} />
  </>
)
```

## API Reference

### Square

`Square` extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'circular',
      required: false,
      type: 'boolean',
      description: `Rounds the border radius to be circular.`,
    },
  ]}
/>

### Circle

`Circle` extends [Square](#square), setting `circular` to `true`.


## components/shapes/2.0.0

---
title: Shapes
description: Easy to use Square and Circle
name: shapes
component: Square
package: shapes
demoName: Shapes
---

<IntroParagraph>
  Square and Circle turn one size value into matching width and height with full
  Tamagui styling.
</IntroParagraph>

<HeroContainer>
  <ShapesDemo />
</HeroContainer>

```tsx hero template=Shapes

```

<Highlights
  features={[
    'Numeric or token-based sizes',
    'Minimum and maximum width and height',
  ]}
/>

## Installation

Shapes is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/shapes
```

## Usage

Tamagui supports sizing shapes using your `size` tokens, or plain numbers.

```tsx
import { Circle, Square } from 'tamagui'

export default () => (
  <>
    <Square size="4" />
    <Square size={100} />
    <Circle size="4" />
    <Circle size={100} />
  </>
)
```

## API reference

### Square

Square extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens | number',
      description: `A number is px, a string is a size token key.`,
    },
    {
      name: 'circular',
      required: false,
      type: 'boolean',
      description: `Rounds the border radius to be circular.`,
    },
  ]}
/>

### Circle

Circle extends [Square](#square), setting `circular` to `true`.


## components/button/1.0.0

---
title: Button
description: A simple button component
name: button
component: Button
package: button
demoName: Button
---

# Button

<Description>A simple, sizable button.</Description>

<HeroContainer demoMultiple>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Inverse themes with themeInverse',
    'Icons before or after content',
  ]}
/>

### Usage

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

### Sizing

Sizing buttons provides a unique challenge especially for a compiler, because you need to adjust many different properties - not just on the outer frame, but on the text wrapped inside. Tamagui supports adjusting the padding, border radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="6">Lorem ipsum</Button>
```

Given your theme defines a size `6`, the button will adjust all of the properties appropriately. You can also pass a plain number to get an arbitrary size.

### Icon Theming

You can pass icons as either elements or components. If passing components, Tamagui will automatically pass the `size` and `color` prop to them based on your theme.

You can [use the source of Button itself](https://github.com/tamagui/tamagui/blob/v2/code/ui/button/src/Button.tsx) to see in more detail what variants you can override, and how we use this pattern internally to create our Button component.

### Customization (Advanced)

Button only supports a limited subset of text props directly. If you need more control over state-specific text values, customize its text component with flat clauses.

Please note that this pattern is a bit antithetical to the multiple-components APIs that Tamagui generally prefers. In a future release we hope to fix this, but that change should be easy to migrate to.

```tsx
import { forwardRef } from 'react'
import {
  ButtonFrame,
  ButtonText,
  GetProps,
  ButtonProps as TamaguiButtonProps,
  styled,
  themeable,
  useButton,
} from 'tamagui'

const CustomButtonFrame = styled(ButtonFrame, {
  // ...
})

const CustomButtonText = styled(ButtonText, {
  // ...
})

// to capture the custom variant types you define
type CustomButtonFrameProps = GetProps<typeof CustomButtonFrame>
type CustomButtonTextProps = GetProps<typeof CustomButtonText>

export type CustomButtonProps = TamaguiButtonProps &
  CustomButtonFrameProps &
  CustomButtonTextProps

export const Button = CustomButtonFrame.styleable<CustomButtonProps>((propsIn, ref) => {
  const { props } = useButton(propsIn, { Text: CustomButtonText })
  return <CustomButtonFrame {...props} ref={ref} />
})
```

### Button props

Buttons extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, Button won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon more than usual by this number.`,
    },
    {
      name: 'scaleSpace',
      required: false,
      type: 'number',
      description: `Scale the spacing more than usual by this number.`,
    },
    {
      name: 'spaceFlex',
      required: false,
      type: `boolean`,
      description: `Makes all space elements have a flex.`,
    },
    {
      name: 'color',
      required: false,
      type: `SizableTextProps['color']`,
      description: `Passes "color" down to the inner text component`,
    },
    {
      name: 'fontWeight',
      required: false,
      type: `SizableTextProps['fontWeight']`,
      description: `Passes "fontWeight" down to the inner text component`,
    },
    {
      name: 'letterSpacing',
      required: false,
      type: `SizableTextProps['letterSpacing']`,
      description: `Passes "letterSpacing" down to the inner text component`,
    },
    {
      name: 'textAlign',
      required: false,
      type: `SizableTextProps['textAlign']`,
      description: `Passes "textAlign" down to the inner text component`,
    },
    {
      name: 'circular',
      required: false,
      type: `boolean`,
      description: `Forces a circular button.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/button/1.0.0-alpha

---
title: Button
description: A simple button component
name: button
component: Button
demoName: Button
---

# Button

<Description>A simple, sizable button.</Description>

<HeroContainer>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Inverse themes with themeInverse',
    'Icons before or after content',
  ]}
/>

### Usage

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

### Sizing

Sizing buttons provides a unique challenge especially for a compiler, because
you need to adjust many different properties - not just on the outer frame, but
on the text wrapped inside. Tamagui supports adjusting the padding, border
radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="6">Lorem ipsum</Button>
```

Given your theme defines a size `6`, the button will adjust all of the
properties appropriately. You can also pass a plain number to get an arbitrary
size.

### Icon Theming

You can pass icons as either elements or components. If passing components,
Tamagui will automatically pass the `size` and `color` prop to them based on
your theme.

### Button props

Button extends View, inheriting all the
[Tamagui standard props](/docs/intro/props), adding:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'textProps',
      required: false,
      type: 'TextProps',
      description: `By default a button wraps contents in Text and will pass textProps if set.`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, Button won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
  ]}
/>


## components/button/1.28.0

---
title: Button
description: An incredibly flexible button.
name: button
component: Button
package: button
demoName: Button
---

<HeroContainer demoMultiple>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Inverse themes with themeInverse',
    'Icons before or after content',
  ]}
/>

## Usage

When using the simple Button API, it's as simple as this:

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

### Sizing

Sizing buttons provides a unique challenge especially for a compiler, because you need to adjust many different properties - not just on the outer frame, but on the text wrapped inside. Tamagui supports adjusting the padding, border radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="6">Lorem ipsum</Button>
```

Given your theme defines a size `6`, the button will adjust all of the properties appropriately. You can also pass a plain number to get an arbitrary size.

### Icon Theming

You can pass icons as either elements or components. If passing components, Tamagui will automatically pass the `size` and `color` prop to them based on your theme.

You can [use the source of Button itself](https://github.com/tamagui/tamagui/blob/main/code/ui/button/src/Button.tsx) to see in more detail what variants you can override, and how we use this pattern internally to create our Button component.

### Creating your own Button

Tamagui now has all the features necessary to make creating a custom Button easy enough that you may want to roll your own button. Learn how to do it with our dedicated guide, [How to Build a Button](/docs/guides/how-to-build-a-button).

<Notice>
  The previous `useButton` API is deprecated and will be removed in a future version. It's
  brittle and is easily replaced with the new compound component APIs as described in the
  guide.
</Notice>

## API Reference

### Button

Buttons extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, Button won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon more than usual by this number.`,
    },
    {
      name: 'scaleSpace',
      required: false,
      type: 'number',
      description: `Scale the spacing more than usual by this number.`,
    },
    {
      name: 'spaceFlex',
      required: false,
      type: `boolean`,
      description: `Makes all space elements have a flex.`,
    },
    {
      name: 'color',
      required: false,
      type: `SizableTextProps['color']`,
      description: `Passes "color" down to the inner text component`,
    },
    {
      name: 'fontWeight',
      required: false,
      type: `SizableTextProps['fontWeight']`,
      description: `Passes "fontWeight" down to the inner text component`,
    },
    {
      name: 'letterSpacing',
      required: false,
      type: `SizableTextProps['letterSpacing']`,
      description: `Passes "letterSpacing" down to the inner text component`,
    },
    {
      name: 'textAlign',
      required: false,
      type: `SizableTextProps['textAlign']`,
      description: `Passes "textAlign" down to the inner text component`,
    },
    {
      name: 'circular',
      required: false,
      type: `boolean`,
      description: `Forces a circular button.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>


## components/button/2.0.0

---
title: Button
description: A simple button component
name: button
component: Button
package: button
demoName: Button
---

<HeroContainer demoMultiple>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Icons before or after content',
    'Explicit icon sizing with `iconSize`',
    'Button group theming with `Button.Apply`',
  ]}
/>

## Installation

Button is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/button
```

## Usage

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

## Sizing

Sizing buttons provides a unique challenge especially for a compiler, because
you need to adjust many different properties - not just on the outer frame, but
on the text wrapped inside. Tamagui supports adjusting the padding, border
radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="6">Lorem ipsum</Button>
```

Given your theme defines a size `6`, the button will adjust all of the
properties appropriately. You can also pass a plain number to get an arbitrary
size.

## Variants

The Button component supports different visual styles through the `variant`
prop. Currently, the primary available variant is `"outlined"`.

```tsx
import { Button, XStack } from 'tamagui'

export default () => (
  <XStack gap="2">
    <Button>Default</Button>
    <Button variant="outlined">Outlined</Button>
  </XStack>
)
```

When `variant="outlined"` is applied, the button typically has a transparent
background with a visible border. The exact appearance (border color,
hover/press states) is determined by your theme's definitions for an outlined
button.

## Icon Theming

You can pass icons as either elements or components. If passing components,
Tamagui will automatically theme them (passing `size`). The icon size is
determined by the Button's `size` prop by default.

You can also explicitly set the icon size using the `iconSize` prop, which
accepts a `SizeTokens` value (e.g., `"2"`). The `scaleIcon` prop can be used to
further adjust the size relative to the determined or explicitly set icon size.

When an icon is present, Tamagui automatically adds spacing between the icon and
the button's text using the CSS `gap` property on the Button frame. The gap is
derived from the Button's `size` token value, keeping spacing consistent with
the overall button dimensions.

```tsx
import { Button, Star } from 'tamagui'

export default () => (
  <>
    <Button icon={Star} size="5">
      Icon sized by Button
    </Button>
    <Button icon={Star} iconSize="2" size="5">
      Icon sized explicitly
    </Button>
  </>
)
```

You can
[use the source of Button itself](https://github.com/tamagui/tamagui/blob/v2/code/ui/button/src/Button.tsx)
to see in more detail what variants you can override, and how we use this
pattern internally to create our Button component.

## Group Theming

You can use `Button.Apply` to theme a group of Buttons using a shared context.
This is useful for applying consistent sizing or variants to multiple buttons
without passing props to each one individually.

```tsx
import { Button, ButtonDemo, YStack } from 'tamagui'

export default () => (
  <YStack gap="4">
    <Button.Apply size="2" variant="outlined">
      <Button>Small Outlined 1</Button>
      <Button>Small Outlined 2</Button>
      <Button icon={Star}>With Icon</Button>
    </Button.Apply>

    <Button.Apply size="5">
      <Button>Large 1</Button>
      <Button theme="blue">Large Themed</Button>
    </Button.Apply>
  </YStack>
)
```

## Web Form Props

Button supports all standard HTML `<button>` attributes for form integration.
These props are web-only and ignored on native:

```tsx
import { Button, Form } from 'tamagui'

export default () => (
  <Form action="/submit">
    <Button type="submit">Submit Form</Button>
    <Button type="reset">Reset</Button>
    <Button type="button">Regular Button (default)</Button>

    {/* Override form attributes */}
    <Button type="submit" formAction="/alternative-endpoint" formMethod="post">
      Submit to Different Endpoint
    </Button>
  </Form>
)
```

<Notice>
  Button defaults to `type="button"` to prevent unintended form submissions. Use
  `type="submit"` explicitly when you want form submission behavior.
</Notice>

## Text Styling

**Changed from v1:** In v1, you could pass text style props like `color`,
`fontSize`, `fontWeight`, `fontFamily`, and `letterSpacing` directly to
`<Button>` and they would be forwarded to the button's text via context. In v2,
this is no longer supported — Button's frame is a `View` and text style props
passed to it are ignored.

To customize text appearance, use `Button.Text` explicitly:

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button>
    <Button.Text color="blue" fontSize="5" fontWeight="bold">
      Styled text
    </Button.Text>
  </Button>
)
```

### Interactive Text Styles

Combine `Button.Text` with the `group` prop on Button to coordinate text
styles across hover, press, and focus states:

<MDXTabs id="button-2-interactive-syntax" defaultValue="styled">
<MDXTabs.List>
  <MDXTabs.Tab value="styled">Typed</MDXTabs.Tab>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="styled">

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button group="btn" bg="pink">
    <Button.Text color={{ default: 'blue', 'group-hover/btn': 'red' }}>
      Hello world
    </Button.Text>
  </Button>
)
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button group="btn" bg="pink">
    <Button.Text color="blue group-hover/btn:red">
      Hello world
    </Button.Text>
  </Button>
)
```

</MDXTabs.Content>
</MDXTabs>

The `group` prop lets any child reference <span className="show-sm-inline">all of Tamagui's </span>interactive states like
`group-hover/btn`, `group-press/btn`, and `group-focus/btn` for
precise styling per interaction state.

## Creating Your Own Button

Tamagui now has all the features necessary to make creating a custom Button easy
enough that you may want to roll your own button. Learn how to do it with our
dedicated guide, [How to Build a Button](/docs/guides/how-to-build-a-button).

## API Reference

Buttons extend View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'SizeTokens | number',
      description: `Set a size from your theme's size tokens (e.g., "4") or a specific number. Adjusts padding, font size, and icon sizes.`,
    },
    {
      name: 'variant',
      required: false,
      type: '"outlined" | undefined',
      description: 'Applies the "outlined" button style.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description:
        'If true, the button will be non-interactive and visually disabled. Sets `pointerEvents: "none"`.',
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and its children.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'React.ReactNode | React.ComponentType<{ color?: string, size?: number }>',
      description: `Pass any React element or a component. Appears before the text. If a component is passed, 'color' and 'size' props are passed to it.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'React.ReactNode | React.ComponentType<{ color?: string, size?: number }>',
      description: `Pass any React element or a component. Appears after the text. If a component is passed, 'color' and 'size' props are passed to it.`,
    },
    {
      name: 'iconSize',
      required: false,
      type: 'SizeTokens',
      description: `Explicitly set the size of the icon, overriding the default size derived from the Button's 'size' prop. Uses theme size tokens (e.g., "2").`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon by this factor. Default is 1. Applied after 'iconSize' or the default size calculation.`,
    },
    {
      name: 'circular',
      required: false,
      type: `boolean`,
      description: `Forces a circular button. Applies border radius to make the button a circle.`,
    },
    {
      name: 'chromeless',
      required: false,
      type: 'boolean | "all"',
      description:
        'Removes default Tamagui visual styles (background, border) for a more minimal appearance, while keeping layout and interactions. If "all", removes hover/press/focus styles too.',
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all Tamagui default styles, including layout, interactions, and accessibility attributes. Prefer 'chromeless' for removing only visual styles.`,
    },
    // Web-only form props
    {
      name: '// Web Form Props',
      description:
        'The following props are web-only and provide full HTML button form semantics. They are ignored on native.',
      type: '---',
    },
    {
      name: 'type',
      required: false,
      type: '"button" | "submit" | "reset"',
      description:
        'Web-only. The button type. Defaults to "button" to prevent unintended form submissions.',
    },
    {
      name: 'form',
      required: false,
      type: 'string',
      description: 'Web-only. The ID of the form element the button is associated with.',
    },
    {
      name: 'formAction',
      required: false,
      type: 'string',
      description: "Web-only. URL for form submission, overrides the form's action.",
    },
    {
      name: 'formMethod',
      required: false,
      type: '"get" | "post"',
      description: 'Web-only. HTTP method for form submission.',
    },
    {
      name: 'formEncType',
      required: false,
      type: 'string',
      description: 'Web-only. Encoding type for form data.',
    },
    {
      name: 'formNoValidate',
      required: false,
      type: 'boolean',
      description: 'Web-only. Bypass form validation when submitting.',
    },
    {
      name: 'formTarget',
      required: false,
      type: 'string',
      description: 'Web-only. Where to display form response (_self, _blank, etc).',
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: 'Web-only. Name submitted with form data.',
    },
    {
      name: 'value',
      required: false,
      type: 'string',
      description: 'Web-only. Value submitted with form data.',
    },
    {
      name: 'popoverTarget',
      required: false,
      type: 'string',
      description: 'Web-only. ID of popover element to control.',
    },
    {
      name: 'popoverTargetAction',
      required: false,
      type: '"hide" | "show" | "toggle"',
      description: 'Web-only. Action to perform on the popover.',
    },
    // Note about text styling
    {
      name: '// Text Styling',
      description:
        'Button does not support `color` directly. To style text color, use `Button.Text` with the `group` prop for interactive states. See the Text Styling section above.',
      type: '---',
    },
  ]}
/>


## components/button/3.0.0

---
title: Button
description: A pressable button with sizing, icons, and themes
name: button
component: Button
package: button
demoName: Button
---

<IntroParagraph>
  Button combines accessible press behavior with shared sizing, icons, themes,
  and full HTML form semantics.
</IntroParagraph>

<HeroContainer demoMultiple>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Icons before or after content',
    'Explicit icon sizing with `iconSize`',
    'Full HTML button form semantics',
  ]}
/>

## Installation

Button is already installed in `tamagui`:

```tsx
import { Button } from 'tamagui'
```

`@tamagui/button` holds the unstyled half: `useButton` and the parts, with no
styled `Button` of its own. Import from it when you are building your own button
rather than using ours; see [Build your own](#build-your-own).

## Usage

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

## Sizing

Sizing a button means adjusting many properties at once, not just on the outer
frame but on the text inside it. Tamagui adjusts padding, border radius, font
size, and icon size together with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="lg">Lorem ipsum</Button>
```

Each name is a rung in the shared [Sizing](/docs/core/sizing) ladder (`xs`
through `xl`, default `md`), so the frame, its text, and its icon agree by
construction.

## Variants

The `variant` prop selects a visual style. Tamagui ships `outlined` (transparent
background with a visible border) and `quiet` (no background, no border).

```tsx
import { Button, XStack } from 'tamagui'

export default () => (
  <XStack gap="2">
    <Button>Default</Button>
    <Button variant="outlined">Outlined</Button>
    <Button variant="quiet">Quiet</Button>
  </XStack>
)
```

## Icon theming

You can pass icons as either elements or components. If passing components,
Tamagui themes them, passing `size` and `color`. The icon size comes from the
Button's `size` prop by default.

Set the icon size explicitly with `iconSize` (pixels, e.g. `{18}`).
`scaleIcon` adjusts it further, relative to whichever size was resolved.

Spacing between an icon and the text comes from `gap` on the button frame,
derived from the `size` table so it stays consistent with the button's
dimensions.

```tsx
import { Button } from 'tamagui'
import { Star } from './components/icons' // your generated icons, see Lucide Icons

export default () => (
  <>
    <Button icon={Star} size="lg">
      Icon sized by Button
    </Button>
    <Button icon={Star} iconSize={18} size="lg">
      Icon sized explicitly
    </Button>
  </>
)
```

## Web form props

Button supports the standard HTML `<button>` attributes for form integration.
These are web-only and ignored on native:

```tsx
import { Button, Form } from 'tamagui'

export default () => (
  <Form action="/submit">
    <Button type="submit">Submit Form</Button>
    <Button type="reset">Reset</Button>
    <Button type="button">Regular Button (default)</Button>

    {/* Override form attributes */}
    <Button type="submit" formAction="/alternative-endpoint" formMethod="post">
      Submit to Different Endpoint
    </Button>
  </Form>
)
```

<Notice>
  Button defaults to `type="button"` to prevent unintended form submissions. Use
  `type="submit"` explicitly when you want form submission behavior.
</Notice>

## Text styling

Button's frame is a `View`, so text style props passed to it are ignored. The one
exception is `fontFamily`, which forwards to the wrapped text, since a font family
is a base value and needs no conditional resolution.

Everything else goes on `Button.Text`:

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button>
    <Button.Text color="blue" fontSize="5" fontWeight="bold">
      Styled text
    </Button.Text>
  </Button>
)
```

### Interactive text styles

Combine `Button.Text` with the `group` prop on Button to coordinate text styles
across hover, press, and focus states:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button group="btn" backgroundColor="pink">
    <Button.Text color={{ default: 'blue', 'group-hover/btn': 'red' }}>Hello world</Button.Text>
  </Button>
)
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
import { Button } from 'tamagui'

export default () => (
  <Button group="btn" backgroundColor="pink">
    <Button.Text color="blue group-hover/btn:red">Hello world</Button.Text>
  </Button>
)
```

</MDXTabs.Content>
</MDXTabs>

The `group` prop lets any child reference <span className="show-sm-inline">all of Tamagui's </span>interactive states like
`group-hover/btn`, `group-press/btn`, and `group-focus/btn` for precise styling
per interaction state.

## Build your own

No two buttons are alike, so `@tamagui/button` ships the behavior and the parts
rather than a finished component. `useButton` themes the icon props, wraps bare
children in a text, and handles the html nesting rules; the skin is yours. This is
how `tamagui`'s own Button is built:

```tsx
import {
  ButtonFrame as ButtonBehaviorFrame,
  ButtonText as ButtonBehaviorText,
  createStyledContext,
  createStyledHOC,
  styled,
  useButton,
  withStaticProperties,
} from '@tamagui/ui'

const ButtonContext = createStyledContext<{ size?: 'sm' | 'md' | 'lg' }>({
  size: 'md',
})

const ButtonFrame = styled(ButtonBehaviorFrame, {
  context: ButtonContext,
  backgroundColor: 'background hover:background-hover press:background-press',
  borderColor: 'border-color hover:border-color-hover',
  borderWidth: 1,
  cursor: 'web:pointer',
})

const ButtonText = styled(ButtonBehaviorText, {
  context: ButtonContext,
  color: 'color',
  fontWeight: '600',
})

const ButtonComponent = createStyledHOC(ButtonFrame, function Button(props, ref) {
  const { props: buttonProps } = useButton(props, { Text: ButtonText })
  return <ButtonFrame ref={ref} {...buttonProps} />
})

export const Button = withStaticProperties(ButtonComponent, {
  Frame: ButtonFrame,
  Text: ButtonText,
})
```

Because the frame declares `ButtonContext`, passing `size` to it is what
publishes it to the text and icons below. Each component owns its context;
there is no shared size context.

`useButton` also reads `ButtonNestingContext`, which is how a Button inside
another Button (a `Dialog.Trigger` inside a toolbar button, say) renders as a
`span` instead of nesting an invalid `<button>` inside a `<button>`.

For a longer walkthrough see
[How to Build a Button](/docs/guides/how-to-build-a-button).

## API reference

Button extends View, inheriting all the
[Tamagui standard props](/docs/intro/props). Sizes come from the shared
[Sizing](/docs/core/sizing) ladder.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: padding, border radius, font size, and icon size, never a height. Published to Button.Text and Button.Icon through the Button context.`,
    },
    {
      name: 'variant',
      required: false,
      type: '"outlined" | "quiet"',
      description:
        '"outlined" is transparent with a border, "quiet" is transparent with no border.',
    },
    {
      name: 'circular',
      required: false,
      type: 'boolean',
      description: 'Forces a square frame with a fully rounded border radius.',
    },
    {
      name: 'disabled',
      required: false,
      type: 'boolean',
      description:
        'Dims the button and sets `pointerEvents: "none"`. On web it also renders a disabled `<button>` and sets `aria-disabled`.',
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and its children.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'React.ReactNode | React.ComponentType<{ color?: string, size?: number }>',
      description: `Any React element or a component. Appears before the text. A component receives 'color' and 'size'.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'React.ReactNode | React.ComponentType<{ color?: string, size?: number }>',
      description: `Any React element or a component. Appears after the text. A component receives 'color' and 'size'.`,
    },
    {
      name: 'iconSize',
      required: false,
      type: 'number',
      description: `Explicitly set the icon size in pixels, overriding the one derived from 'size'.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon by this factor. Default is 1, applied after 'iconSize' or the default size calculation.`,
    },
    {
      name: 'fontFamily',
      required: false,
      type: 'string',
      description:
        'The one text style prop the frame forwards, since a font family does not vary per breakpoint. Every other text style belongs on `Button.Text`.',
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description:
        'Render children as given instead of wrapping bare text in a `Button.Text`.',
    },
    // Web-only form props
    {
      name: '// Web Form Props',
      description:
        'The following props are web-only and provide full HTML button form semantics. They are ignored on native.',
      type: '---',
    },
    {
      name: 'type',
      required: false,
      type: '"button" | "submit" | "reset"',
      description:
        'Web-only. The button type. Defaults to "button" to prevent unintended form submissions.',
    },
    {
      name: 'form',
      required: false,
      type: 'string',
      description: 'Web-only. The ID of the form element the button is associated with.',
    },
    {
      name: 'formAction',
      required: false,
      type: 'string',
      description: "Web-only. URL for form submission, overrides the form's action.",
    },
    {
      name: 'formMethod',
      required: false,
      type: '"get" | "post"',
      description: 'Web-only. HTTP method for form submission.',
    },
    {
      name: 'formEncType',
      required: false,
      type: 'string',
      description: 'Web-only. Encoding type for form data.',
    },
    {
      name: 'formNoValidate',
      required: false,
      type: 'boolean',
      description: 'Web-only. Bypass form validation when submitting.',
    },
    {
      name: 'formTarget',
      required: false,
      type: 'string',
      description: 'Web-only. Where to display form response (_self, _blank, etc).',
    },
    {
      name: 'name',
      required: false,
      type: 'string',
      description: 'Web-only. Name submitted with form data.',
    },
    {
      name: 'value',
      required: false,
      type: 'string',
      description: 'Web-only. Value submitted with form data.',
    },
    // Note about text styling
    {
      name: '// Text Styling',
      description:
        'Apart from `fontFamily`, Button does not forward text style props. Use `Button.Text`, with the `group` prop for interactive states. See the Text Styling section above.',
      type: '---',
    },
  ]}
/>

### Button.Frame

The button's `View`. Renders as `<button type="button">` on web with
`role="button"`.

### Button.Text

The text the button wraps bare children in, and what you use to style the label.
Extends `SizableText`.

### Button.Icon

Sizes and colors an icon from the surrounding size context. Used for the `icon`
and `iconAfter` props, and available for your own compositions.

### useButton

Themes the `icon` and `iconAfter` props, wraps bare children in a text, and
applies the html nesting rules. Returns the props to spread onto a frame, with the
ones it consumed removed and everything else untouched.

```tsx
const { isNested, props } = useButton(props, { Text: MyButtonText })
```


## components/button/1.0.0-beta.0

---
title: Button
description: A simple button component
name: button
component: Button
demoName: Button
---

# Button

<Description>A simple, sizable button.</Description>

<HeroContainer demoMultiple>
  <ButtonDemo />
</HeroContainer>

```tsx hero template=Button

```

<Highlights
  features={[
    'One size prop for all styles',
    'Inverse themes with themeInverse',
    'Icons before or after content',
  ]}
/>

### Usage

```tsx
import { Button } from 'tamagui'

export default () => <Button>Lorem ipsum</Button>
```

### Sizing

Sizing buttons provides a unique challenge especially for a compiler, because
you need to adjust many different properties - not just on the outer frame, but
on the text wrapped inside. Tamagui supports adjusting the padding, border
radius, font size and icons sizes all in one with the `size` prop.

```tsx
import { Button } from 'tamagui'

export default () => <Button size="6">Lorem ipsum</Button>
```

Given your theme defines a size `6`, the button will adjust all of the
properties appropriately. You can also pass a plain number to get an arbitrary
size.

### Icon Theming

You can pass icons as either elements or components. If passing components,
Tamagui will automatically pass the `size` and `color` prop to them based on
your theme.

### Button props

Button extends View, inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: 'string | tokens.size',
      description: `Set a size, number or one of the size token values.`,
    },
    {
      name: 'theme',
      required: false,
      type: 'string',
      description: `Apply a theme just to the button and it's children`,
    },
    {
      name: 'themeInverse',
      required: false,
      type: 'boolean',
      description: `Helpful for "flipping" any theme between dark and light (including flipping a sub themes defined as [subtheme]-[dark/light]`,
    },
    {
      name: 'noTextWrap',
      required: false,
      type: 'boolean',
      description: `If true, Button won't wrap content with a Text element.`,
    },
    {
      name: 'icon',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears before the text.`,
    },
    {
      name: 'iconAfter',
      required: false,
      type: 'JSX.Element',
      description: `Pass any React element, appears after the text.`,
    },
    {
      name: 'scaleIcon',
      required: false,
      type: 'number',
      description: `Scale the icon more than usual by this number.`,
    },
    {
      name: 'scaleSpace',
      required: false,
      type: 'number',
      description: `Scale the spacing more than usual by this number.`,
    },
    {
      name: 'spaceFlex',
      required: false,
      type: `boolean`,
      description: `Makes all space elements have a flex.`,
    },
    {
      name: 'color',
      required: false,
      type: `SizableTextProps['color']`,
      description: `Passes "color" down to the inner text component`,
    },
    {
      name: 'fontWeight',
      required: false,
      type: `SizableTextProps['fontWeight']`,
      description: `Passes "fontWeight" down to the inner text component`,
    },
    {
      name: 'letterSpacing',
      required: false,
      type: `SizableTextProps['letterSpacing']`,
      description: `Passes "letterSpacing" down to the inner text component`,
    },
    {
      name: 'textAlign',
      required: false,
      type: `SizableTextProps['textAlign']`,
      description: `Passes "textAlign" down to the inner text component`,
    },
  ]}
/>


## components/linear-gradient/1.0.0

---
title: Linear Gradient
description: Linear gradients that work with Tamagui style props
name: html
component: LinearGradient
demoName: LinearGradient
---

<HeroContainer>
  <LinearGradientDemo />
</HeroContainer>

```tsx hero template=LinearGradient

```

<Highlights
  features={[
    'Native and web support',
    'Tamagui style props and theme colors',
    'Webpack bundling support',
  ]}
/>

## Installation

LinearGradient is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/linear-gradient
```

To use this package you'll need to add `expo-linear-gradient` to your app. This works [with vanilla React Native](https://github.com/expo/expo/tree/sdk-47/packages/expo-linear-gradient) or Expo.

## Usage

Because LinearGradient requires a more complex to install native package, we've left it out of the `tamagui` export until Metro supports async import. Import it either separately or using the path `/linear-gradient`:

```tsx
import { LinearGradient } from '@tamagui/linear-gradient'
import { LinearGradient } from 'tamagui/linear-gradient'
```

LinearGradient is a YStack that accepts all Tamagui style props as well as theme colors, that places `expo-linear-gradient` inside it set to absoluteFill.

## API Reference

### LinearGradient

See the [expo docs](https://docs.expo.dev/versions/latest/sdk/linear-gradient/) for more complete information.

LinearGradient extends YStack, inheriting `View` props and therefore the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'colors',
      required: true,
      type: 'string[]',
      description: `Two or more colors.`,
    },
    {
      name: 'locations',
      required: false,
      type: 'number[] | null',
      description: `An array that contains numbers ranging from 0 to 1, inclusive, and is the same length as the colors property. Each number indicates a color-stop location where each respective color should be located.`,
      default: '[0.0, 1.0]',
    },
    {
      name: 'start',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 0.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will start 10% from the left and 20% from the top.`,
    },
    {
      name: 'end',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 1.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will end 10% from the left and 20% from the bottom.`,
    },
  ]}
/>


## components/linear-gradient/1.0.0-alpha

---
title: Linear Gradient
description: Linear Gradient that works with Tamagui style props.
name: html
component: LinearGradient
demoName: LinearGradient
---

# Linear Gradient

<Description>Linear Gradient that works with Tamagui style props.</Description>

<Notice>In beta, currently doesn't resolve theme values for the colors property.</Notice>

<HeroContainer>
  <LinearGradientDemo />
</HeroContainer>

```tsx hero template=LinearGradient

```

<Highlights
  features={[
    'Native and web support',
    'Webpack bundling support',
    'Full Tamagui style props',
  ]}
/>

### Usage

We've included `<LinearGradient />` so it can accept Tamagui style props, and to patch a bug with the current expo version with some Webpack configurations.


## components/linear-gradient/2.0.0

---
title: Linear Gradient
description: Linear gradients that work with Tamagui style props
name: linear-gradient
component: LinearGradient
package: linear-gradient
demoName: LinearGradient
---

<IntroParagraph>
  LinearGradient renders theme-aware gradients with the same style props on web
  and native.
</IntroParagraph>

<HeroContainer>
  <LinearGradientDemo />
</HeroContainer>

```tsx hero template=LinearGradient

```

<Highlights
  features={[
    'Native and web support',
    'Tamagui style props and theme colors',
    'Webpack bundling support',
  ]}
/>

## Installation

LinearGradient is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/linear-gradient
```

### Native setup

On native, LinearGradient uses `expo-linear-gradient` for rendering. This works with vanilla React Native or Expo.

#### Step 1: install expo-linear-gradient

```bash
npm install expo-linear-gradient
```

#### Step 2: import the setup module

In your app's entry file (index.js or App.tsx), before any Tamagui imports:

```tsx
import '@tamagui/native/setup-expo-linear-gradient'
```

That's it! LinearGradient will automatically detect and use expo-linear-gradient when available.

#### Without expo-linear-gradient

If you don't set up expo-linear-gradient, LinearGradient will log a warning on native. On web, LinearGradient uses CSS gradients and doesn't require any additional setup.

## Usage

Because LinearGradient requires a native package, it is not included in the main `tamagui` export. Import it either separately or using the path `/linear-gradient`:

```tsx
import { LinearGradient } from '@tamagui/linear-gradient'
import { LinearGradient } from 'tamagui/linear-gradient'
```

LinearGradient is a YStack that accepts all Tamagui style props as well as theme colors. On native it renders `expo-linear-gradient` inside an `absoluteFill` wrapper.

## API reference

### LinearGradient

See the [expo docs](https://docs.expo.dev/versions/latest/sdk/linear-gradient/) for more complete information.

#### Alternative: backgroundImage style prop

For most gradients, use the [`backgroundImage` style prop](/docs/core/style-props#backgroundimage):

```tsx
<html.div backgroundImage="linear-gradient(to bottom, background, color)" />
```

Use `<LinearGradient>` for precise color stop control.

---

LinearGradient extends YStack, inheriting `View` props and therefore the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'colors',
      required: false,
      type: 'string[]',
      description: `Two or more colors. Falls back to black and white if omitted.`,
    },
    {
      name: 'locations',
      required: false,
      type: 'number[] | null',
      description: `An array that contains numbers ranging from 0 to 1, inclusive, and is the same length as the colors property. Each number indicates a color-stop location where each respective color should be located.`,
      default: '[0.0, 1.0]',
    },
    {
      name: 'start',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 0.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will start 10% from the left and 20% from the top.`,
    },
    {
      name: 'end',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 1.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will end 10% from the left and 20% from the bottom.`,
    },
  ]}
/>


## components/linear-gradient/3.0.0

---
title: Linear Gradient
description: Linear gradients that work with Tamagui style props
name: linear-gradient
component: LinearGradient
package: linear-gradient
demoName: LinearGradient
---

<IntroParagraph>
  LinearGradient renders theme-aware gradients with the same style props on web
  and native.
</IntroParagraph>

<HeroContainer>
  <LinearGradientDemo />
</HeroContainer>

```tsx hero template=LinearGradient

```

<Highlights
  features={[
    'Native and web support',
    'Tamagui style props and theme colors',
    'Webpack bundling support',
  ]}
/>

## Installation

LinearGradient is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/linear-gradient
```

No native package or setup is needed. On native, LinearGradient draws a
`backgroundImage` gradient, which React Native 0.76 and later renders natively
with the new architecture. On web it is a CSS gradient.

## Usage

Import it separately or using the path `/linear-gradient`:

```tsx
import { LinearGradient } from '@tamagui/linear-gradient'
import { LinearGradient } from 'tamagui/linear-gradient'
```

LinearGradient is a YStack that accepts all Tamagui style props as well as theme colors. It draws its gradient as a `backgroundImage` on an `absoluteFill` layer behind its children.

## API reference

### LinearGradient

#### Alternative: backgroundImage style prop

For most gradients, use the [`backgroundImage` style prop](/docs/core/style-props#backgroundimage):

```tsx
<html.div backgroundImage="linear-gradient(to bottom, background, color)" />
```

Use `<LinearGradient>` for precise color stop control.

---

LinearGradient extends YStack, inheriting `View` props and therefore the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'colors',
      required: false,
      type: 'string[]',
      description: `Two or more colors. Falls back to black and white if omitted.`,
    },
    {
      name: 'locations',
      required: false,
      type: 'number[] | null',
      description: `An array that contains numbers ranging from 0 to 1, inclusive, and is the same length as the colors property. Each number indicates a color-stop location where each respective color should be located.`,
      default: '[0.0, 1.0]',
    },
    {
      name: 'start',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 0.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will start 10% from the left and 20% from the top.`,
    },
    {
      name: 'end',
      required: false,
      type: 'LinearGradientPoint | null',
      default: '{ x: 0.5, y: 1.0 }',
      description: `For example, { x: 0.1, y: 0.2 } means that the gradient will end 10% from the left and 20% from the bottom.`,
    },
  ]}
/>


## components/spinner/1.0.0

---
title: Spinner
description: Render a loading indicator.
name: spinner
component: Spinner
demoName: Spinner
---

<HeroContainer>
  <SpinnerDemo />
</HeroContainer>

```tsx hero template=Spinner

```

<Highlights
  features={[
    'Small and large size options',
    'All theme colors supported',
    'All YStack props supported',
  ]}
/>

## Installation

Spinner is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/spinner
```

Note that due to the fact that Spinner is an extension of React Native [ActivityIndicator](https://reactnative.dev/docs/activityindicator), and that only accepts size `small` or `large`, we are currently limited to just these sizes.

```tsx
import { Button, Spinner } from 'tamagui'

export default () => <Spinner size="large" color="green-10" />
```

## API Reference

### Spinner

Spinner extends [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: '"small" | "large"',
    },
    {
      name: 'color',
      required: false,
      type: 'string | ColorTokens',
      description: `Give the spinner a color.`,
    },
  ]}
/>


## components/spinner/2.0.0

---
title: Spinner
description: Render a loading indicator
name: spinner
component: Spinner
package: spinner
demoName: Spinner
---

<IntroParagraph>
  Spinner renders a theme-aware loading indicator in small and large sizes.
</IntroParagraph>

<HeroContainer>
  <SpinnerDemo />
</HeroContainer>

```tsx hero template=Spinner

```

<Highlights
  features={[
    'Small and large size options',
    'All theme colors supported',
    'All YStack props supported',
  ]}
/>

## Installation

Spinner is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/spinner
```

Spinner extends React Native's [ActivityIndicator](https://reactnative.dev/docs/activityindicator), which only accepts `small` or `large`, so those are the only sizes.

## Usage

```tsx
import { Button, Spinner } from 'tamagui'

export default () => <Spinner size="large" color="green-10" />
```

## API reference

### Spinner

Spinner extends [YStack](/docs/components/stacks), getting [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: '"small" | "large"',
      description: `Size of the spinner.`,
    },
    {
      name: 'color',
      required: false,
      type: 'string | ColorTokens',
      description: `Gives the spinner a color.`,
    },
  ]}
/>


## components/image/1.0.0

---
title: Image
description: React Native Web Image + Tamagui style props.
name: html
component: Image
package: image
demoName: Image
---

# Image

<Description>React Native Web Image + Tamagui style props.</Description>

<HeroContainer noPad>
  <ImageDemo />
</HeroContainer>

```tsx hero template=Image

```

<Highlights
  features={['Server rendering support', 'Native and web support', 'Full Tamagui style props']}
/>

### Props

[Tamagui props](/docs/intro/props) + [React Native Web Image props](https://necolas.github.io/react-native-web/docs/image/).


## components/image/2.0.0

---
title: Image
description: A lightweight cross-platform Image with Tamagui style props
name: image
component: Image
package: image
demoName: Image
---

<IntroParagraph>
  Image provides a lightweight cross-platform image component with Tamagui
  style props and pluggable renderers.
</IntroParagraph>

<HeroContainer noPad>
  <ImageDemo />
</HeroContainer>

```tsx hero template=Image

```

<Highlights
  features={[
    'Server rendering support',
    'Native and web support',
    'Full Tamagui style props',
    'Pluggable image renderers, including expo-image, through createImage',
  ]}
/>

## Installation

Image is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/image
```

## Usage

Use the `src` prop for the image URL:

```tsx
import { Image } from 'tamagui'

export default () => (
  <Image src="https://example.com/photo.jpg" width={200} height={200} />
)
```

Use `objectFit` to control how the image fits its container:

```tsx
<Image src="https://example.com/photo.jpg" width="100%" height={300} objectFit="cover" />
```

### Sizing on native

`width` and `height` are Tamagui layout props. On native, they become React Native
Image styles. Remote images must resolve to a nonzero layout size, so use fixed
dimensions or place percentage-sized images inside a parent with defined dimensions:

```tsx
<html.div width={320} height={200}>
  <Image
    src="https://example.com/photo.jpg"
    width="100%"
    height="100%"
    objectFit="cover"
  />
</html.div>
```

Tamagui converts a string `src` to `source={{ uri: src }}` on native. Layout
dimensions stay in `style`; they are not copied into the native source metadata.
React Native `source` objects remain supported for migration, but `src` is preferred.

## Using with expo-image

For better performance and features like blurhash placeholders and transitions,
you can use `createImage` to create a custom Image component with expo-image:

```tsx
import { Image as ExpoImage } from 'expo-image'
import { createImage } from '@tamagui/image'

export const Image = createImage({
  Component: ExpoImage,
  resizeModePropName: 'contentFit',
  objectPositionPropName: 'contentPosition',
})
```

Now you can use all expo-image props alongside Tamagui's unified API:

```tsx
const blurhash = '|rF?hV%2WCj[ayj[a|j[az...'

export default () => (
  <Image
    src="https://example.com/photo.jpg"
    width={200}
    height={300}
    objectFit="cover"
    placeholder={{ blurhash }}
    transition={300}
  />
)
```

### createImage options

<SimpleTable
  headers={['Option', 'Type', 'Default', 'Description']}
  rows={[
    [
      'Component',
      '`ComponentType`',
      '-',
      'The underlying image component (expo-image, react-native-fast-image, etc.)',
    ],
    [
      'resizeModePropName',
      '`string`',
      "`'resizeMode'`",
      "The prop name for resize mode. expo-image uses `'contentFit'`",
    ],
    [
      'objectPositionPropName',
      '`string`',
      '`undefined`',
      "The prop name for object position. expo-image uses `'contentPosition'`",
    ],
    [
      'mapObjectFitToResizeMode',
      '`function`',
      'Default mapper',
      "Custom function to map `objectFit` values to the component's resize mode",
    ],
    [
      'transformSource',
      '`function`',
      'Default transformer',
      'Custom function to transform source props',
    ],
  ]}
/>

## Accessibility

Always provide an `alt` attribute describing the image content. For decorative images, use an empty string (`alt=""`).

```tsx
// meaningful image
<Image
  src="/team-photo.jpg"
  alt="The Tamagui team at React Conf 2024"
  width={400}
  height={300}
/>

// decorative image
<Image
  src="/decorative-bg.jpg"
  alt=""
  width={400}
  height={300}
/>
```

On React Native, use `accessible` and `accessibilityLabel` for screen reader support. See the [React Native Accessibility docs](https://reactnative.dev/docs/accessibility) for details.

```tsx
<Image
  src="/avatar.jpg"
  accessible
  accessibilityLabel="User profile photo"
  width={64}
  height={64}
/>
```

## API reference

### Image

Extends View with [Tamagui props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'src',
      type: 'string | number',
      description:
        'The image URL or native require() result. Preferred over `source` for better web alignment.',
    },
    {
      name: 'alt',
      type: 'string',
      description:
        'Alternative text describing the image for accessibility. Use empty string for decorative images.',
    },
    {
      name: 'objectFit',
      type: "'cover' | 'contain' | 'fill' | 'none' | 'scale-down'",
      description:
        'How the image should be resized to fit its container. Maps to CSS object-fit on web and resizeMode on native.',
    },
    {
      name: 'objectPosition',
      type: 'string',
      description:
        'How the image should be positioned within its container. On native, requires expo-image or similar for full support.',
    },
    {
      name: 'source',
      type: 'ImageSourcePropType',
      description:
        'Deprecated React Native source prop. It remains supported during migration; prefer `src`.',
    },
    {
      name: 'resizeMode',
      type: 'ImageResizeMode',
      description: 'Deprecated. Use `objectFit` instead.',
    },
  ]}
/>

### Web-only props

These props pass through to the native `<img>` element on web:

<PropsTable
  data={[
    {
      name: 'loading',
      type: "'lazy' | 'eager'",
      description:
        'Lazy load images below the fold. Use eager (default) for above-the-fold images.',
    },
    {
      name: 'decoding',
      type: "'async' | 'sync' | 'auto'",
      description:
        'Hint for how the browser should decode the image. Use async for non-blocking decode.',
    },
    {
      name: 'fetchPriority',
      type: "'high' | 'low' | 'auto'",
      description:
        'Hint for fetch priority. Use high for LCP (largest contentful paint) images.',
    },
    {
      name: 'srcSet',
      type: 'string',
      description:
        'Comma-separated list of image sources with width descriptors for responsive images.',
    },
    {
      name: 'sizes',
      type: 'string',
      description:
        'Media conditions describing the image display size, used with srcSet.',
    },
    {
      name: 'crossOrigin',
      type: "'anonymous' | 'use-credentials'",
      description: 'CORS setting for the image request.',
    },
    {
      name: 'referrerPolicy',
      type: 'string',
      description: 'Referrer policy for the image request.',
    },
  ]}
/>

### Accessibility props

<PropsTable
  data={[
    {
      name: 'alt',
      type: 'string',
      description:
        'Alternative text for screen readers. Required for meaningful images, use empty string for decorative.',
    },
    {
      name: 'accessible',
      type: 'boolean',
      description: 'Native only. Marks the image as an accessible element.',
    },
    {
      name: 'accessibilityLabel',
      type: 'string',
      description:
        'Native only. Label read by screen readers. Use with accessible={true}.',
    },
    {
      name: 'aria-label',
      type: 'string',
      description: 'Overrides alt as the accessible name. Prefer using alt instead.',
    },
    {
      name: 'aria-describedby',
      type: 'string',
      description: 'References an element providing extended description.',
    },
    {
      name: 'aria-hidden',
      type: 'boolean',
      description: 'Hides the image from assistive technology. Alternative to alt="".',
    },
    {
      name: 'role',
      type: 'string',
      description:
        "Set to 'presentation' or 'none' for decorative images, or 'img' (default).",
    },
  ]}
/>

<Notice theme="green">
  Web props like `loading`, `srcSet`, and `fetchPriority` only apply on web. On native,
  use expo-image via `createImage` for advanced features like blurhash placeholders and
  priority loading.
</Notice>


## components/image/1.13.0

---
title: Image
description: React Native Web Image + Tamagui style props.
name: html
component: Image
package: image
demoName: Image
---

<HeroContainer noPad>
  <ImageDemo />
</HeroContainer>

```tsx hero template=Image

```

<Highlights
  features={['Server rendering support', 'Native and web support', 'Full Tamagui style props']}
/>

## Installation

Image is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/image
```

## Usage

Note that you need to set `source` like so - the `width` and `height` properties apply as styles around the image, but the actual image needs `source.width` and `source.height` for React Native:

```tsx
export default () => (
  <Image
    source={{ width: 200, height: 200, uri: 'https://...' }}
    width="100%"
    height="100%"
  />
)
```

## API Reference

### Image

[Tamagui props](/docs/intro/props) + [React Native Web Image props](https://necolas.github.io/react-native-web/docs/image/).


## components/switch/1.0.0

---
title: Switch
description: A simple switch component
name: switch
component: Switch
package: switch
demoName: Switch
---

# Switch

<Description>Use in forms to toggle between two states.</Description>

<HeroContainer showAnimationDriverControl>
  <SwitchDemo />
</HeroContainer>

```tsx hero template=Switch

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Independent frame and thumb styling and animation`,
    `Sizing with controlled or uncontrolled state`,
  ]}
/>

### Usage

```tsx
import { Switch } from 'tamagui'

export default () => (
  <Switch size="4">
    <Switch.Thumb animation="bouncy" />
  </Switch>
)
```

### Switch props

Switchs extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>


## components/switch/1.89.0

---
title: Switch
description: A toggle between two states.
name: switch
component: Switch
package: switch
demoName: Switch
---

<YStack className="is-sticky" />

<Tabs id="type" defaultValue="styled">
<Tabs.List>
  <TooltipSimple label="With Tamagui's default styles">
    <Tabs.Tab value="styled">Styled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No default styles, easy to customize">
    <Tabs.Tab value="unstyled">Unstyled</Tabs.Tab>
  </TooltipSimple>
  <TooltipSimple label="No dependency on Tamagui's core">
    <Tabs.Tab value="headless" label="No styles and no dependency on Tamagui's styling">Headless</Tabs.Tab>
  </TooltipSimple>
</Tabs.List>

<HeroContainer showAnimationDriverControl>
  <Tabs.Content value="styled" justifyContent="center" alignItems="center" width="100%">
    <SwitchDemo />
  </Tabs.Content>
  <Tabs.Content value="unstyled" justifyContent="center" alignItems="center" width="100%">
    <SwitchDemo />
  </Tabs.Content>
  <Tabs.Content value="headless" justifyContent="center" alignItems="center" width="100%">
    <SwitchHeadlessDemo />
  </Tabs.Content>
</HeroContainer>

<Tabs.Content value="styled">
```tsx hero template=Switch

```
</Tabs.Content>
<Tabs.Content value="unstyled">
```tsx hero template=Switch

```

</Tabs.Content>
  <Tabs.Content value="headless">
```tsx hero template=SwitchHeadless

```
</Tabs.Content>



<Highlights
features={[
  `Accessible, composable, and customizable`,
  `Independent frame and thumb styling and animation`,
  `Sizing with controlled or uncontrolled state`,
  `Native mobile Switch through the native prop`,
]}
/>


## Installation

<Tabs.Content value="styled">

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

</Tabs.Content>

<Tabs.Content value="headless">

To use the headless switch, you want to import it from the
`@tamagui/switch-headless` package. This package has no dependency on
`@tamagui/core`, but still works off the react-native APIs.
This means you can bring your own style library.

```bash
npm install @tamagui/switch-headless
```

</Tabs.Content>

## Usage

<Tabs.Content value="styled">

```tsx
import { Switch } from 'tamagui' // or '@tamagui/switch'

export default () => (
  <Switch size="4">
    <Switch.Thumb animation="bouncy" />
  </Switch>
)
```

</Tabs.Content>

<Tabs.Content value="unstyled">

Using the `createSwitch` export, you can create an unstyled switch without using
any of the default styles. This is similar to the `unstyled` prop, but it
doesn't assume the props `size` or `unstyled` exist, and it won't automatically
apply the `active` theme.

You must pass `SwitchContext` as the `context` option to your Frame and Thumb
styled components.

If you define a `checked` variant, it will apply those styles.

```tsx template=Switch

```

</Tabs.Content>

<Tabs.Content value="headless">

Using the `useSwitch` API, you can make your own Switch from scratch.

```tsx template=SwitchHeadless

```

</Tabs.Content>

## API Reference

### Switch

`Switch` extends View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch;`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>

</Tabs>

{/* TODO: document createSwitch and useSwitch's API */}


## components/switch/1.28.0

---
title: Switch
description: A simple switch component
name: switch
component: Switch
package: switch
demoName: Switch
---

# Switch

<Description>Use in forms to toggle between two states.</Description>

<HeroContainer showAnimationDriverControl>
  <SwitchDemo />
</HeroContainer>

```tsx hero template=Switch

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Independent frame and thumb styling and animation`,
    `Sizing with controlled or uncontrolled state`,
    `Native mobile Switch through the native prop`,
  ]}
/>

## Installation

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

## Usage

```tsx
import { Switch } from 'tamagui' // or '@tamagui/switch'

export default () => (
  <Switch size="4">
    <Switch.Thumb animation="bouncy" />
  </Switch>
)
```

## API Reference

### Switch

Switchs extend View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch;`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>


## components/switch/2.0.0

---
title: Switch
description: A toggle between two states
name: switch
component: Switch
package: switch
demoName: Switch
---

<HeroContainer showAnimationDriverControl>
  <SwitchDemo />
</HeroContainer>

```tsx hero template=Switch

```



<Highlights
features={[
  `Accessible, composable, and customizable`,
  `Independent frame and thumb styling and animation`,
  `Sizing with controlled or uncontrolled state`,
  `Native mobile Switch through the native prop`,
]}
/>


## Installation

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

## Usage

```tsx
import { Switch } from 'tamagui' // or '@tamagui/switch'

export default () => (
  <Switch size="md">
    <Switch.Thumb transition="bouncy" />
  </Switch>
)
```

### Headless Usage

To use the headless switch without `@tamagui/core`, install `@tamagui/switch-headless`:

```bash
npm install @tamagui/switch-headless
```

The `useSwitch` hook provides all the state and accessibility props needed to build a custom switch with any styling solution:

```tsx
import { useSwitch } from '@tamagui/switch-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

function MySwitch({ defaultChecked, onCheckedChange, ...props }) {
  const [checked, setChecked] = useState(defaultChecked || false)

  const { switchProps, switchRef, bubbleInput } = useSwitch(
    props,
    [checked, setChecked],
    null
  )

  return (
    <>
      <Pressable
        ref={switchRef}
        {...switchProps}
        style={{
          width: 50,
          height: 28,
          borderRadius: 14,
          backgroundColor: checked ? '#22c55e' : '#d1d5db',
          padding: 2,
        }}
      >
        <View
          style={{
            width: 24,
            height: 24,
            borderRadius: 12,
            backgroundColor: 'white',
            transform: [{ translateX: checked ? 22 : 0 }],
          }}
        />
      </Pressable>
      {bubbleInput}
    </>
  )
}
```

## API Reference

### Switch

`Switch` extends View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
      description: `Callback called when checked state changes.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply when the switch is checked/active.`,
    },
    {
      name: 'activeTheme',
      type: 'string | null',
      description: `Theme to apply when the switch is checked/active.`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply to the thumb when the switch is checked/active.`,
    },
  ]}
/>

### useSwitch

The `useSwitch` hook accepts three arguments:

```tsx
const { switchProps, switchRef, bubbleInput } = useSwitch(
  props, // SwitchProps
  state, // [checked: boolean, setChecked: (checked: boolean) => void]
  ref // React.Ref
)
```

#### Props (first argument)

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labelledby for accessibility.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Whether the switch is disabled.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Form input name for the hidden input.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Form input value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Whether the switch is required in a form.`,
    },
    {
      name: 'onPress',
      type: '(event) => void',
      description: `Called when switch is pressed (composed with internal handler).`,
    },
  ]}
/>

#### State (second argument)

A tuple of `[checked, setChecked]` where:

- `checked`: Current boolean state
- `setChecked`: React state setter function

#### Return Value

| Property      | Type                | Description                                                                |
| ------------- | ------------------- | -------------------------------------------------------------------------- |
| `switchProps` | `object`            | Props to spread on your switch element (role, aria-checked, onPress, etc.) |
| `switchRef`   | `Ref`               | Composed ref to attach to your switch element                              |
| `bubbleInput` | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only)          |


## components/switch/3.0.0

---
title: Switch
description: A toggle between two states
name: switch
component: Switch
package: switch
demoName: Switch
---

<IntroParagraph>
  Switch exposes a controlled or uncontrolled boolean state through accessible,
  independently styled frame and thumb parts.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <SwitchDemo />
</HeroContainer>

```tsx hero template=Switch

```



<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Independent frame and thumb styling and animation`,
    `Sizing with controlled or uncontrolled state`,
    `Native mobile Switch through the native prop`,
  ]}
/>

## Installation

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

## Usage

```tsx
import { Switch } from 'tamagui' // or '@tamagui/switch'

export default () => (
  <Switch size="md">
    <Switch.Thumb transition="bouncy" />
  </Switch>
)
```

### Headless usage

To use the headless switch without `@tamagui/core`, install `@tamagui/switch-headless`:

```bash
npm install @tamagui/switch-headless
```

The `useSwitch` hook provides all the state and accessibility props needed to build a custom switch with any styling solution:

```tsx
import { useSwitch } from '@tamagui/switch-headless'
import { useState } from 'react'
import { Pressable, View } from 'react-native'

function MySwitch({ defaultChecked, onCheckedChange, ...props }) {
  const [checked, setChecked] = useState(defaultChecked || false)

  const { switchProps, switchRef, bubbleInput } = useSwitch(
    props,
    [checked, setChecked],
    null
  )

  return (
    <>
      <Pressable
        ref={switchRef}
        {...switchProps}
        style={{
          width: 50,
          height: 28,
          borderRadius: 14,
          backgroundColor: checked ? '#22c55e' : '#d1d5db',
          padding: 2,
        }}
      >
        <View
          style={{
            width: 24,
            height: 24,
            borderRadius: 12,
            backgroundColor: 'white',
            transform: [{ translateX: checked ? 22 : 0 }],
          }}
        />
      </Pressable>
      {bubbleInput}
    </>
  )
}
```

## API reference

### Switch

`Switch` extends View, inheriting all the
[Tamagui standard props](/docs/intro/props). Sizes come from the shared
[Sizing](/docs/core/sizing) ladder.

<PropsTable
  data={[
    {
      name: 'size',
      required: false,
      type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
      description: `A named size ("xs" to "xl", default "md") is a rung in the sizing ladder: the track is the ladder's square stretched 1.9 wide, and the thumb insets 2px on every side.`,
    },
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
      description: `Callback called when checked state changes.`,
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply when the switch is checked/active.`,
    },
    {
      name: 'activeTheme',
      type: 'string | null',
      description: `Theme to apply when the switch is checked/active.`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends View inheriting all the
[Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, removes all default Tamagui styling.`,
    },
    {
      name: 'activeStyle',
      type: 'ViewStyle',
      description: `Styles to apply to the thumb when the switch is checked/active.`,
    },
  ]}
/>

### useSwitch

The `useSwitch` hook accepts three arguments:

```tsx
const { switchProps, switchRef, bubbleInput } = useSwitch(
  props, // SwitchProps
  state, // [checked: boolean, setChecked: (checked: boolean) => void]
  ref // React.Ref
)
```

#### Props (first argument)

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labelledby for accessibility.`,
    },
    {
      name: 'disabled',
      type: 'boolean',
      description: `Whether the switch is disabled.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Form input name for the hidden input.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Form input value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Whether the switch is required in a form.`,
    },
    {
      name: 'onPress',
      type: '(event) => void',
      description: `Called when switch is pressed (composed with internal handler).`,
    },
  ]}
/>

#### State (second argument)

A tuple of `[checked, setChecked]` where:

- `checked`: Current boolean state
- `setChecked`: React state setter function

#### Return value

| Property      | Type                | Description                                                                |
| ------------- | ------------------- | -------------------------------------------------------------------------- |
| `switchProps` | `object`            | Props to spread on your switch element (role, aria-checked, onPress, etc.) |
| `switchRef`   | `Ref`               | Composed ref to attach to your switch element                              |
| `bubbleInput` | `ReactNode \| null` | Hidden input for form compatibility (render as sibling, web only)          |


## components/switch/1.58.0

---
title: Switch
description: A simple switch component
name: switch
component: Switch
package: switch
demoName: Switch
---

# Switch

<Description>Use in forms to toggle between two states.</Description>

<HeroContainer showAnimationDriverControl>
  <SwitchDemo />
</HeroContainer>

```tsx hero template=Switch

```

<Highlights
  features={[
    `Accessible, composable, and customizable`,
    `Independent frame and thumb styling and animation`,
    `Sizing with controlled or uncontrolled state`,
    `Native mobile Switch through the native prop`,
  ]}
/>

## Installation

Switch is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/switch
```

## Usage

```tsx
import { Switch } from 'tamagui' // or '@tamagui/switch'

export default () => (
  <Switch size="4">
    <Switch.Thumb animation="bouncy" />
  </Switch>
)
```

## Headless with `createSwitch`

Using the `createSwitch` export, you can create a fully custom switch without using any of the default styles. This is similar to `unstyled`, but it doesn't assume the props `size` or `unstyled` exist, and it won't automatically apply the `active` theme.

You must pass `SwitchContext` as the `context` option to your Frame and Thumb styled components.

If you define a `checked` variant, it will apply those styles.

Here's an example:

```tsx
import { View, styled } from '@tamagui/core'
import { createSwitch } from '@tamagui/switch'

const Frame = styled(View, {
  variants: {
    checked: {
      true: {
        backgroundColor: 'yellow',
      },
      false: {
        backgroundColor: 'green',
      },
    },
  } as const,
})

const Thumb = styled(View, {
  variants: {
    checked: {
      true: {
        opacity: 1,
      },
      false: {
        opacity: 0.5,
      },
    },
  } as const,
})

export const Switch = createSwitch({
  Frame,
  Thumb,
})
```

## API Reference

### Switch

`Switch` extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'labeledBy',
      type: 'string',
      description: `Set aria-labeled-by.`,
    },
    {
      name: 'name',
      type: 'string',
      description: `Equivalent to input name.`,
    },
    {
      name: 'value',
      type: 'string',
      description: `Give it a value (for use in HTML forms).`,
    },
    {
      name: 'checked',
      type: 'boolean',
      description: `Control the input.`,
    },
    {
      name: 'defaultChecked',
      type: 'boolean',
      description: `Uncontrolled default value.`,
    },
    {
      name: 'required',
      type: 'boolean',
      description: `Sets aria-required.`,
    },
    {
      name: 'onCheckedChange',
      type: '(checked: boolean) => void',
    },
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
    {
      name: 'native',
      type: 'NativeValue<"mobile" | "ios" | "android">',
      description: `Render to a native switch. (Not supported on web)`,
    },
    {
      name: 'nativeProps',
      type: 'SwitchProps (from `react-native`)',
      description: `Props to pass to the native Switch;`,
    },
  ]}
/>

### Switch.Thumb

`Switch.Thumb` extends View inheriting all the [Tamagui standard props](/docs/intro/props), plus:

<PropsTable
  data={[
    {
      name: 'unstyled',
      type: 'boolean',
      default: 'false',
      description: `When true, remove all default tamagui styling.`,
    },
  ]}
/>


## components/dialog/1.0.0

---
title: Dialog
description: Show a modal with configurable layout and accessible actions.
name: dialog
component: Dialog
package: dialog
demoName: Dialog
---

<HeroContainer showAnimationDriverControl>
  <DialogDemo />
</HeroContainer>

```tsx hero template=Dialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Accessibility checks for ARIA props during development`,
  ]}
/>

<Notice>
  Dialog does not work on native, instead you can Adapt it to a Sheet as shown in the demo
  code above.
</Notice>

## Installation

Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/dialog
```

In order to use this component independently of `tamagui`, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

## Anatomy

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* Optional: Control focus behavior */}
    <Dialog.FocusScope loop trapped focusOnIdle={true}>
      <Dialog.FocusScope.Scope>
        {/* Focus scope will be applied to children */}
      </Dialog.FocusScope.Scope>
    </Dialog.FocusScope>
  </Dialog>
)
```

## API Reference

### Dialog

Contains every component for the dialog. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Dialog.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Passes size down too all sub-components when set for padding, arrow, borderRadius`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      description: `Renders into root of app instead of inline`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      required: false,
      description: `Used to disable the automatic removal of scrolling from the page when open.`,
    },
  ]}
/>

### Dialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### Dialog.Portal

Renders Dialog into appropriate container. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Dialog.Content

Main container for Dialog content, this is where you should apply animations.

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Dialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### Dialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/docs/components/headings).

### Dialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/docs/components/text).

### Dialog.Close

Closes the Dialog, accepts the same props as YStack. Recommended to use with your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Close elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

Just [Tamagui Props](/docs/intro/props).

### Dialog.FocusScope

Provides access to the underlying FocusScope component used by Dialog for focus management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Dialog.Sheet

When used with `Adapt`, Dialog will render as a sheet when that breakpoint is active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Dialog.Sheet.Frame` to insert the contents given to `Dialog.Content`

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* optionally change to sheet when small screen */}
    <Dialog.Adapt when="maxMd">
      <Dialog.Sheet>
        <Dialog.Sheet.Frame>
          <Dialog.Adapt.Contents />
        </Dialog.Sheet.Frame>
        <Dialog.Sheet.Overlay />
      </Dialog.Sheet>
    </Dialog.Adapt>
  </Dialog>
)
```

<Notice>
  Note that Dialog.Sheet currently doesn't preserve state of the contents when it
  transitions between Sheet and Portal. In the future, we can do this on the web using
  react-reparenting.
</Notice>

### PortalProvider

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Examples

### Inside native modals

If you're using native modals (maybe from react-navigation), you'll notice the Dialogs won't show up inside the modal. To get around this, you should wrap your screen inside `PortalProvider`, like so:

```tsx
import { PortalProvider } from 'tamagui'

// this component used in react-navigation/expo-router with `presentation: "modal"`
export function Page() {
  return (
    <PortalProvider>{/* rest of your page, including the Dialog... */}</PortalProvider>
  )
}
```


## components/dialog/1.131.0

---
title: Dialog
description: Show a modal with configurable layout and accessible actions.
name: dialog
component: Dialog
package: dialog
demoName: Dialog
---

<HeroContainer showAnimationDriverControl>
  <DialogDemo />
</HeroContainer>

```tsx hero template=Dialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Accessibility checks for ARIA props during development`,
  ]}
/>

Dialog is a great way to show content inside a new floating window above
content. Be sure to open the code example above for a copy-paste implementation.

## Installation

Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/dialog
```

If you aren't using `tamagui` and instead using the `@tamagui/dialog` package
separately, you'll first need to install the `@tamagui/portal` package:

```bash
npm install @tamagui/portal
```

Then add `PortalProvider` to the root of your app:

```tsx fileName="App.tsx"
import { PortalProvider } from '@tamagui/portal'
import YourApp from './components/YourApp'

function App() {
  return (
    <PortalProvider shouldAddRootHost>
      <YourApp />
    </PortalProvider>
  )
}

export default App
```

## Anatomy

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* Optional: Control focus behavior */}
    <Dialog.FocusScope loop trapped focusOnIdle={true}>
      <Dialog.FocusScope.Scope>
        {/* Focus scope will be applied to children */}
      </Dialog.FocusScope.Scope>
    </Dialog.FocusScope>
  </Dialog>
)
```

## Scoping

Dialog supports scoping which lets you mount one or more Dialog instances at the
root of your app, while having a deeply nested child Trigger or Content attach
to the proper parent Dialog instance.

In performance sensitive areas you may want to take advantage of this, it allows
you to only need to render the Dialog.Trigger inside the sensitive area as
Dialogs aren't the cheapest component - they have a lot of functionality.

Here's the basic anatomy of using `scope` and placing your Dialog higher up for
performance:

```tsx fileName=_layout.tsx
import { Dialog } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Dialog scope="user-profile">
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* the rest of your app, note that it's inside of Dialog */}
    {children}
  </Dialog>
)
```

```tsx fileName=UserProfile.tsx
export default () => (
  <Dialog.Trigger scope="user-profile">
    <Button>Open Profile</Button>
  </Dialog.Trigger>
)
```

Note that the `Trigger` scope ties to the `Dialog` scope.

## Dismissal Behavior

By default, dialogs can be dismissed by:

- Clicking outside the dialog content (on the overlay)
- Pressing the Escape key
- Clicking a Dialog.Close element

### Modal vs Non-Modal Dialogs

- **Modal dialogs** (`modal={true}`, which is the default):
  - In v1, have `disableOutsidePointerEvents` set to `true` by default
  - Still dismiss on outside click, but prevent interaction with elements behind the dialog
  - Prevent right-click dismissal (right-clicks on the overlay are ignored)
- **Non-modal dialogs** (`modal={false}`):
  - Allow interaction with elements behind the dialog
  - Dismiss on any outside click
  - Do not trap focus

### Preventing Outside Dismissal

To prevent a dialog from closing when clicking outside:

```tsx
<Dialog.Content
  onPointerDownOutside={(event) => {
    event.preventDefault()
  }}
>
  {/* Dialog contents */}
</Dialog.Content>
```

## API Reference

### Dialog

Contains every component for the dialog. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Dialog.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: ``,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      description: `Renders into root of app instead of inline`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      required: false,
      description: `Used to disable the automatic removal of scrolling from the page when open.`,
    },
  ]}
/>

### Dialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### Dialog.Portal

Renders Dialog into appropriate container. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Dialog.Content

Main container for Dialog content, this is where you should apply animations.

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'disableOutsidePointerEvents',
      type: 'boolean',
      required: false,
      description: `When true, hover/focus/click interactions will be disabled on elements outside the Dialog. Users will need to click twice on outside elements to interact with them: once to close the Dialog, and again to trigger the element. Note: In v1, modal dialogs have this set to true by default.`,
    },
  ]}
/>

### Dialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### Dialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/docs/components/headings).

### Dialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/docs/components/text).

### Dialog.Close

Closes the Dialog, accepts the same props as YStack. Recommended to use with
your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Close elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

Just [Tamagui Props](/docs/intro/props).

### Dialog.FocusScope

Provides access to the underlying FocusScope component used by Dialog for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Dialog.Sheet

When used with `Adapt`, Dialog will render as a sheet when that breakpoint is
active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Dialog.Sheet.Frame` to insert the contents
given to `Dialog.Content`

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* optionally change to sheet when small screen */}
    <Dialog.Adapt when="maxMd">
      <Dialog.Sheet>
        <Dialog.Sheet.Frame>
          <Dialog.Adapt.Contents />
        </Dialog.Sheet.Frame>
        <Dialog.Sheet.Overlay />
      </Dialog.Sheet>
    </Dialog.Adapt>
  </Dialog>
)
```

<Notice>
  Note that Dialog.Sheet currently doesn't preserve state of the contents when it
  transitions between Sheet and Portal. In the future, we can do this on the web using
  react-reparenting.
</Notice>

### PortalProvider

<PropsTable
  data={[
    {
      name: 'shouldAddRootHost',
      type: 'boolean',
      required: false,
      description: `Defines whether to add a default root host or not.`,
    },
  ]}
/>

## Examples

### Inside native modals

If you're using native modals (maybe from react-navigation), you'll notice the
Dialogs won't show up inside the modal. To get around this, you should wrap your
screen inside `PortalProvider`, like so:

```tsx
import { PortalProvider } from 'tamagui'

// this component used in react-navigation/expo-router with `presentation: "modal"`
export function Page() {
  return (
    <PortalProvider>{/* rest of your page, including the Dialog... */}</PortalProvider>
  )
}
```


## components/dialog/2.0.0

---
title: Dialog
description: Show a modal with configurable layout and accessible actions
name: dialog
component: Dialog
package: dialog
demoName: Dialog
---

<HeroContainer showAnimationDriverControl>
  <DialogDemo />
</HeroContainer>

```tsx hero template=Dialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Animations, themes, and size props`,
    `Accessibility checks for ARIA props during development`,
  ]}
/>

Dialog is a great way to show content inside a new floating window above
content. Dialogs [automatically stack](/ui/z-index) above other overlays. Be sure to open the code example above for a copy-paste implementation.

## Installation

Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/dialog
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/docs/components/portal#native-portal-setup-recommended) to preserve React
  context inside Dialog content.
</Notice>

## Anatomy

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* Optional: Control focus behavior */}
    <Dialog.FocusScope loop trapped focusOnIdle={true}>
      <Dialog.FocusScope.Scope>
        {/* Focus scope will be applied to children */}
      </Dialog.FocusScope.Scope>
    </Dialog.FocusScope>
  </Dialog>
)
```

## Scoping

Dialog supports scoping which lets you mount one or more Dialog instances at the
root of your app, while having a deeply nested child Trigger or Content attach
to the proper parent Dialog instance.

In performance sensitive areas you may want to take advantage of this, it allows
you to only need to render the Dialog.Trigger inside the sensitive area as
Dialogs aren't the cheapest component - they have a lot of functionality.

Here's the basic anatomy of using `scope` and placing your Dialog higher up for
performance:

```tsx fileName=_layout.tsx
import { Dialog } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Dialog scope="user-profile">
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* the rest of your app, note that it's inside of Dialog */}
    {children}
  </Dialog>
)
```

```tsx fileName=UserProfile.tsx
export default () => (
  <Dialog.Trigger scope="user-profile">
    <Button>Open Profile</Button>
  </Dialog.Trigger>
)
```

Note that the `Trigger` scope ties to the `Dialog` scope.

## Dismissal Behavior

By default, dialogs can be dismissed by:

- Clicking outside the dialog content (on the overlay)
- Pressing the Escape key
- Clicking a Dialog.Close element

### Modal vs Non-Modal Dialogs

- **Modal dialogs** (`modal={true}`, which is the default):
  - In v1, have `disableOutsidePointerEvents` set to `true` by default
  - Still dismiss on outside click, but prevent interaction with elements behind the dialog
  - Prevent right-click dismissal (right-clicks on the overlay are ignored)
- **Non-modal dialogs** (`modal={false}`):
  - Allow interaction with elements behind the dialog
  - Dismiss on any outside click
  - Do not trap focus

### Preventing Outside Dismissal

To prevent a dialog from closing when clicking outside:

```tsx
<Dialog.Content
  onPointerDownOutside={(event) => {
    event.preventDefault()
  }}
>
  {/* Dialog contents */}
</Dialog.Content>
```

## API Reference

### Dialog

Contains every component for the dialog. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Dialog.Content`,
    },
    {
      name: 'size',
      type: 'SizeTokens',
      description: `Passes size down to all sub-components when set for padding, arrow, borderRadius.`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open state of the dialog.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Initial open state when uncontrolled.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called when the dialog opens or closes.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      description: `Renders into root of app instead of inline.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      default: 'false',
      description: `When true, dialog content stays mounted in the DOM even when closed. Useful for preserving state across open/close cycles or when you need faster re-opening.`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      required: false,
      description: `Used to disable the automatic removal of scrolling from the page when open.`,
    },
  ]}
/>

### Dialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### Dialog.Portal

Renders Dialog into appropriate container. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Dialog.Content

Main container for Dialog content, this is where you should apply animations.

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'disableOutsidePointerEvents',
      type: 'boolean',
      required: false,
      description: `When true, hover/focus/click interactions will be disabled on elements outside the Dialog. Users will need to click twice on outside elements to interact with them: once to close the Dialog, and again to trigger the element. Note: In v1, modal dialogs have this set to true by default.`,
    },
  ]}
/>

### Dialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### Dialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/docs/components/headings).

### Dialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/docs/components/text).

### Dialog.Close

Closes the Dialog, accepts the same props as YStack. Recommended to use with
your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Close elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

Just [Tamagui Props](/docs/intro/props).

### Dialog.FocusScope

Provides access to the underlying FocusScope component used by Dialog for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'false',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Dialog.Sheet

When used with `Adapt`, Dialog will render as a sheet when that breakpoint is
active.

See [Sheet](/docs/components/sheet) for more props.

Must use `Adapt.Contents` inside the `Dialog.Sheet.Frame` to insert the contents
given to `Dialog.Content`

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* optionally change to sheet when small screen */}
    <Dialog.Adapt when="max-md">
      <Dialog.Sheet>
        <Dialog.Sheet.Frame>
          <Dialog.Adapt.Contents />
        </Dialog.Sheet.Frame>
        <Dialog.Sheet.Overlay />
      </Dialog.Sheet>
    </Dialog.Adapt>
  </Dialog>
)
```

<Notice>
  Note that Dialog.Sheet currently doesn't preserve state of the contents when it
  transitions between Sheet and Portal. In the future, we can do this on the web using
  react-reparenting.
</Notice>


## components/dialog/3.0.0

---
title: Dialog
description: Show a modal with configurable layout and accessible actions
name: dialog
component: Dialog
package: dialog
demoName: Dialog
---

<IntroParagraph>
  Dialog presents focused content in an accessible modal with composable parts
  and optional Sheet adaptation.
</IntroParagraph>

<HeroContainer showAnimationDriverControl>
  <DialogDemo />
</HeroContainer>

```tsx hero template=Dialog

```

<Highlights
  features={[
    `Customizable, themeable default styling`,
    `Transitions, themes, and focus props`,
    `Accessibility checks for ARIA props during development`,
    `Per-part presence lifecycle for reliable exit animations`,
  ]}
/>

Dialog shows content in a floating window above the page. Dialogs
[automatically stack](/ui/z-index) above other overlays. Open the code example
above for a copy-paste implementation.

## Installation

Dialog is already installed in `tamagui`, or you can install it independently:

```bash
npm install @tamagui/dialog
```

<Notice theme="blue">
  For native apps, we recommend [setting up native
  portals](/ui/portal#native-portal-setup-recommended) to preserve React
  context inside Dialog content.
</Notice>

## Anatomy

```tsx
import { Dialog } from 'tamagui' // or '@tamagui/dialog'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    {/* Optional: control focus from a parent */}
    <Dialog.FocusScope loop trapped focusOnIdle={true}>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Title />
          <Dialog.Description />
          <Dialog.Close />
          {/* ... */}
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.FocusScope>
  </Dialog>
)
```

## Scoping

Dialog supports scoping which lets you mount one or more Dialog instances at the
root of your app, while having a deeply nested child Trigger or Content attach
to the proper parent Dialog instance.

In performance-sensitive areas this lets you render only `Dialog.Trigger` in
that subtree, since Dialog is not cheap to render and carries a lot of
functionality.

Here's the basic anatomy of using `scope` and placing your Dialog higher up for
performance:

```tsx fileName=_layout.tsx
import { Dialog } from 'tamagui'

// in your root layout:
export default ({ children }) => (
  <Dialog scope="user-profile">
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* the rest of your app, note that it's inside of Dialog */}
    {children}
  </Dialog>
)
```

```tsx fileName=UserProfile.tsx
export default () => (
  <Dialog.Trigger scope="user-profile">
    <Button>Open Profile</Button>
  </Dialog.Trigger>
)
```

Note that the `Trigger` scope ties to the `Dialog` scope.

## Dismissal behavior

By default, dialogs can be dismissed by:

- Clicking outside the dialog content (on the overlay)
- Pressing the Escape key
- Clicking a Dialog.Close element

### Modal vs non-modal dialogs

- **Modal dialogs** (`modal={true}`, which is the default):
  - In v1, have `disableOutsidePointerEvents` set to `true` by default
  - Still dismiss on outside click, but prevent interaction with elements behind the dialog
  - Prevent right-click dismissal (right-clicks on the overlay are ignored)
- **Non-modal dialogs** (`modal={false}`):
  - Allow interaction with elements behind the dialog
  - Dismiss on any outside click
  - Do not trap focus
  - Do not enable RemoveScroll while open in v3

In v3, Dialog parts own their presence lifecycle. Overlay and content can finish
exit animations before unmounting, and `onTransition` reports completion from
the animated part rather than from the root alone.

### Preventing outside dismissal

To prevent a dialog from closing when clicking outside:

```tsx
<Dialog.Content
  onPointerDownOutside={(event) => {
    event.preventDefault()
  }}
>
  {/* Dialog contents */}
</Dialog.Content>
```

## API reference

### Dialog

Contains every component for the dialog. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'children',
      type: 'React.ReactNode',
      required: true,
      description: `Must contain Dialog.Content`,
    },
    {
      name: 'scope',
      type: 'string',
      description: `Isolates this Dialog and its parts from other Dialog instances when needed.`,
    },
    {
      name: 'open',
      type: 'boolean',
      description: `Controlled open state of the dialog.`,
    },
    {
      name: 'defaultOpen',
      type: 'boolean',
      description: `Initial open state when uncontrolled.`,
    },
    {
      name: 'onOpenChange',
      type: '(open: boolean) => void',
      description: `Called when the dialog opens or closes.`,
    },
    {
      name: 'modal',
      type: 'boolean',
      default: 'true',
      description: `When true, traps focus, blocks outside scroll and interaction, and portals into the root of the app. When false, the dialog renders inline and is non-blocking.`,
    },
    {
      name: 'keepChildrenMounted',
      type: 'boolean',
      default: 'false',
      description: `When true, dialog content stays mounted in the DOM even when closed. Useful for preserving state across open/close cycles or when you need faster re-opening.`,
    },
    {
      name: 'disableRemoveScroll',
      type: 'boolean',
      required: false,
      description: `Used to disable the automatic removal of scrolling from the page when open.`,
    },
    {
      name: 'onAnimationComplete',
      type: '(info: { open: boolean }) => void',
      required: false,
      description: `Called when the dialog open or close animation completes.`,
    },
  ]}
/>

### Dialog.Trigger

Just [Tamagui Props](/docs/intro/props).

### Dialog.Portal

Renders Dialog into appropriate container. Beyond
[Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
  ]}
/>

### Dialog.Content

Main container for Dialog content, this is where you should apply animations.
`Dialog.Content` no longer accepts the old no-op `size` variant in v3.

To sit the content a level above the page, wrap it in `theme="level2"` (see
[Surfaces and levels](/docs/core/surfaces)):

```tsx
<Dialog.Content theme="level2">{/* ... */}</Dialog.Content>
```

Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
    {
      name: 'unstyled',
      required: false,
      type: `boolean`,
      description: `Removes all default Tamagui styles.`,
    },
    {
      name: 'disableOutsidePointerEvents',
      type: 'boolean',
      required: false,
      description: `When true, hover/focus/click interactions will be disabled on elements outside the Dialog. Users will need to click twice on outside elements to interact with them: once to close the Dialog, and again to trigger the element. Note: In v1, modal dialogs have this set to true by default.`,
    },
    {
      name: 'onEscapeKeyDown',
      type: '(event: KeyboardEvent) => void',
      required: false,
      description: `Called when Escape is pressed while the content is active.`,
    },
    {
      name: 'onInteractOutside',
      type: '(event: Event) => void',
      required: false,
      description: `Called when pointer or focus interaction happens outside the content. Prevent default to stop dismissal.`,
    },
  ]}
/>

### Dialog.Overlay

Displays behind Content. Beyond [Tamagui Props](/docs/intro/props), adds:

<PropsTable
  data={[
    {
      name: 'forceMount',
      type: 'boolean',
      required: false,
      description: `Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.`,
    },
  ]}
/>

### Dialog.Title

Required. Can wrap in VisuallyHidden to hide.

Defaults to H2, see [Headings](/ui/headings).

### Dialog.Description

Required. Can wrap in VisuallyHidden to hide.

Defaults to Paragraph, see [Paragraph](/ui/text).

### Dialog.Close

Closes the Dialog, accepts the same props as View. Recommended to use with
your own component and `asChild`.

<PropsTable
  data={[
    {
      name: 'displayWhenAdapted',
      type: 'boolean',
      description: `By default Close elements hide when Adapt is active. If set to true, they will show when adapted.`,
    },
  ]}
/>

### Dialog.FocusScope

Provides access to the underlying FocusScope component used by Dialog for focus
management. Can be used to control focus behavior from a parent component.

<PropsTable
  data={[
    {
      name: 'enabled',
      type: 'boolean',
      default: 'true',
      description: `Whether focus management is enabled`,
    },
    {
      name: 'loop',
      type: 'boolean',
      default: 'false',
      description: `When true, tabbing from last item will focus first tabbable and shift+tab from first item will focus last tabbable`,
    },
    {
      name: 'trapped',
      type: 'boolean',
      default: 'false',
      description: `When true, focus cannot escape the focus scope via keyboard, pointer, or programmatic focus`,
    },
    {
      name: 'noFocus',
      type: 'boolean',
      default: 'false',
      description: `Zero focus mode. While active, focus is allowed neither inside nor outside the scope. Web only.`,
    },
    {
      name: 'focusOnIdle',
      type: 'boolean | number',
      default: 'true',
      description: `When true, waits for idle before focusing. When a number, waits that many ms. This prevents reflows during animations`,
    },
    {
      name: 'onMountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on mount. Can be prevented`,
    },
    {
      name: 'onUnmountAutoFocus',
      type: '(event: Event) => void',
      description: `Event handler called when auto-focusing on unmount. Can be prevented`,
    },
  ]}
/>

### Adapted Sheet

When used with [Adapt](/ui/adapt), Dialog can hand its content to a Sheet at the
matching breakpoint.

See [Sheet](/ui/sheet) for more props.

Use `Adapt.Contents` inside `Sheet.Container` to insert the contents given to
`Dialog.Content`.

```tsx
import { Adapt, Dialog, Sheet } from 'tamagui'

export default () => (
  <Dialog>
    <Dialog.Trigger />

    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
        {/* ... */}
      </Dialog.Content>
    </Dialog.Portal>

    {/* optionally change to sheet when small screen */}
    <Adapt when="max-md" platform="touch">
      <Sheet modal dismissOnSnapToBottom>
        <Sheet.Container>
          <Sheet.Background />
          <Adapt.Contents />
        </Sheet.Container>
        <Sheet.Overlay />
      </Sheet>
    </Adapt>
  </Dialog>
)
```


## intro/compiler-install

---
title: Tamagui Compiler
description: Adding the compiler to your apps
---

<IntroParagraph>
  The Tamagui Compiler significantly improves performance of both web and native
  applications through partial analysis and view flattening.
</IntroParagraph>

See the [Benchmarks](/docs/intro/benchmarks) or read the
[in-depth background](/docs/intro/introduction#why-a-compiler). Note that Tamagui features
work at compile-time and runtime, so installing the compiler is optional, and in
fact we recommend only setting it up once you're ready for production.

The compiler analyzes JSX and `styled` definitions, resolves static styles,
and lowers eligible components to platform-native primitives.
The end result is less abstraction, such as a `div` on web or a plain React Native
`View` on native:

<br />
<br />
<TamaguiExamplesCode />

<Notice theme="blue">
  The compiler generates built versions of your components and config into a `.tamagui`
  directory. You'll want to add that directory to your `.gitignore`.
</Notice>

## Configuration with tamagui.build.ts

We recommend creating a `tamagui.build.ts` file in your project root as the
single source of truth for your compiler configuration. All bundler plugins and
the CLI automatically read from this file, so you only need to define your
options once.

This file lets the Tamagui CLI read your config and perform operations like
generating CSS, pre-compiling components, and verifying optimizations, while
also sharing that same configuration with whichever bundler plugin you use.
Without it, you'd need to duplicate options across your metro, babel, vite,
or webpack configs.

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: './public/tamagui.generated.css',
  // optional:
  importsWhitelist: ['constants.js', 'colors.js'],
  disableExtraction: process.env.NODE_ENV === 'development',
} satisfies TamaguiBuildOptions
```

With this file in place, your bundler plugins can be configured with no options
at all, because they pick up everything from `tamagui.build.ts`:

```tsx
// vite: tamaguiPlugin()
// webpack: new TamaguiPlugin()
// metro: withTamagui(config)
// all read from tamagui.build.ts automatically
```

You can still pass options directly to a plugin, and they'll be merged with
(and override) the options from `tamagui.build.ts`.

### Experimental native theme fast path

Tamagui 3 includes an opt-in, beta native theme engine for React Native 0.82 and newer.
It can update eligible Fabric views through a ShadowTree commit without
re-rendering each view in React. The API and compiler output are experimental.

Install the native engine and Nitro runtime:

```sh
bun add @tamagui/native-registry react-native-nitro-modules
```

Enable its compiler output in `tamagui.build.ts`:

```ts
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  experimental: {
    nativeFastPath: true,
  },
} satisfies TamaguiBuildOptions
```

Install the engine before your themed application tree mounts:

```ts
import * as nativeRegistry from '@tamagui/native-registry'
import { setNativeStyleEngine } from '@tamagui/core'

if (nativeRegistry.isAvailable()) {
  setNativeStyleEngine(nativeRegistry)
}
```

Rebuild the iOS and Android applications after adding the packages. The flag
defaults to `false`. When it is off, native compiler output is unchanged. When
the compiler flag is on but the engine is unavailable, components use the
existing theme hook and React render path. Web output is unchanged.

The registry keeps the existing `DynamicColorIOS` optimization in place. It
does not replace that path.

## Install

The recommended install is one package. `@tamagui/cli` carries the CLI and the
bundler integrations together, each behind a subpath:

```bash
yarn add -D @tamagui/cli
```

| Import               | Gives you                                   |
| -------------------- | ------------------------------------------- |
| `@tamagui/cli/vite`  | the same exports as `@tamagui/vite-plugin`  |
| `@tamagui/cli/metro` | the same exports as `@tamagui/metro-plugin` |

One dependency means one version to keep in sync, so the CLI and your bundler
plugin can't drift apart on an upgrade.

You can still install the standalone plugin instead, and if your project only
ever uses one bundler that is the smaller install. Both packages stay published
and the exports are identical, so the setup below is the same either way.

There are plugins for a variety of bundlers, or you can use the `@tamagui/cli`
to compile in-place:

### Webpack

```bash
yarn add tamagui-loader
```

We have a full example of a plain Webpack or Vite setup in the simple starter
accessible through `npm create tamagui@latest`, which shows a complete
configuration with more detail.

Add `tamagui-loader` and set up your `webpack.config.js`.

You can set it up more manually like so:

```js
const { shouldExclude } = require('tamagui-loader')

const tamaguiOptions = {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  importsWhitelist: ['constants.js', 'colors.js'],
  logTimings: true,
  disableExtraction: process.env.NODE_ENV === 'development',
}

module.exports = {
  resolve: {
    alias: {
      // Resolve react-native to react-native-web
      'react-native$': require.resolve('react-native-web'),
      // optional, for lighter svg icons on web
      'react-native-svg': require.resolve('@tamagui/react-native-svg'),
    },
  },
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        // you'll likely want to adjust this helper function,
        // but it serves as a decent start that you can copy/paste from
        exclude: (path) => shouldExclude(path, __dirname, tamaguiOptions),
        use: [
          // optionally thread-loader for significantly faster compile!
          'thread-loader',

          // works nicely alongside esbuild
          {
            loader: 'esbuild-loader',
          },

          {
            loader: 'tamagui-loader',
            options: tamaguiOptions,
          },
        ],
      },
    ],
  },
}
```

Or you can use the TamaguiPlugin which automates some of this setup for you.
If you have a `tamagui.build.ts`, you can pass no options:

```tsx
const { TamaguiPlugin } = require('tamagui-loader')

module.exports = {
  plugins: [
    // reads from tamagui.build.ts automatically
    new TamaguiPlugin(),
  ],
}
```

Or pass options inline to override:

```tsx
const { TamaguiPlugin } = require('tamagui-loader')

module.exports = {
  plugins: [
    new TamaguiPlugin({
      config: './tamagui.config.ts',
      components: ['tamagui'],
      importsWhitelist: ['constants.js', 'colors.js'],
      logTimings: true,
      disableExtraction: process.env.NODE_ENV === 'development',
    }),
  ],
}
```

Some notes on the options:

- _importsWhitelist_: Tamagui takes a conservative approach to partial
  evaluation, this field whitelists (matching against both .ts and .js) files to
  allow files that import them to read and use their values during compilation.
  Typically colors and constants files.
- _disableExtraction_: Useful for faster developer iteration as your design
  system hot reloads more reliably.

### Vite

See the [Vite guide](/docs/guides/vite) for more complete setup.

<Notice theme="yellow">
  The Vite plugin is ESM-only. Your project must have `"type": "module"` in its `package.json` (or use `.mjs`/`.mts` config files).
</Notice>

Update your `vite.config.ts`. If you have a `tamagui.build.ts`, no options are
needed:

```tsx
import { tamaguiPlugin } from '@tamagui/cli/vite'

export default defineConfig({
  plugins: [
    // reads from tamagui.build.ts automatically
    tamaguiPlugin(),
  ],
})
```

If you installed `@tamagui/vite-plugin` on its own, import from there instead.

Or pass options inline:

```tsx
import { tamaguiPlugin } from '@tamagui/cli/vite'

export default defineConfig({
  plugins: [
    tamaguiPlugin({
      config: 'src/tamagui.config.ts',
      components: ['tamagui'],
      disableExtraction: true,
    }),
  ],
})
```

### Next.js

See the [guide](/docs/guides/next-js) for more complete setup.

Next.js with Turbopack (the default) works best with the CLI approach: create a
`tamagui.build.ts` and use `tamagui build` to optimize production builds. No
bundler plugin needed.

For older Webpack-based Next.js setups, add `@tamagui/next-plugin` and configure
your `next.config.js`:

```js
const { withTamagui } = require('@tamagui/next-plugin')

module.exports = function (name, { defaultConfig }) {
  const tamaguiPlugin = withTamagui({
    // reads from tamagui.build.ts automatically, or pass inline:
    config: './tamagui.config.ts',
    components: ['tamagui'],
    disableExtraction: process.env.NODE_ENV === 'development',
    excludeReactNativeWebExports: ['Switch', 'ProgressBar', 'Picker'],
  })
  return {
    ...defaultConfig,
    ...tamaguiPlugin(defaultConfig),
  }
}
```

Note: If running into issues, the environment variable `IGNORE_TS_CONFIG_PATHS`
to "true" can fix issues with Tamagui being resolved incorrectly.

See the [Next.js Guide](/docs/guides/next-js) for more details on setting up
your app.

### Metro

The Metro integration runs the same shared compiler used by the other bundler
adapters after your configured Babel transformer.

Wrap your existing Metro config. With a `tamagui.build.ts`, you can omit the
inline options:

```js
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/cli/metro')

module.exports = withTamagui(getDefaultConfig(__dirname))
```

If you installed `@tamagui/metro-plugin` on its own, require from there instead.

Or pass options inline:

```js
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/cli/metro')

module.exports = withTamagui(getDefaultConfig(__dirname), {
  components: ['tamagui'],
  config: './tamagui.config.ts',
  logTimings: true,
  disableExtraction: process.env.NODE_ENV === 'development',
})
```

### Expo

[Check out the Expo guide](/docs/guides/expo) for more information on setting up
Expo. It uses the same Metro integration shown above.

### CLI-Based In-Place Compilation

For bundlers that don't have a Tamagui plugin yet (like Turbopack), or if you
prefer a simple setup, you can use `@tamagui/cli` to pre-compile your components
in-place before your build step.

This approach is meant for **production builds only** and should run in your
deployment pipeline, not during development. It rewrites files in place which
will mess up your working directory, but makes it highly compatible with any
bundler or tool. The downside is you don't get the helpful development
compatibility parts of the plugins, plus dev-mode debugging and `data-`
attributes.

For complete CLI documentation including all available commands, see the
[CLI Guide](/docs/core/cli).

#### Setup

1. Install:

```bash
yarn add -D @tamagui/cli
```

2. Create a `tamagui.build.ts` if you haven't already (see
   [above](#configuration-with-tamaguibuildts)).

3. Add a build script to your `package.json`:

```json
{
  "scripts": {
    "build": "tamagui build ./src -- next build"
  }
}
```

#### Usage

```bash
# Build all components in a directory (web + native by default)
npx tamagui build ./src

# Build for web only
npx tamagui build --target web ./src

# Build for native only
npx tamagui build --target native ./src

# Build a specific file
npx tamagui build ./src/components/MyComponent.tsx

# Include/exclude patterns
npx tamagui build --include "components/**" --exclude "**/*.test.tsx" ./src

# Output to a separate directory (source files unchanged)
npx tamagui build --output ./dist ./src

# Create platform-specific files next to source files (.web.tsx or .native.tsx)
npx tamagui build --target native --output-around ./src

# Preview changes without writing files
npx tamagui build --dry-run ./src

# Verify minimum optimizations (useful in CI)
npx tamagui build --target web --expect-optimizations 10 ./src
```

#### CI Verification with --expect-optimizations

The `--expect-optimizations` flag ensures your build is actually optimizing components. This is useful in CI to catch configuration issues:

```json
{
  "scripts": {
    "build": "tamagui build --target web --expect-optimizations 10 ./src -- next build"
  }
}
```

If the compiler produces fewer than the expected number of optimizations, the build will fail with an error message showing the actual count. This helps catch:

- Misconfigured `components` array
- Wrong source paths
- Configuration files not being found

#### Platform-Specific File Handling

The CLI automatically handles platform-specific files (`.web.tsx`,
`.native.tsx`, `.ios.tsx`, `.android.tsx`):

- Files with `.web.tsx` extensions are optimized for web only
- Files with `.native.tsx`, `.ios.tsx`, or `.android.tsx` extensions are
  optimized for native only
- Base files (`.tsx`) without platform-specific versions are optimized for all
  platforms
- If both `.web.tsx` and `.native.tsx` exist, the base `.tsx` file is skipped

#### Package.json Exports Support

The CLI supports `package.json` exports for path-specific imports. For example:

```json
{
  "exports": {
    ".": "./src/index.tsx",
    "./components/Button": "./src/Button.tsx"
  }
}
```

Both import styles work:

```tsx
import { Button } from '@my/ui'
import { Button } from '@my/ui/components/Button'
```

#### Integration Examples

This works with **any build tool**: run `tamagui build` before your build
command. Here are some examples:

**Next.js with Turbopack** (Turbopack doesn't support plugins yet):

```json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "tamagui build --target web ./src -- next build"
  }
}
```

**Vite, Remix, or any other bundler:**

```json
{
  "scripts": {
    "build": "tamagui build --target web ./src -- vite build"
  }
}
```

**React Native / Expo:**

```json
{
  "scripts": {
    "build:ios": "tamagui build --target native ./src -- eas build --platform ios",
    "build:android": "tamagui build --target native ./src -- eas build --platform android"
  }
}
```

**Using --output (no file restoration needed):**

If you prefer to output optimized files to a separate directory instead of modifying
source files in-place, use `--output`:

```json
{
  "scripts": {
    "build": "tamagui build --target web --output ./dist ./src && next build"
  }
}
```

With `--output`, your source files are never modified. The optimized files are
written to the output directory with their directory structure preserved.

**Using --output-around (platform-specific files):**

The `--output-around` flag creates optimized platform-specific files (`.web.tsx` or
`.native.tsx`) next to your source files instead of modifying them. Bundlers
automatically pick up these files via platform-specific resolution:

```json
{
  "scripts": {
    "prebuild:native": "tamagui build --target native --output-around ./src",
    "prebuild:web": "tamagui build --target web --output-around ./src"
  }
}
```

This transforms `Button.tsx` → creates `Button.native.tsx` or `Button.web.tsx`
alongside it. Metro/Expo uses `.native.tsx` on native, and web bundlers use `.web.tsx`.

The Tamagui CLI optimizes your components in-place (or to an output directory),
then your bundler processes the already-optimized files.

**Learn more:** See the [CLI Guide](/docs/core/cli) for documentation on all
CLI commands including `check`, `generate`, `add`, and more.

## Props

All compiler plugins accept the same options:

<PropsTable
  data={[
    {
      name: 'config',
      required: false,
      type: 'string',
      typeSimple: 'enum',
      default: "'./tamagui.config.ts'",
      description:
        'Relative path to your tamagui.config.ts file which should export default the result from createTamagui. Can be set in tamagui.build.ts instead.',
    },
    {
      name: 'components',
      required: false,
      type: 'string[]',
      typeSimple: 'enum',
      default: "['tamagui']",
      description: `Array of npm modules containing Tamagui components which you'll be using in your app. For example:  if you are using the base Tamagui components. This directs the compiler to load and optimize.`,
    },
    {
      name: 'importsWhitelist',
      required: false,
      type: 'string[]',
      typeSimple: 'enum',
      description: `Array of whitelisted file paths (always end in .js) which the compiler may try and import and parse at build-time. It is normalized to ".js" ending for all file extensions (js, jsx, tsx, ts). This usually should be set to something like ['constants.js', 'colors.js'] for example, where you have a couple mostly static files of constants that are used as default values for styles.`,
    },
    {
      name: 'logTimings',
      required: false,
      type: 'boolean',
      typeSimple: 'enum',
      default: 'true',
      description:
        'Tamagui outputs information for each file it compiles on how long it took to run, how many components it optimized, and how many it flattened. Set to false to disable these logs.',
    },
    {
      name: 'disable',
      required: false,
      type: 'boolean',
      typeSimple: 'enum',
      default: 'false',
      description: 'Disable everything - debug and extraction.',
    },
    {
      name: 'disableExtraction',
      required: false,
      type: 'boolean',
      typeSimple: 'enum',
      default: 'false',
      description:
        'Disable extraction to CSS completely, instead fully relying on runtime. Setting this to true speed up development as generally your app will hot reload the Tamagui configuration itself.',
    },
    {
      name: 'disableDebugAttr',
      required: false,
      type: 'boolean',
      typeSimple: 'enum',
      default: 'false',
      description:
        'Disable the data- attributes added in development mode that tie DOM nodes back to their source file and component.',
    },
    {
      name: 'disableFlattening',
      required: false,
      type: 'boolean',
      typeSimple: 'enum',
      default: 'false',
      description: 'Turns off tree-flattening.',
    },
    {
      name: 'outputCSS',
      required: false,
      type: 'string',
      typeSimple: 'enum',
      description:
        'Path to output extracted CSS. When set, the compiler automatically sets TAMAGUI_DID_OUTPUT_CSS which tree-shakes all runtime CSS generation code from your bundle (~6KB gzipped savings).',
    },
  ]}
/>

### Component discovery

The compiler resolves every component it meets. Components defined with
`styled()` anywhere in your app are linked across files, and a component
imported from any package is evaluated the first time a file uses it as a JSX
element or as a `styled()` base. The result is cached for the life of the dev
server or build, and a package bump invalidates the cached plans that lowered
against it.

`components` is an optional warm-up list. Listing a package evaluates it once
when the project loads instead of on first use, which is worth doing for the
package most of your files import from. Nothing else is needed for the
compiler to optimize components from other packages.

A package that cannot run in Node during the build (one that touches native
modules at import time, for example) is skipped with a debug message, and the
elements that use it stay on the runtime path. Set `DEBUG=tamagui` to see which
modules discovery skipped and why.

### Disabling the compiler

You can disable the compiler optimizations for an entire file with a comment at
the top of your file:

```tsx
// tamagui-ignore
```

You can disable the compiler optimization for a single component with the
boolean property `disableOptimization`:

```tsx
import { html } from '@tamagui/core'

export default () => <html.div disableOptimization />
```


## intro/errors

---
title: Errors
description: Common error messages and how to resolve them
---

<IntroParagraph>
  Find an error number below to see its cause and the steps that resolve it.
</IntroParagraph>

### Error 001

Haven't called createTamagui yet.

This often happens due to having duplicate Tamagui sub-dependencies.

Tamagui needs every `@tamagui/*` dependency to be on the exact same version.
Starter kits include an upgrade script you can run with `yarn upgrade:tamagui` to
align package versions.

You can also remove `node_modules` and run a fresh install after upgrading.

### Error 002

Using global config fallback. This may indicate duplicate tamagui instances
(e.g., from Vite SSR bundling). This is handled automatically, but may cause
issues due to duplicate tamagui modules if ignored.

### Error 003

#### Static evaluation failed

The compiler evaluates your Tamagui config and configured component modules in
Node during the build. The error names the module that could not be evaluated,
the importing file, and the original failure. Fix that failure so the compiler
can read the same config and component metadata as the application.

If the module is only used at runtime and none of its exports create your
Tamagui config or components, ignore that module explicitly in
`tamagui.build.ts`:

```ts
export default {
  components: ['tamagui'],
  dangerouslyIgnoreStaticEvaluationModules: ['runtime-only-package'],
}
```

Ignored modules receive an empty object during static evaluation. Do not ignore
a module whose exports contribute to `createTamagui()` or a configured component.

### Error 004

#### Flat value clause condition depth exceeded

A flat value clause supports at most 5 non-platform conditions (e.g. `hover:sm:focus:dark:`). Reduce the number of chained modifiers on a single clause.

### Error 005

#### Invalid variable name

`createCSSVariable` expected a string variable name.

### Error 006

#### Missing component in styled()

`styled()` was called without a target component. Pass a valid React component or host element tag.

### Error 007

#### createTamagui in zero-runtime graph

`createTamagui` was invoked in a zero-runtime graph. In zero-runtime mode, config parsing and CSS generation happen at build time. Remove client config references or mark the module as full-runtime.

### Error 008

#### Reserved token name collision

A token name collides with a reserved CSS-wide keyword (`initial`, `inherit`, `unset`, etc.). Rename the token to avoid collision with standard CSS identifiers.

### Error 009

#### Missing default font

`settings.defaultFont` points to a font family that was not defined in the `fonts` configuration.

### Error 010

#### createComponent in zero-runtime graph

A Tamagui component renderer survived compilation in a zero-runtime bundle. Move the component to a declared full-runtime island or ensure static compilation extracts it.

### Error 011

#### Missing animation driver

No animation driver was configured. Pass an `animations` driver to `createTamagui()`.

### Error 012

#### Missing animated-number hooks in driver

The configured animation driver does not support animated numbers. For CSS animations, use `@tamagui/animations-css/extras`.

### Error 013

#### Invalid matchMedia implementation

`matchMedia` did not return a valid `MediaQueryList` object. Supply a compatible `matchMedia` polyfill on native platforms.

### Error 014

#### Missing parent theme for shallow render

`<Theme shallow>` requires a mounted parent `<Theme>` component to derive its scoped theme hierarchy.

### Warning 002

You're rendering a Tamagui <Adapt /> component without nesting it inside a
parent that is able to adapt.

Adapt must be a child of a Dialog, Popover or Select. If that parent uses a
`scope` prop, the Adapt needs the matching adapt scope. See [Adapt](/ui/adapt).


## intro/themes

---
title: Themes
description: Create themes and sub-themes
---

<IntroParagraph>
  Themes map neatly to CSS variables: they are objects whose values you want to
  contextually change at any point in your React tree. Tamagui lets you define,
  nest, and read them on web and native.
</IntroParagraph>

Bare theme names are the first lookup for style values, and `useTheme` exposes
them directly. Themes nest both in the definition and at runtime, and values
resolve upward, ultimately all the way back to tokens.

For the recommended theme setup, see the [Config v6 docs](/docs/core/config-v6).

See the [ThemeBuilder guide](/docs/guides/theme-builder) for generating
custom theme suites.

To style `bento` or `tamagui` components, see
[Styling `tamagui` UI components](#styling-tamagui-components).

For a copy-paste custom palette and recipe tree, see the
[v6 Colors guide](/docs/core/config-v6-colors#add-a-custom-palette).

You define a theme like this:

```tsx
const dark = {
  background: '#000',
  color: '#fff',
  // define any key to any string or number value
}
```

If you use tokens, you can share values from tokens down to themes. Tokens act
as fallback values for themes, like global CSS variables vs scoped ones:

```tsx
const tokens = createTokens({
  color: {
    black: '#000',
    white: '#fff',
  },
})

// theme:
const dark = {
  background: tokens.color.black,
  color: tokens.color.white,
}
```

### Sub-themes

Tamagui supports theme nesting. Define sub-themes using the `parentName_subName`
format, where each segment resolves as a valid theme. Sub-themes can nest across
multiple levels:

- `dark_green_subtle`
- `light_green_subtle`

```tsx
<Theme name="dark">
  <Theme name="green">
    <Button theme="subtle">Hello world</Button>
  </Theme>
</Theme>
```

You can also access a specific sub-theme more specifically:

```tsx
<Theme name="dark">
  <Button theme="green_subtle">Hello world</Button>
</Theme>
```

### Inverse themes

In v3, `inverse` is a real sub-theme generated by the default theme setup. Use
it like any other sub-theme:

```tsx
<Button theme="inverse">Inverted colors</Button>

<Theme name="inverse">
  <Card />
</Theme>
```

The old `themeInverse` prop and `<Theme inverse>` path are removed. Because
`inverse` is a named sub-theme, SSR can emit the right CSS variables without
client-only light/dark inversion. See the
[theme creation guide](/docs/guides/theme-builder#function-children) for custom
theme generation details.

### Forcing a scheme with black and white

`inverse` is relative: it flips whichever scheme its parent happened to be. When
you need a specific scheme instead, use `black` or `white`. They resolve to the
dark and light themes from any parent, including from inside a palette
sub-theme:

```tsx
// dark, wherever this is mounted
<Theme name="black">
  <Card />
</Theme>

// still dark, even though the parent is light and red
<Theme name="light">
  <Theme name="red">
    <Theme name="black">
      <Card />
    </Theme>
  </Theme>
</Theme>
```

Reach for them when a subtree cannot know which scheme it is mounted under, such
as a menu that always reads as dark over a light page. Levels nest inside them
as usual, so `<Theme name="black"><Theme name="level2">` steps within the dark
scheme rather than falling back to the parent's.

Keep themes consistent in shape, sharing the same named keys and typed values.
Sub-themes can define subsets of parent themes. The `useTheme` hook and style
system resolve missing keys upward through parent themes and back to tokens.

#### Component themes

V3 does not select themes from styled component display names. The `displayName`
option sets React's debugging identity and may add an `is_Circle` class, but it
does not make Tamagui search for `light_Circle` or affect style resolution.

Use a normal theme boundary when a component owns a theme operation:

```tsx
import { Theme, View, styled } from 'tamagui'

const CircleFrame = styled(View, {
  displayName: 'Circle',
  backgroundColor: 'background',
})

function Circle(props) {
  return (
    <Theme name="level2">
      <CircleFrame {...props} />
    </Theme>
  )
}
```

This composes under light, dark, color, inverse, and existing level themes
without a second component-specific lookup system.

---

### Styling Tamagui Components

The `tamagui` component suite uses standard semantic theme keys across all
components:

- `background`: component surface color
- `color`: text and icon color
- `border-color`: border color
- `shadow-color`: elevation and shadow color
- `placeholder-color`: placeholder text color

Each key supports interactive pseudo-states: `background-hover`,
`background-press`, and `background-focus`.

Defining these standard keys lets you re-theme both built-in UI components and
your own components consistently across light and dark mode.

A minimal theme might look like this:

```tsx
const dark = {
  // Standard keys for all components
  background: '#000',
  'background-hover': '#111',
  'background-press': '#222',
  'background-focus': '#333',
  color: '#fff',
  'color-hover': '#eee',
  'color-press': '#ddd',
  'color-focus': '#ccc',
  'border-color': '#555',
  'border-color-hover': '#666',
  'border-color-focus': '#777',
  'border-color-press': '#888',
  'placeholder-color': '#999',
  'outline-color': '#aaa',
  // Custom tokens like "brand"
  'brand-background': '#000', // You can add your own tokens like "brand"
  'brand-color': '#fff', // and use them in your components
}

const light = {
  // Standard keys for all components
  background: '#fff',
  'background-hover': '#f5f5f5',
  'background-press': '#e0e0e0',
  'background-focus': '#d5d5d5',
  color: '#000',
  'color-hover': '#111',
  'color-press': '#222',
  'color-focus': '#333',
  'border-color': '#444',
  'border-color-hover': '#555',
  'border-color-focus': '#666',
  'border-color-press': '#777',
  'placeholder-color': '#888',
  'outline-color': '#999',
  // Custom tokens like "brand"
  'brand-background': '#000', // You can add your own tokens like "brand"
  'brand-color': '#fff', // and use them in your components
}
```

You can of course do all of this yourself in your own design system with
`styled`:

If you are building a component with more than one sub-component, you can
follow this pattern:

```tsx
import { GetProps, View, Text, createStyledHOC, styled } from 'tamagui' // or '@tamagui/core'

const ButtonFrame = styled(View, {
  displayName: 'Button',
  backgroundColor: 'background',
})

const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  color: 'color',
})

type ButtonProps = GetProps<typeof ButtonFrame>

// createStyledHOC wraps a functional component so it can be further styled with styled()
// see /docs/core/styled#createstyledhoc for full documentation
export const Button = createStyledHOC(
  ButtonFrame,
  ({ children, ...props }: ButtonProps, ref) => {
    return (
      <ButtonFrame ref={ref} {...props}>
        <ButtonText>{children}</ButtonText>
      </ButtonFrame>
    )
  }
)
```

The frame and text share the active theme. Wrap the composed component in an
explicit named or relative level theme when it needs a different semantic
surface.

## Full Example

Let's start with an example of inline styling with a subset of the
configuration:

```tsx
import { TamaguiProvider, createTokens, createTamagui, html, Theme } from 'tamagui'

const tokens = createTokens({
  color: {
    darkRed: '#550000',
    lightRed: '#ff0000',
  },
  // ... see configuration docs for required tokens
})

const config = createTamagui({
  tokens,
  themes: {
    dark: {
      red: tokens.color.darkRed,
    },
    light: {
      red: tokens.color.lightRed,
    },
  },
})

export const App = () => (
  <TamaguiProvider config={config} defaultTheme="light">
    <html.div backgroundColor="red" />
    <Theme name="dark">
      <html.div backgroundColor="red" />
    </Theme>
  </TamaguiProvider>
)
```

In this example we've set up darkRed and lightRed variables and a dark and light
theme that use those variables. Tamagui will handle defining:

```css
:root {
  --colors-dark-red: #550000;
  --colors-light-red: #ff0000;
}

.tui_dark {
  --red: var(--colors-dark-red);
}

.tui_light {
  --red: var(--colors-light-red);
}
```

Which will automatically apply at runtime, or can be gathered for use in SSR
with `config.getCSS()`.

Finally, the compiler on web will extract your views roughly as so:

```tsx
export const App = () => (
  <Provider defaultTheme="light">
    <div className="baCo-2nesi3" />
    <Theme name="dark">
      <div className="baCo-2nesi3" />
    </Theme>
  </Provider>
)

// CSS output:
//  .color-2nesi3 { background-color: var(--red); }
```

## Ensuring valid types

This structure keeps everything typed. Keep themes in a separate `themes.ts`
file, and structure it like this:

```tsx
import { tokens } from './tokens'

const light = {
  background: '#fff',
  'background-hover': tokens.color['gray-100'],
  'background-press': tokens.color['gray-200'],
  'background-focus': tokens.color['gray-300'],
  'border-color': tokens.color['gray-200'],
  'border-color-hover': tokens.color['gray-400'],
  color: tokens.color['gray-950'],
  'color-hover': tokens.color['gray-800'],
  'color-press': tokens.color['gray-700'],
  'color-focus': tokens.color['gray-400'],
  'shadow-color': 'rgba(0, 0, 0, 0.12)',
}

// note: we set up a single consistent base type to validate the rest:
type BaseTheme = typeof light

// the rest of the themes use BaseTheme
const dark: BaseTheme = {
  background: '#000',
  'background-hover': tokens.color['gray-900'],
  'background-press': tokens.color['gray-800'],
  'background-focus': tokens.color['gray-700'],
  'border-color': tokens.color['gray-800'],
  'border-color-hover': tokens.color['gray-700'],
  color: '#ddd',
  'color-hover': tokens.color['gray-100'],
  'color-press': tokens.color['gray-200'],
  'color-focus': tokens.color['gray-400'],
  'shadow-color': 'rgba(0, 0, 0, 0.25)',
}

const dark_translucent: BaseTheme = {
  ...dark,
  background: 'rgba(0,0,0,0.7)',
  'background-hover': 'rgba(0,0,0,0.5)',
  'background-press': 'rgba(0,0,0,0.25)',
  'background-focus': 'rgba(0,0,0,0.1)',
}

const light_translucent: BaseTheme = {
  ...light,
  background: 'rgba(255,255,255,0.85)',
  'background-hover': 'rgba(250,250,250,0.85)',
  'background-press': 'rgba(240,240,240,0.85)',
  'background-focus': 'rgba(240,240,240,0.7)',
}

export const allThemes = {
  dark,
  light,
  dark_translucent,
  light_translucent,
} satisfies { [key: string]: BaseTheme }
```

## Dynamic Themes

Sometimes you want to defer loading themes, or change existing theme values at
runtime. Tamagui exports three helpers for this in the package `@tamagui/theme`
which exports `addTheme`, `updateTheme`, and `replaceTheme`.

### addTheme

<HeroContainer>
  <AddThemeDemo />
</HeroContainer>

```tsx hero template=AddTheme

```

### updateTheme

<HeroContainer>
  <UpdateThemeDemo />
</HeroContainer>

```tsx hero template=UpdateTheme

```

### replaceTheme

<HeroContainer>
  <ReplaceThemeDemo />
</HeroContainer>

```tsx hero template=ReplaceTheme

```

### Notes

- Dynamic themes only work on the client side and will be ignored on the server
  side.
- The difference between `updateTheme` and `replaceTheme` is that `replaceTheme`
  will replace the entire theme, while `updateTheme` will only update the values
  that are passed in.

### Advanced Optimization

To omit theme objects from a server-rendered web app's client bundle, follow
[Tree shaking themes](/docs/core/tamagui-provider#tree-shaking-themes). That section
covers the CSS and bundler setup required before hydration.


## intro/benchmarks

---
title: Benchmarks
description: Reproducible web and native performance comparisons
---

<IntroParagraph>
  On the iOS uniwind-benchmarks app, Tamagui 3.0.6 rendered 2,003 views in 39.5
  ms and switched themes in 3.5 ms. Both times beat every other themed library,
  Uniwind Pro included. In our Tailwind class suite, Uniwind was fastest in all
  15 native cells and Tamagui Tailwind was second. On web, Tailwind CSS was
  fastest in 10 cells, Tamagui Tailwind in three, and inline React in two.
</IntroParagraph>

Green cells mark the lowest mean in each row. All values are mean milliseconds.
Lower is faster.

## Web results

The web fixture renders 200 items, or 60 in the heavy case. Mount starts with an
empty root. Update changes fixture state without replacing the root. Remount
replaces the tree. Timing starts before the React state change and ends in
`useLayoutEffect`.

Each production build ran in Chromium `151.0.7922.34` on an Apple M5 Pro with 18
logical CPUs and 64 GiB of memory. The runner used Bun `1.3.14` on Darwin
`25.5.0`. Two warmup rounds preceded 10 retained rounds. Seed `73129` shuffled
every framework and scenario round. All 50 behavior checks passed before timing.

Simple, rich, group, and heavy use Tamagui `3.0.0-beta.901.1`. Animated uses
Tamagui `3.0.0-beta.917.1`. The animated compiler flattened all 14 candidates
with zero bailouts. The other versions are Tailwind CSS `4.3.0`, NativeWind
`5.0.0-preview.4`, React Native Web `0.21.2`, Uniwind `1.11.0`, React `19.2.3`,
and React DOM `19.2.3`.

<Wide>
  <SimpleTable
    headers={[
      'Scenario',
      'Operation',
      'Tamagui Tailwind',
      'Tailwind CSS',
      'Inline React',
      'NativeWind v5',
      'Uniwind',
    ]}
    columnWidths={['10%', '10%', '22%', '15%', '15%', '14%', '14%']}
    numericColumns={[2, 3, 4, 5, 6]}
    minWidth={960}
    highlightCells={[
      [0, 3],
      [1, 4],
      [2, 3],
      [3, 3],
      [4, 3],
      [5, 3],
      [6, 2],
      [7, 4],
      [8, 2],
      [9, 3],
      [10, 2],
      [11, 3],
      [12, 3],
      [13, 3],
      [14, 3],
    ]}
    rows={[
      ['Simple', 'Mount', '0.45', '**0.35**', '0.53', '1.60', '1.71'],
      ['Simple', 'Update', '0.96', '0.98', '**0.90**', '2.43', '2.35'],
      ['Simple', 'Remount', '0.55', '**0.44**', '0.63', '1.72', '1.80'],
      ['Rich', 'Mount', '0.57', '**0.33**', '0.90', '1.73', '1.64'],
      ['Rich', 'Update', '1.14', '**1.06**', '1.07', '2.39', '2.59'],
      ['Rich', 'Remount', '0.67', '**0.43**', '0.98', '1.82', '2.11'],
      ['Group', 'Mount', '**0.71**', '0.80', '1.38', '4.21', '5.24'],
      ['Group', 'Update', '2.23', '2.53', '**2.18**', '6.00', '6.92'],
      ['Group', 'Remount', '**0.92**', '1.10', '1.83', '5.75', '6.10'],
      ['Heavy', 'Mount', '0.72', '**0.63**', '1.01', '2.95', '3.11'],
      ['Heavy', 'Update', '**1.67**', '1.80', '1.70', '4.52', '4.42'],
      ['Heavy', 'Remount', '1.06', '**0.93**', '1.34', '3.59', '4.00'],
      ['Animated', 'Mount', '0.42', '**0.31**', '0.57', '1.21', '1.07'],
      ['Animated', 'Update', '1.91', '**1.14**', '1.25', '1.96', '1.81'],
      ['Animated', 'Remount', '2.01', '**1.98**', '2.35', '2.81', '2.95'],
    ]}
  />
</Wide>

Tamagui Tailwind mounted faster than NativeWind and Uniwind in all five web
scenarios. The paired 95% confidence intervals favored Tamagui in each of those
10 comparisons. Tailwind CSS had lower means than Tamagui in 10 of 15 cells.
Inline React had the lowest simple and group update means.

The Tamagui arm uses `@tamagui/tailwind`. This table does not measure Tamagui's
component APIs.

## Native: uniwind-benchmarks

[uniwind-benchmarks](https://github.com/uni-stack/uniwind-benchmarks) is the
benchmark app Uniwind publishes. It renders 2,003 views, then switches between
light and dark themes. Render is the average of 10 re-renders. Theme switch is
the average of 10 theme changes. Each published value is the median of six warm
launches of a Release build with Hermes and the New Architecture.

The Tamagui app uses `@tamagui/core` style props. It runs the compiler with the
[native runtime](/docs/core/native) (`experimental.nativeFastPath`), as
configured in that repository. Every row except Tamagui comes from the
repository's published results. Those were measured on an iPhone 18 Pro Max
simulator running iOS `27.0`, hosted on an Apple M3 Pro. We measured Tamagui
`3.0.6` on the same app beside a StyleSheet control, taking medians over eight
interleaved runs. Then we scaled our times to the published device using the
ratio between the two StyleSheet runs.

<Wide>
  <SimpleTable
    headers={['Library', 'Render (ms)', 'vs StyleSheet', 'Theme switch (ms)']}
    columnWidths={['34%', '22%', '22%', '22%']}
    numericColumns={[1, 2, 3]}
    minWidth={640}
    highlightCells={[
      [1, 1],
      [1, 3],
    ]}
    rows={[
      ['StyleSheet 0.86.3', '37.3', '1.00x', 'no themes'],
      ['Tamagui 3.0.6', '**39.5**', '1.06x', '**3.5**'],
      ['Uniwind Pro 1.8.1', '45.8', '1.23x', '7.7'],
      ['Uniwind Pro 1.0.1', '48.8', '1.31x', '17.1'],
      ['Unistyles 3.5.3', '53.2', '1.43x', '47.1'],
      ['Uniwind 1.12.0', '56.7', '1.52x', '93.2'],
      ['NativeWind 4.2.7', '138.1', '3.70x', '127.6'],
      ['NativeWind 5.0.0-rc.0', '322.7', '8.66x', '211.7'],
    ]}
  />
</Wide>

Green cells mark the fastest themed library in each column. StyleSheet has no
themes, so it is the render baseline.

## Native: Tailwind class suite

All three Release apps render the same `native-class-bench.tsx` fixture. They use
the same class strings, component tree, item counts, state changes, and timing
boundary. Simple, themed, rich, and group render 200 items. Heavy renders 60
three-component groups.

The fixture uses explicit point dimensions. An earlier smoke run found that
`w-5` resolved to 52 points under the benchmark's Tamagui config and 20 points
in the other arms. That fixture was rejected. Fixture version 2 passed an
independent 20 by 20 layout check in all three apps before timing.

The campaign used Tamagui Tailwind `3.0.0-beta.917.1`, NativeWind
`5.0.0-preview.4`, and Uniwind `1.11.0`. NativeWind also used
`react-native-css` `3.0.7`, Reanimated `4.5.1`, and Worklets `0.10.1`. Every app
used Expo `57.0.15`, React `19.2.3`, and React Native `0.86.2`.

The apps ran on an iOS `26.4` simulator on an Apple M5 Pro with 18 logical CPUs
and 64 GiB of memory. The runner used Bun `1.4.0`, Node `26.3.0`, and
XcodeBuildMCP `2.3.0` on Darwin `25.5.0`. It waited until three host samples were
`71.8%`, `63.4%`, and `74.1%` idle. Two warmup rounds preceded 12 retained
rounds. Seed `73129` shuffled every round.

<Wide>
  <SimpleTable
    headers={['Scenario', 'Operation', 'Tamagui Tailwind', 'NativeWind v5', 'Uniwind']}
    columnWidths={['16%', '16%', '24%', '22%', '22%']}
    numericColumns={[2, 3, 4]}
    minWidth={960}
    highlightCells={[
      [0, 4],
      [1, 4],
      [2, 4],
      [3, 4],
      [4, 4],
      [5, 4],
      [6, 4],
      [7, 4],
      [8, 4],
      [9, 4],
      [10, 4],
      [11, 4],
      [12, 4],
      [13, 4],
      [14, 4],
    ]}
    rows={[
      ['Simple', 'Mount', '19.18', '37.41', '**4.13**'],
      ['Simple', 'Update', '15.00', '27.59', '**3.22**'],
      ['Simple', 'Remount', '18.23', '71.99', '**4.03**'],
      ['Themed', 'Mount', '17.91', '53.78', '**3.55**'],
      ['Themed', 'Update', '14.54', '32.98', '**3.57**'],
      ['Themed', 'Remount', '18.10', '48.37', '**3.87**'],
      ['Rich', 'Mount', '39.44', '201.42', '**4.73**'],
      ['Rich', 'Update', '31.41', '108.29', '**4.11**'],
      ['Rich', 'Remount', '39.47', '199.20', '**4.83**'],
      ['Group', 'Mount', '68.48', '516.28', '**15.10**'],
      ['Group', 'Update', '37.35', '196.06', '**11.24**'],
      ['Group', 'Remount', '73.19', '396.69', '**16.60**'],
      ['Heavy', 'Mount', '38.73', '292.36', '**8.16**'],
      ['Heavy', 'Update', '29.00', '68.76', '**5.02**'],
      ['Heavy', 'Remount', '39.99', '318.57', '**8.23**'],
    ]}
  />
</Wide>

Uniwind had the lowest mean in every native cell. Its paired 95% confidence
intervals also favored it over Tamagui in all 15 cells. Tamagui had lower means
than NativeWind in all 15 cells. Several Tamagui and NativeWind paired intervals
overlapped zero because NativeWind's observations varied widely.

## Source record

The cross-framework harness began in `code/comparisons`. It was extracted from
this monorepo in [commit `300a4db8de`](https://github.com/tamagui/tamagui/commit/300a4db8def094229793e2c416b1a008fc5d20a5)
so NativeWind does not enter the main workspace dependency graph.

The web values come from committed receipts `8b45f79809` and `9896f9c488`. The
native values come from fixture source commit `84fc84bb5d` and receipt commit
`352925a2ac`. The native receipt contains all 180
retained observations, 30 warmups, confidence intervals, package versions,
fixture hashes, bundle hashes, build identities, and behavior signatures. The
comparison repository does not have a public remote yet. The web table is also
retained in the [Tamagui Tailwind post](/blog/tailwind-mode).

The monorepo still contains Tamagui's conformance harness, runtime
microbenchmarks, compiler graph benchmark, bundle checks, and browser fixture.

## What this does not measure

- The web run covers production rendering after load. It does not measure server
  rendering, hydration, interaction latency, or network cost.
- The native run uses one simulator. It does not measure a physical device,
  Android, startup, memory, GPU work, or energy use.
- The timers end in `useLayoutEffect`. They include React reconciliation and the
  synchronous native commit. They do not include the next fully drawn frame.
- The behavior gate checks this fixture. It does not prove support or visual
  equivalence for every utility.
- Compiler acceptance and rendered pixels are separate questions.
- Small differences can move with hardware, operating system, library version,
  and application shape.
- Bundle size and build time are tracked separately. Each library ships a
  different mix of runtime and build tooling.


## intro/tokens

---
title: Tokens
description: The default Tamagui token scale and sizing structure
---

<IntroParagraph>
  These are the default `@tamagui/config` tokens that power this site. Your app
  can define its own scale and naming system.
</IntroParagraph>

### Understanding the size scale

Most design systems use pure exponential scaling (2, 4, 8, 16). Tamagui instead uses a hybrid scale: gradual increments from 1 to 10 for fine control across common UI controls, followed by exponential steps from 11 to 16 for large display elements. This gives components a practical range of sizes where small differences matter most.

#### Shared scale keys

Token groups (size, space, radius) and font groups share the same 1 through 16 keys. A size 2 Button naturally aligns with size 2 padding, a size 2 icon, and size 2 text.

#### Sub-unit scale (0.25, 0.5, 0.75)

While the primary scale starts at 1, Tamagui includes three fractional tokens below 1 for fine adjustments, borders, and sub-pixel alignment.

#### Primary scale (1-10)

Sizes 1 through 10 increase gradually for controls and containers. Size 2 suits compact UI elements, size 4 is the standard default size, sizes 5 and 6 provide emphasized controls, and sizes 7 and above serve larger call-to-action blocks.

#### Display scale (11-16)

Sizes 11 through 16 switch to exponential spacing for hero sections and display banners.

<TokensDemo />


## intro/colors

---
title: Colors
description: Color palettes and customization options
---

<IntroParagraph>
  Explore the default color palettes and learn how to configure custom palettes
  with `@tamagui/colors` or Config v6.
</IntroParagraph>

Tamagui defaults to Tailwind-aligned colors in `@tamagui/config/v6`, while also supporting Radix palettes via `@tamagui/colors`. For configuring custom color palettes and recipe-generated adaptive themes, see the [v6 Colors guide](/docs/core/config-v6-colors).

<ColorsDemo />


## intro/design-system

---
title: Design system
description: Tokens, themes, fonts, media queries, and how they reach your styles
---

<IntroParagraph>
  A Tamagui config is a small design system. Style props resolve their values
  against it, so `padding="4"` and `color="color-11"` mean the same thing on
  every screen and every platform.
</IntroParagraph>

Most apps start from the `@tamagui/config/v6` preset and customize from there.
It ships Tailwind's spacing scale, the full Tailwind palette, adaptive light
and dark themes, and Tailwind-aligned shorthands:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui(defaultConfig)

declare module 'tamagui' {
  interface TamaguiCustomConfig extends typeof config {}
}
```

See [Config v6](/docs/core/config-v6) for what the preset contains and
[Configuration](/docs/core/configuration) for building one from scratch.

## Tokens

Tokens are named static values. They become CSS variables on web and plain
values on native, and every style prop accepts a token from the matching
category:

| Category | Style props it feeds | v6 example |
| --- | --- | --- |
| `space` | padding, margin, gap, inset | `padding="4"` is 16px |
| `size` | width, height, min and max sizes | `width="64"` |
| `radius` | borderRadius and its corners | `borderRadius="lg"` |
| `color` | any color prop | `backgroundColor="blue-500"` |
| `zIndex` | zIndex | `zIndex="1"` |

A bare value such as `"4"` looks up the token for that prop's category. Numbers
are pixels, and `"4px"` or `px(4)` forces a pixel value when a token has the
same name. See [Tokens](/docs/core/tokens).

## Themes

Themes are values that change per subtree, most often colors. A theme is an
object of keys, and sub-themes named `parent_child` fall back to their parent:

```tsx
themes: {
  light: { background: '#fff', color: '#000' },
  dark: { background: '#000', color: '#fff' },
  dark_blue: { background: '#0b1a33', color: '#e5efff' },
}
```

Style props read theme keys by name, so `backgroundColor="background"` follows
whichever theme is active. The v6 preset adds an adaptive ramp, `color-1`
through `color-11`, that steps from the page background toward the strongest
foreground in both schemes:

```tsx
<html.div backgroundColor="color-2" borderColor="color-5">
  <html.p color="color-11">Adapts to light and dark</html.p>
</html.div>
```

Switch themes with `<Theme name="dark">` or a `theme` prop. See
[Themes](/docs/intro/themes) for sub-themes, component themes, and inverse
themes, and [Creating themes](/docs/guides/theme-builder) to generate full
suites.

## Fonts

Fonts are tokens with structure. Each family carries its own size, line height,
weight, and letter spacing scales, so `fontSize="lg"` and `lineHeight="lg"`
pull from the same family. Text components pick a family with `fontFamily`, and
`SizableText`, `Paragraph`, and the headings take a `size` prop that sets all
four at once:

```tsx
<html.p fontFamily="body" fontSize="lg" lineHeight="lg">
  Body copy
</html.p>

<Paragraph size="lg">Body copy</Paragraph>
```

See [Fonts](/docs/core/fonts) for `createFont`, native font files, and
per-language fonts.

## Media queries

Named media queries in the config become modifiers on every style prop, keys
on `useMedia`, and container query names:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div
  flexDirection={{ default: 'column', md: 'row' }}
  padding={{ default: '4', lg: '8' }}
/>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div flexDirection="column md:row" padding="4 lg:8" />
```

</MDXTabs.Content>
</MDXTabs>

The v6 preset defines `xs`, `sm`, `md`, `lg`, `xl`, and `xxl` as min-width
queries with matching `max-sm` style variants, plus `hoverable` and
`touchable`. See [useMedia](/docs/core/use-media).

## Where the pieces meet

```tsx
<html.button
  paddingHorizontal="4"
  paddingVertical="2"
  borderRadius="md"
  backgroundColor="background hover:background-hover press:background-press"
  color="color"
  fontSize="sm md:base"
>
  Save
</html.button>
```

Spacing and radius come from tokens, colors from the active theme, font size
from the body font, and `md:` from the media config. The compiler turns all of
it into atomic CSS on web, and the runtime resolves the same values on native.


## intro/styles

---
title: Styling
description: Style props, conditional values, and the modifiers that control them
---

<IntroParagraph>
  Tamagui uses style props across all components. Every element accepts React
  Native and web styles, with unified support for responsive, theme, and pseudo-state
  conditions.
</IntroParagraph>

```tsx
import { Text, View } from 'tamagui'

export const Card = () => (
  <View
    padding="4 md:6"
    borderRadius="lg"
    backgroundColor="background hover:background-hover"
  >
    <Text color="color-11">Hello</Text>
  </View>
)
```

`padding`, `borderRadius`, and `backgroundColor` are style props. `"4"` and
`"lg"` are tokens, `background` is a theme key, and `md:` and `hover:` are
modifiers. That is the whole grammar. The same props go on `View`, `Text`,
every other [component](/docs/intro/components), and the second argument of
[`styled()`](/docs/core/styled).

Every style prop takes its value as a string or an object. Strings fit the
base value and its conditions into one short read:

```tsx
<View padding="4 md:8" backgroundColor="background hover:background-hover" />
```

Objects spell the same thing with keys, and stay fully typed:

```tsx
<View
  padding={{ default: '4', md: '8' }}
  backgroundColor={{ default: 'background', hover: 'background-hover' }}
/>
```

Use strings for short, mostly static values — a prop with one or two
conditions, written inline. They exist so the common case stays terse and
readable. Use objects when the value is a number (numbers skip token lookup,
so `padding={16}` is always 16 pixels), when conditions stack up, or when you
build the value in code from variables and spreads — objects are real values,
so TypeScript checks every token and modifier as you type. Both spellings take
the same values and modifiers and render identically, so mix them per prop as
needed. The Conditional values section below details each spelling.

## Values

A style value is one of:

| Value | Example | Resolves to |
| --- | --- | --- |
| Number | `padding={16}` | 16 pixels on every platform |
| Pixel string | `padding="16px"` | An exact pixel value, even when a token has the same name |
| Token | `padding="4"`, `borderRadius="lg"` | The token from that prop's category |
| Theme key | `color="color-11"` | The active theme's value, updating when the theme changes |
| CSS value | `display="flex"`, `boxShadow="0 2px 8px shadow-3"` | Passed through on web and converted on native |
| `rem` | `padding="1rem"` | Scaled by the user's font size on native |

[Design system](/docs/intro/design-system) covers where tokens and theme keys
come from. [Style props](/docs/core/style-props) lists every prop, including
the ones that only render on web.

## Conditional values

Every style prop takes conditions in two spellings, a string of clauses or a
flat object. These render the same thing:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<View
  backgroundColor={{
    default: 'red',
    hover: 'blue',
    sm: 'green',
    'sm:hover': 'purple',
  }}
/>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<View backgroundColor="red hover:blue sm:green sm:hover:purple" />
```

</MDXTabs.Content>
</MDXTabs>

The object keys are the same modifiers the string uses, with `default` for the
base value. There is no mode to pick, and you can mix them per prop in one
component:

```tsx
<View backgroundColor="red hover:blue" scale={{ press: 0.98 }} />
```

Strings are shorter for one or two conditions. Objects work better when the
values are numbers, when the conditions stack up, or when you build the value
in code. Both compile to identical CSS.

An object only counts as conditional when it has a `default` key or its first
key is a valid modifier. A plain value object like
`shadowOffset={{ width: 0, height: 2 }}` is left alone.

## Font size and line height values

Numeric `lineHeight` authored in Tamagui styles is a font-size ratio on web and
native. A numeric string has the same ratio meaning when it is not a configured
font-token name. An explicit px string stays absolute. Values are never inferred
from magnitude, so `lineHeight={24}` means 24 times the effective font size and
`lineHeight="24px"` means 24 pixels.

Font configuration keeps a separate compatibility contract. Numeric
`lineHeight` entries remain absolute pixels. Use a numeric string for a relative
font token and a px string for an explicit absolute token:

```tsx
<Text fontSize={17}>Platform line height</Text>
<Text fontSize="17px">Exact px size</Text>
<Text fontSize={20} lineHeight={1.5}>30px line box</Text>
<Text lineHeight="24px">24px line box</Text>

const bodyFont = createFont({
  family: 'Inter',
  size: { body: 20 },
  lineHeight: {
    legacy: 24, // absolute pixels
    relative: '1.5', // ratio
    explicit: '24px', // absolute pixels
  },
})
```

On native, Tamagui can resolve a ratio from the effective font size inherited
through Tamagui text. This inheritance continues through intervening Tamagui Views,
as it does on web. When a Tamagui text boundary sits below a raw React Native
or third-party text parent, pass the effective font size at that boundary because
Tamagui cannot inspect typography held only by the native host tree.

If a native ratio has no known font size, Tamagui explicitly sets `fontSize={14}`
and calculates the line height from 14. This also applies below a raw native text
parent, so pass its font size at the Tamagui boundary to preserve the glyph size.

## Modifiers

Every modifier applies to just the property carrying it. They fall into five
groups:

| Group | Modifiers | Example |
| --- | --- | --- |
| State | `hover:`, `press:`, `focus:`, `focus-visible:`, `focus-within:`, `disabled:` | `scale="press:0.98"` |
| Screen size | any media name from your config, such as `sm:` or `max-md:` | `padding="4 md:8"` |
| Theme | `dark:`, `light:`, or a top-level theme name | `color="dark:white"` |
| Platform | `web:`, `native:`, `ios:`, `android:` | `paddingTop="ios:12"` |
| Parent | `group-hover:`, `group-press:`, `group-focus:`, `@sm:` container queries | `color="group-hover:white"` |

Modifiers stack. `sm:hover:purple` applies on hover at the `sm` breakpoint.
When several clauses match, the most specific one wins.
[Flat conditional values](/docs/guides/flat-values) has the full precedence rules and
grammar.

### States

Add state clauses directly to the property they change:

- **`hover:`**: while hovering (web only, maps to CSS `:hover`)
- **`press:`**: while pressing
- **`focus:`**: while focused (maps to CSS `:focus`)
- **`focus-visible:`**: while keyboard-focused (maps to CSS `:focus-visible`)
- **`focus-within:`**: while a child has focus (maps to CSS `:focus-within`)
- **`disabled:`**: while `disabled={true}`

```tsx
<View
  backgroundColor="background hover:background-hover press:background-press"
  scale="press:0.98"
  outlineColor="focus-visible:blue-500"
  outlineWidth="focus-visible:2px"
  outlineStyle="focus-visible:solid"
  borderColor="focus-within:blue-500"
  opacity="disabled:0.5"
/>
```

`hover:` is web only. `focus:`, `focus-visible:`, and `focus-within:` map to the
matching CSS pseudo-classes on web.

### Enter and exit

For mount and unmount animations, `enter:` is the value the property animates
from on mount, and `exit:` is the value it animates to on unmount:

```tsx
<View opacity="enter:0 exit:0" />
```

See [Animations](/docs/core/animations).

### Screen size

Media queries come from `createTamagui({ media })`. Each name is a modifier on
native and web:

```tsx
<Text color="red sm:blue" />
```

### Theme and platform

Theme modifiers target top-level themes. With `light` and `light_subtle`
defined, only `light` can be targeted. Platform modifiers cover `ios`,
`android`, `web`, and `native`:

```tsx
<Text color="dark:white ios:white" />
```

### Groups

Mark a parent with `group` and children can react to its state:

```tsx
<View group>
  <Text color="gray group-hover:white" />
</View>
```

The states are `hover` (web only), `press`, and `focus`. Name a group to
target it from further down:

```tsx
<View group="card">
  <View group>
    <Text color="gray group-hover/card:blue">Inner</Text>
    <Text color="gray group-hover:green">Sibling</Text>
  </View>
</View>
```

`Inner` turns blue when the `card` group is hovered. `Sibling` turns green
when its nearest group is hovered. For completion on named groups, declare
them next to your config types:

```tsx
declare module 'tamagui' {
  interface TamaguiCustomConfig extends AppConfig {}

  interface TypeOverride {
    groupNames(): 'card' | 'header' | 'sidebar'
  }
}
```

### Container queries

Add `container` to a group and children can respond to the parent's size,
using the same media names. Web outputs a CSS container query:

```tsx
<View group container>
  <Text color="gray @sm:white @sm:group-hover:green" />
</View>
```

Named containers work the same way with `@sm/card:`.

On native the container's size is only known after the first `onLayout`, so
children render once before the query applies. Set `untilMeasured="hide"` on
the container to keep it at opacity 0 until measured, or give the container an
explicit `width` and `height` so children can resolve the query on first
render.

## Next

- [Style props](/docs/core/style-props) for every accepted property and how it
  renders per platform.
- [styled()](/docs/core/styled) and [Variants](/docs/core/variants) for
  reusable components.
- [Flat conditional values](/docs/guides/flat-values) for the complete value
  grammar and editor support.


## intro/static

---
title: Static Optimization
description: How @tamagui/static optimizes code at build time
---

<IntroParagraph>
  The Tamagui compiler turns component styles into atomic CSS and flattened
  platform primitives at build time.
</IntroParagraph>

For details on how the compiler optimizes your code through static analysis:

- [Why a compiler](/docs/intro/introduction#why-a-compiler): architectural background on compiler benefits
- [Compiler Installation](/docs/intro/compiler-install): how to set up the compiler in your project
- [Benchmarks](/docs/intro/benchmarks): performance measurements across platforms


## intro/introduction

---
title: Introduction
---

<DocsIntro />

<GetStarted />

## Two ways to write styles

Tamagui ships two styling frontends. Both compile to the same atomic CSS on web
and the same native styles on iOS and Android, and both accept the same tokens,
themes, and media queries.

**Style props** on `View` and `Text` are the default. They are typed and
compile to atomic CSS on web or native styles on iOS and Android:

```tsx
import { Text, View } from 'tamagui'

export const Card = () => (
  <View padding="4" borderRadius="lg" backgroundColor="background">
    <Text fontSize="6">Hello</Text>
    <Text color="color-11 hover:color-12">World</Text>
  </View>
)
```

**Tailwind** classes on `className` are the other option, for teams who already
think in utilities:

```tsx
import { Text, View } from '@tamagui/tailwind'

export const Card = () => (
  <View className="p-4 rounded-lg bg-background">
    <Text className="text-2xl">Hello</Text>
    <Text className="text-color-11 hover:text-color-12">World</Text>
  </View>
)
```

The choice is per import path, so one app can use both. Read
[Components](/docs/intro/components) for the style prop path and
[Tailwind](/docs/core/tailwind) for the utility path.

## Why a compiler

Cross-platform development often involves trade-offs between native feel, code reuse, and performance. React Native shares logic across platforms, but on web, styling in JavaScript can mean heavy runtime overhead and larger bundles.

Tamagui resolves this with `@tamagui/static`, an optimizing compiler that:

<YStack py="4">
  <Features
    size="5"
    items={[
      `Extracts every style prop, media query, theme value, and interactive state into atomic CSS.`,
      `Removes most inline styles through partial evaluation and hoisting.`,
      `Flattens styled components into a plain div or View, so the tree gets shallower.`,
      `Turns useMedia and useTheme expressions into media queries and CSS variables.`,
    ]}
  />
</YStack>

Here is what that looks like in code:

<TamaguiExamplesCode />

The `Text` became a `p` and the `YStack` became a `div`. On native the same
pass produces `Text` and `View`. Flattening is where most of the speed comes
from. Across real apps around a third to a half of components flatten, and the
result on web is close to hand-written CSS. On native the output is within a
few percent of hand-optimized React Native, with the whole feature set intact.

Everything still works at runtime. The compiler is an optimization you can add
later, and a component it cannot optimize simply renders the normal way. See
[Benchmarks](/docs/intro/benchmarks) for numbers and
[Compiler installation](/docs/intro/compiler-install) to turn it on.

## Where to go next

- [Installation](/docs/intro/installation) sets up a project or hands the job
  to a coding agent.
- [Components](/docs/intro/components) covers `html.*`, `View`, `Text`, and how
  they render on each platform.
- [Styling](/docs/intro/styles) explains style props, conditional values, and
  states.
- [Design system](/docs/intro/design-system) introduces tokens, themes, and
  fonts.
- [Tailwind](/docs/core/tailwind) covers the utility class frontend.

#### Highlights

<Highlights
  disableLinks
  disableTitle
  large
  features={[
    `Core depends only on React and supports the full React Native View and Text APIs, style props, styled(), hooks, and typed design tokens in ~28KB on web.`,
    `The optimizing compiler extracts styles into atomic CSS and flattens styled components at build time.`,
    `Every feature works with or without the compiler, with graceful fallback to runtime resolution.`,
    `useTheme and useMedia hooks provide fine-grained subscription updates.`,
    `Unstyled and styled variants are available for all components.`,
  ]}
/>

---

## Community

Join us on:

- [Discord](https://discord.gg/4qh6tdcVDa)
- [X](https://x.com/tamagui_js)
- [GitHub](https://github.com/tamagui/tamagui)

---

## Credits

A big thanks to:

- [Stitches](https://stitches.dev) for the variants pattern.
- [JSXStyle](https://github.com/jsxstyle/jsxstyle) for providing the original
  version of the compiler.
- [Modulz](https://github.com/modulz) for Radix, which inspired many of our component APIs, and for the initial structure of this website.
- [Framer Motion](https://github.com/framer/motion) for the AnimatePresence
  implementation.


## intro/installation

---
title: Installation
description: Get Tamagui set up, step by step
---

<IntroParagraph>
  Tamagui installs with no bundler configuration on web or native. Start small,
  and add the compiler and bundler plugins once the basics work.
</IntroParagraph>

The fastest start is a starter template:

```bash
npm create tamagui@latest
```

## Requirements

- **React 19+**
- **TypeScript 5+**
- **React Native 0.81+** with the New Architecture enabled, for native apps.
  Tamagui uses newer style features such as `boxShadow` and `filter`. On web
  there are no version restrictions.

## Install

Install the full UI kit:

```bash
yarn add tamagui @tamagui/config
```

Or install only the style library. The `tamagui` package is a superset of
`@tamagui/core`, so anywhere the docs reference core you can use either:

```bash
yarn add @tamagui/core @tamagui/config
```

## Choose a styling frontend

Tamagui has two ways to write styles. Both produce the same output, and the
choice is per import path, so you can mix them later. Pick one to start.

<MDXTabs id="frontend" defaultValue="props">
<MDXTabs.List>
  <MDXTabs.Tab value="props">Style props</MDXTabs.Tab>
  <MDXTabs.Tab value="tailwind">Tailwind</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="props">

Typed style props on `View`, `Text`, and every other Tamagui component. This is
the default for new apps. It reads like React Native and needs no extra package.

```tsx fileName="App.tsx"
import { TamaguiProvider, View, createTamagui } from 'tamagui'
import { defaultConfig } from '@tamagui/config/v6'

const config = createTamagui(defaultConfig)

declare module 'tamagui' {
  interface TamaguiCustomConfig extends typeof config {}
}

export default () => (
  <TamaguiProvider config={config} defaultTheme="light">
    <View width={200} height={200} backgroundColor="background" />
  </TamaguiProvider>
)
```

Continue with [Components](/docs/intro/components) and
[Styling](/docs/intro/styles).

</MDXTabs.Content>

<MDXTabs.Content value="tailwind">

Tailwind utility classes on `className`, extracted to atomic CSS on web and
resolved to native styles on iOS and Android.

```bash
yarn add @tamagui/tailwind
```

```tsx fileName="App.tsx"
import { TamaguiProvider, createTamagui } from 'tamagui'
import { View } from '@tamagui/tailwind'
import { defaultConfig } from '@tamagui/config/v6'

const config = createTamagui(defaultConfig)

declare module 'tamagui' {
  interface TamaguiCustomConfig extends typeof config {}
}

export default () => (
  <TamaguiProvider config={config} defaultTheme="light">
    <View className="w-[200px] h-[200px] bg-background" />
  </TamaguiProvider>
)
```

Continue with [Tailwind](/docs/core/tailwind).

</MDXTabs.Content>
</MDXTabs>

You usually export the config from a `tamagui.config.ts` file. See
[Configuration](/docs/core/configuration) for what goes in it.

Set your root theme with the `defaultTheme` prop on `TamaguiProvider` rather
than wrapping the app in `<Theme>`. That keeps the
[`fastSchemeChange` setting](/docs/core/settings) working on native and lets
light and dark switch through media queries during SSR on web.

That is the whole setup:

<Preview>
  <DemoButton />
</Preview>

```tsx class=preview line=5
import { Button } from 'tamagui'

export default function Demo() {
  return <Button theme="blue">Hello world</Button>
}
```

Every feature works at runtime, so nothing above depends on a bundler plugin.
When you are ready for production, [set up the compiler](/docs/intro/compiler-install)
for smaller bundles and faster renders.

## Bundler guides

Tamagui itself needs no bundler setup. React Native and React Native Web
tooling often does, so Tamagui ships plugins that handle it:

<Spacer />

<Grid gap="4">
  <LogoCard
    title="Next.js"
    img="/logos/next-js.svg"
    link="/docs/guides/next-js"
    subtitle="React framework for web applications."
    colorOffset={2}
  />
  <LogoCard
    title="Expo"
    img="/logos/expo.svg"
    link="/docs/guides/expo"
    subtitle="Universal React Native application platform."
    colorOffset={6}
  />
  <LogoCard
    title="Vite"
    img="/logos/vite.svg"
    link="/docs/guides/vite"
    subtitle="Frontend build tool and development server."
    colorOffset={1}
  />
  <LogoCard
    title="Webpack"
    img="/logos/webpack.svg"
    link="/docs/guides/webpack"
    subtitle="Configurable JavaScript module bundler."
    colorOffset={0}
  />
  <LogoCard
    title="Metro"
    img="/logos/metro.svg"
    link="/docs/guides/metro"
    subtitle="Default JavaScript bundler for React Native."
    colorOffset={3}
  />
  <LogoCard
    title="One"
    img="/logos/one.svg"
    link="/docs/guides/one"
    subtitle="Universal React framework for web and native."
    colorOffset={4}
  />
</Grid>

## Next steps

- **[CLI](/docs/core/cli)** for building, checking versions, and generating
  agent prompts.
- **[Design system](/docs/intro/design-system)** for tokens, themes, and fonts.
- **[Custom UI package](/docs/guides/design-systems)** to build your own
  optimized component library.


## intro/components

---
title: Components
description: The elements you build with, and what they render on each platform
---

<IntroParagraph>
  Every Tamagui component takes style props. This page covers the base elements
  those props go on, and which one to use when.
</IntroParagraph>

## View and Text

`View` and `Text` are the two primitives everything else is built on. They match
React Native's `View` and `Text` and add the Tamagui style props on top:

```tsx
import { View, Text } from 'tamagui'

export const Hello = () => (
  <View padding="4" gap="2">
    <Text fontSize="6">Hello</Text>
    <Text color="color-11">The same layout on iOS, Android, and web.</Text>
  </View>
)
```

Use them by default. A `View` is a flex column on every platform, so a layout you
build once looks the same on web and native. On web they render a `div` and a
`span`, and you can change the tag with [`render`](/docs/core/styled#render) when
you need semantic HTML, such as `<View render="nav">`.

See [View & Text](/docs/core/view-and-text) for the full prop reference,
including event handlers and the non-style props Tamagui adds.

## Reusable components with styled()

`styled()` wraps any of the above into a named component with default styles
and typed variants. Inline props and `styled()` are both optimized by the
compiler, so pick whichever reads better:

```tsx
import { styled, View } from 'tamagui'

export const Card = styled(View, {
  padding: '4',
  borderRadius: 'lg',
  backgroundColor: 'background',

  variants: {
    elevated: {
      true: { boxShadow: '0 4px 12px shadow-3' },
    },
  } as const,
})

// <Card elevated />
```

See [styled()](/docs/core/styled) and [Variants](/docs/core/variants).

## Themes in the tree

`Theme` switches the theme for a subtree, and any component takes a `theme`
prop for the same thing at one level:

```tsx
import { Button, Theme } from 'tamagui'

export const Panel = () => (
  <Theme name="dark">
    <Button>Dark</Button>
    <Button theme="blue">Dark blue</Button>
  </Theme>
)
```

See [Theme](/docs/core/theme) for `ThemeUpdate`, custom variables, and how
sub-themes resolve.

## The UI kit

The `tamagui` package adds styled, accessible components on top of these
primitives: `Button`, `Dialog`, `Sheet`, `Select`, and the rest of the
[UI kit](/ui/intro). Every one of them accepts `unstyled` to drop its default
styles and keep only its behavior.

## HTML elements

The `html` export has an element for each semantic HTML tag, such as
`html.article`, `html.h1`, and `html.p`. On web each one renders that tag, and on
native it renders the matching React Native primitive. It follows web and
[React Strict DOM](https://facebook.github.io/react-strict-dom/) semantics, which
makes it a good fit for screens that are mostly web content, like docs,
marketing pages, and articles.

```tsx
import { html } from 'tamagui'

export const Article = () => (
  <html.article maxWidth={720} margin="auto" padding="4 md:8">
    <html.h1 fontSize="8">A semantic heading</html.h1>
    <html.p color="color-11" marginTop="4">
      Renders an article, h1, and p on web.
    </html.p>
  </html.article>
)
```

`html.*` is in early development. Its elements keep the browser's default
`display`, so `html.div` is `display: block` on web, while React Native only
supports flex layout. A layout built from `html.*` can therefore look different
on native. Use `View` and `Text` when the same screen has to look the same
everywhere. See [HTML elements](/docs/core/html-primitives) for the element list
and native rules.

## Prefer utility classes?

The same elements exist in `@tamagui/tailwind`, styled with `className`
instead of props. See [Tailwind](/docs/core/tailwind).


## guides/how-to-upgrade

---
title: Upgrading to v3
description: A complete guide for migrating Tamagui v2 apps to Tamagui v3.
---

<IntroParagraph>
  Tamagui v3 removes deprecated APIs, makes tokens and themes more predictable,
  and gives every adaptive overlay the same composition model.
</IntroParagraph>

Most migrations are mechanical, but the Sheet anatomy, token changes, and focus
behavior should be verified in real screens.

<Notice theme="blue">
  If you are on v1, migrate through the v2 guide first or run the v1-to-v3 AI
  migration prompt from the CLI. v3 assumes the v2 web-standard prop model,
  defaults to Config v6, and has a React 19, React Native 0.81+, and TypeScript
  5+ baseline.
</Notice>

## Start with a smaller, complete upgrade

The runtime version and config version are separate. **V3 APIs with your existing
design values is the recommended first checkpoint.**

- **From V2:** migrate the packages and required APIs while preserving your token,
  theme, font, media, and animation values. Do not replace a custom config with
  v6 defaults as part of the syntax conversion.
- **From Config v5 or v5-subtle:** keep that supported config through the API
  migration. Keep its 12-step colors and physical scales; the v6 remaps later in
  this guide are for a separate design migration.
- **Already on V3 with Config v5:** check the remaining API work and validate it.
  You do not need to adopt Config v6 to finish upgrading to V3.

Record representative screens before editing. Finish with typecheck, build, report
review, and the same browser/native interactions and screenshots. Defer Config v6,
wholesale `html.*` conversion, and Tailwind adoption unless you chose them as
separate work. The agent setup prompt makes this checkpoint explicit:

<CopyAgentSetupButton type="upgrade" my="2" />

## Required: migrate tokens and conditional styles

V3 accepts bare token and theme names, with conditions expressed as typed
objects or string clauses on each style property. There is no runtime
compatibility path for sigil-prefixed values or V2 condition objects such as
`hoverStyle`.
Run the codemod from your project root before the API-specific steps below:

```bash
npx @tamagui/codemod-flat-values \
  --source-semantics v2-pixels \
  --report flat-values-report.md \
  ./src

npx @tamagui/codemod-flat-values --write \
  --source-semantics v2-pixels \
  --report flat-values-report.md \
  --json flat-values-report.json \
  ./src
```

For example, this V2 migration input:

```tsx
<View
  bg="$background"
  hoverStyle={{ bg: '$backgroundHover' }}
  $sm={{ p: '$6' }}
  p="$4"
/>
```

becomes:

```tsx
<View bg="background hover:background-hover" p="4 sm:6" />
```

Read and hand-fix every flagged report row, then rerun until the migrated path
has no V2 authoring sites. See [Flat Conditional Values](/docs/guides/flat-values)
for the grammar and full workflow.

### Declare query containers separately from groups

`group` now provides parent interaction state only. It no longer adds CSS
containment or native layout measurement. A named size clause needs an explicit
container on the ancestor it targets:

```tsx
// before: group implicitly established the query container
<View group="card">
  <Text width="100% @sm/card:50%" />
</View>

// after: state and containment are authored separately
<View group="card" container="card">
  <Text width="100% @sm/card:50%" />
</View>
```

Use `container` for an unnamed inline-size container, `container="main"` for a
named inline-size container, and `container="main" containerType="size"` for
containment on both axes. `container={false}` and `container={undefined}` do
nothing, so conditional roots can use `container={isRoot}`. Raw CSS
`containerName` and `containerType` longhands remain available in `style()` and
style objects. An explicit longhand wins the property it names when used with
`container`.

Remove `webContainerType` from `createTamagui` settings. V3 has no global
container-type compatibility setting.

Plan for that review before starting a large migration. On the V2 Bento corpus,
the codemod found 2,113 sites. It classified 1,681 as clean and left 412 of
2,052 JSX sites plus 20 of 61 `styled()` configuration sites for a person to
review. That is 432 sites, or 20.4% of the corpus. After the proposed conversion,
63 of 208 files still contained legacy condition objects. A successful codemod
run means the report was generated, not that the application is ready for V3.

## 1. Update packages

Bump all `tamagui` and `@tamagui/*` packages together. The `tamagui` command
is `@tamagui/cli`, so add it as a dev dependency first if the app does not have
it yet.

```bash
npx tamagui check
```

Then install the v3 versions with your package manager and make sure your lockfile
does not contain duplicate `@tamagui/core`, `@tamagui/web`, or `tamagui` copies.

### Choose the component surface

V3 gives each styling mode an explicit import path. Import the default styled skin
from its generated `tamagui/<component>` subpath:

```tsx
import { Button } from 'tamagui/button'
import { Toast, toast } from 'tamagui/toast'
```

The `tamagui` root remains the convenient full barrel. Component subpaths are the
smaller delivery path for apps and compiler configuration that only need selected
skins. Use `tamagui/unstyled` or `@tamagui/ui` for behavior primitives without the
default skin, and `@tamagui/tailwind` for Tailwind-authored primitives. The Styled,
Unstyled, and Tailwind switch above every v3 docs page changes examples between
these authoring modes.

The V3 roots for `Avatar`, `Tabs`, and `Group` retain behavior and structural
layout, but no longer supply the old opinionated visual defaults. There are no
`tamagui/avatar` or `tamagui/group` default-skin subpaths. Keep the behavior
imports and add the exact visual styles your application needs:

```tsx
import { Avatar, Tabs, styled } from 'tamagui'

const AppAvatar = styled(Avatar, {
  borderWidth: 1,
  borderColor: 'border-color',
})

const AppTab = styled(Tabs.Tab, {
  paddingHorizontal: '3',
  paddingVertical: '2',
  activeStyle: { backgroundColor: 'background-press' },
})
```

Apply the same treatment to `Group` and its children. Existing code that relied
on V2 defaults can still compile while rendering without that chrome, so inspect
these components visually rather than relying only on typecheck.

Remove tooling packages that no longer exist in v3:

| Removed package            | Migration                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `@tamagui/babel-plugin`    | Install `@tamagui/cli` and use `@tamagui/cli/vite`, `@tamagui/cli/metro`, or the `tamagui build` precompile command for Turbopack. |
| `@tamagui/get-button-sized`| Call `resolveSizing` from `@tamagui/core` with the size name; see §5. |
| `@tamagui/sizable-context` | Use `createStyledContext` from `@tamagui/core` with your own size names.                                          |
| `@tamagui/static-sync`     | Remove direct imports. Compiler sessions are owned by the supported bundler adapters.                         |
| `@tamagui/static-worker`   | Remove direct imports. Metro owns its graph/cache workers through `@tamagui/cli/metro`.                       |
| `@tamagui/theme-builder`   | Freeze the generated themes or use `@tamagui/config-v5` for the intermediate checkpoint. Adopt `@tamagui/themes/builder` recipes only in a separate v6 migration. |

### LinearGradient needs no native setup

`LinearGradient` draws a `backgroundImage` gradient on native, so
`@tamagui/native/setup-expo-linear-gradient` is gone. Delete that import, and
remove `expo-linear-gradient` from your dependencies unless your own code uses
it. Native gradients need React Native 0.76 or later with the new
architecture.

### Config and theme compatibility

V3 defaults to Config v6. It also keeps frozen static v5 and v5-subtle packs so
existing applications can preserve their token values and generated themes
while migrating the rest of the v3 API.

The dynamic v5 theme builders are not part of `@tamagui/config`. An application
that generates its own v5 themes with `createV5Theme`, `subtleChildrenThemes`,
or `@tamagui/theme-builder` has three options:

1. **Freeze the generated themes.** The builder is a value generator. Run it
   once on your current version, serialize the result to a static literal, and
   the application stops importing the removed API while every resolved value
   survives unchanged. This is the cheapest path and the right one whenever the
   palette is settled, especially if its values were measured or tuned against a
   visual reference.
2. **`@tamagui/config-v5`**, an opt-in package carrying the dynamic builders.
   It is deliberately separate from `@tamagui/config` so the builder code and
   its dependencies stay out of the default install.
3. **Rebuild on the v6 recipe API.** The real destination, and a migration to
   schedule on its own rather than alongside the flat-values conversion.

No config bundles an animation driver, so import one alongside it. The old
`v5-*` animation paths remain aliases for compatibility, while the unversioned
paths are preferred for new code.

| V2 entry | V3 status or replacement |
| --- | --- |
| `@tamagui/config` (root, `config` / `configWithoutAnimations`) | `defaultConfig` from `@tamagui/config/v6` |
| `@tamagui/config/v3` or `/v4` | `defaultConfig` from `@tamagui/config/v6` |
| `@tamagui/config/v5` or `/v5-subtle` | Retained as frozen static compatibility packs. Use `/v6` for new applications. |
| `@tamagui/config` `animations` / `reanimated` | `@tamagui/config/animations-css`, `animations-rn`, `animations-reanimated`, or `animations-motion` |
| `@tamagui/config/v5-css`, `/v5-rn`, `/v5-reanimated`, or `/v5-motion` | Retained aliases for the matching unversioned animation entries. |
| old config `fonts`, `media`, `breakpoints`, and `shorthands` | the matching exports from `@tamagui/config/v6-base` |
| `@tamagui/config` `createGenericFont` | `createSystemFont` from `@tamagui/config/v6-base` |
| old `@tamagui/themes` root behavior | v6 static `themes` and `tokens` from `@tamagui/themes` |
| `@tamagui/themes/v5`, `/v5-subtle`, or `/v5-tokens` | Retained as frozen static compatibility packs. The `/v5-builder` entries are removed. |
| `@tamagui/theme-builder` | recipe helpers from `@tamagui/themes/builder` |
| `@tamagui/colors/legacy` (the pre-v2 Radix ramps: `blue`/`blueDark`, `gray`/`grayDark`, …) | `@tamagui/colors`, which exports the same names from the current Radix scales |

The v6 replacements above adopt new design defaults. For the intermediate
checkpoint, retain `@tamagui/config/v5` or `/v5-subtle` and import
`defaultConfig` from that entry. If coming from older config entries or custom
builders, freeze their resolved tokens and themes before replacing the removed
imports; switching to v5 or v6 by name does not preserve those values.

For example, when separately adopting v6:

```tsx
// before
import { config } from '@tamagui/config/v4'
import { createAnimations } from '@tamagui/animations-moti'

// after
import { defaultConfig } from '@tamagui/config/v6'
import { createAnimations } from '@tamagui/animations-reanimated'
```

### Replace the React Native animation driver on web

V3 keeps `@tamagui/animations-react-native` on native and removes its web
implementation. A web config that calls its `createAnimations` now throws during
setup. Choose `@tamagui/animations-css`, `@tamagui/animations-motion`, or
`@tamagui/animations-reanimated` for web. Use platform-specific config files if the
same application keeps `@tamagui/animations-react-native` on native.

Apps that use Sheet or the animated-number hooks with the CSS driver must import
`createAnimations` from `@tamagui/animations-css/extras`. The root
`@tamagui/animations-css` entry omits those hooks, so Sheet throws when it tries
to animate its position.

Remove `@tamagui/babel-plugin` from Babel configuration and dependencies. Vite
and Metro perform compilation through their dedicated plugins:

```tsx
// before: babel.config.js
plugins: ['@tamagui/babel-plugin']

// after: vite.config.ts
plugins: [tamaguiPlugin(tamaguiOptions)]

// after: metro.config.js
config = withTamagui(config, tamaguiOptions)
```

### Clear Metro after config changes

The Metro plugin does not yet invalidate Metro's transform cache when a
Tamagui lowering plan changes but the app source does not. After editing
`tamagui.config.ts` or another compiler input, stop the live Metro process and
restart it with a cleared cache:

```bash
npx expo start -c
```

For a warm CLI production build, remove the app-local Tamagui cache and use the
Expo command's Metro reset flag:

```bash
rm -rf node_modules/.cache/tamagui
npx expo export --clear
# native embedded bundle: add --reset-cache to expo export:embed
```

Without this step, Metro can serve stale compiled output from the earlier plan.
Expect the first rebuild after clearing caches to be slower because Metro must
replan every module. We measured about 12 ms per module: roughly 27
seconds for a 2,328-module starter and about two minutes for a 10,000-module
application. Later warm builds are unaffected.

### Recommended: defer Config v6 to its own migration

Upgrading to V3 and moving from Config v5 to v6 are two separate migrations,
and a mature application should do only the first. Stay on
`@tamagui/config/v5`, which V3 supports as a frozen static pack.

They cost differently. The V3 upgrade is a large but mechanical syntax change
with a codemod, a report, and a visible finish line. The v6 move is a design
change: it buys Tailwind alignment and costs a visible shift in spacing, sizing
and color across the whole application, and no tool can tell you whether the
result is right.

Stacking them means every visual difference has two possible causes and none of
them can be bisected. Staying on v5 preserves the scales while you convert syntax. Component API changes
can still affect layout, so compare actual controls and interactions against the
baseline rather than accepting visual changes automatically.

Adopt v6 afterwards, piece by piece, when there is budget for the visual review.

### The space, size and radius scales change value

Read this before running the codemod with `--write` against a v6 config. The
codemod converts spelling and never edits `createTamagui()`, so a token keeps
its name, changes its value, and the report calls the site clean.

The v5 scale is a hand-tuned curve; the v6 scale is Tailwind's 4px grid. 15 of
16 integer space tokens differ, and they diverge further the larger the token:
`$4` is 18px in v5 and 16px in v6, `$10` moves 60px to 40px, and `$20` moves
186px to 80px.

Do not migrate these by name. Mapping by resolved value lands far closer:

| v5 token | value | by name | by nearest value |
| --- | --- | --- | --- |
| `$1.5` | 4 | `1-5` = 6 | `1` = 4, exact |
| `$3.5` | 16 | `3-5` = 14 | `4` = 16, exact |
| `$5` | 24 | `5` = 20 | `6` = 24, exact |
| `$6` | 32 | `6` = 24 | `8` = 32, exact |
| `$16` | 144 | `16` = 64 | `36` = 144, exact |

Note also that the v6 spelling uses a hyphen: `$2.5` becomes `2-5`. Quarter
steps such as `$0.75` have no v6 equivalent at any spelling, so those sites need
a real value rather than a rename, and a raw number is often the honest answer.

### Theme migration

You can defer this section while using the frozen v5 compatibility packs. Apply
it when moving the application's values and themes to Config v6.

V3's default adaptive ramp has 11 keys, and every key is hyphenated. The numbers
still mean steps relative to the active theme's own scheme, not Tailwind's
absolute `50` through `950` shades; the hyphen is the only spelling change.
Because the ramp is one step shorter, the middle of a V2 12-step ramp compresses:

| V2 | V3 | V2 | V3 |
| --- | --- | --- | --- |
| `color1` | `color-1` | `color7` | `color-6` |
| `color2` | `color-2` | `color8` | `color-7` |
| `color3` | `color-3` | `color9` | `color-8` |
| `color4` | `color-4` | `color10` | `color-9` |
| `color5` | `color-5` | `color11` | `color-10` |
| `color6` | `color-6` | `color12` | `color-11` |

The endpoints map exactly. `color6` and `color7` both land on `color-6`, so
inspect contrast where those two used to be distinct.

Palette-specific steps such as `blue9` are a separate migration. The default v6
config does not define `blue-9` or any other palette step; it defines absolute
Tailwind tokens such as `blue-500`. Either replace the old name with an absolute
token, enter `theme="blue"` and use an adaptive `color-N` value from that theme,
or opt into 12-step scales with `createV6Config({ scales })`, which adds
`blue-1` through `blue-12` to the base themes.

A missing color value is dropped without an error or warning, and the web and
native renderers can expose different fallback colors underneath it. The
flat-values codemod cannot choose the intended replacement, because custom
configs may still define those names and the closest Tailwind shade depends on
the design. It preserves `$blue10` as `blue10` and emits a non-blocking
`legacy-palette-token` configuration warning for every old palette name it
finds. Write mode still applies the safe syntax conversion, so resolve every
warning before running the converted application. This search also finds old
ramp and palette names in source the flat-values codemod does not need to edit:

```bash
rg '\b(color|shadow|gray|mauve|slate|sage|olive|sand|tomato|red|ruby|crimson|pink|plum|purple|violet|iris|indigo|blue|cyan|teal|jade|green|grass|bronze|gold|brown|orange|amber|yellow|lime|mint|sky)[0-9]{1,2}\b' src
```

```tsx
// before: adaptive ramp
<Text color="color12" />

// after: the compressed, hyphenated step
<Text color="color-11" />

// palette-specific names are a separate migration
// before
<Text color="blue10" />

// after: choose the absolute shade that preserves the intended contrast
<Text color="blue-500" />
```

Shadows are per-theme values again, as in v5: `shadow1` through `shadow6`
become `shadow-1` through `shadow-6`, and the default themes carry a seventh
step. Dark themes use stronger shadows than light themes, `shadow-color` is the
active theme's `shadow-3`, and `boxShadow="0 8px 24px shadow-4"` reads
`shadow-4` from the active theme rather than a fixed token.

Replace old surface themes with relative levels:

| V2 | V3 |
| --- | --- |
| `surface1` | `level2` |
| `surface2` | `level3` |
| `surface3` | `level4` |
| `surface4` | `level4` (clamped) |

Levels compose relative to the current theme. A nested `level2` below an
existing `level2` resolves to absolute level 3 while preserving a surrounding
color theme.

```tsx
// before
<Theme name="surface1"><Panel /></Theme>

// after
<Theme name="level2"><Panel /></Theme>
```

Replace the old builder input:

```tsx
// before
import { createThemes, defaultComponentThemes } from '@tamagui/theme-builder'

export const themes = createThemes({
  componentThemes: defaultComponentThemes,
  base,
  accent,
  childrenThemes,
})
```

Custom theme generation now uses the tree API:

```tsx
import {
  createThemes,
  getTheme,
  levels,
  tokens,
} from '@tamagui/themes/builder'

const tree = {
  light: { scheme: 'light', palette: 'gray' },
  dark: { scheme: 'dark', palette: 'gray' },
  children: {
    ...levels(),
    inverse: ({ parent }) => ({
      scheme: parent.scheme === 'light' ? 'dark' : 'light',
      children: levels(),
    }),
  },
} as const

export const themes = createThemes(tokens, tree, { getTheme })
```

Remove the v2 builder exports and options `defaultComponentThemes`,
`componentThemes`, `templates`, `masks`, `childrenThemes`, and
`grandChildrenThemes`. Put hierarchy directly in the tree, semantic shade
choices in scale objects, and exact one-theme overrides in `values`. Components
no longer resolve uppercase name segments such as
`light_Button` automatically. A component that needs a raised surface should create a
normal `level2` boundary in its own skin.

Search configuration and application code together:

```bash
rg "@tamagui/theme-builder|defaultComponentThemes|themes/v5-builder|config/v[34]|createV5Theme|componentThemes|grandChildrenThemes|surface[1-4]|color-12"
```

See [Creating Themes](/docs/guides/theme-builder) for the recipe API and
[Surfaces and levels](/docs/core/surfaces) for nesting semantics.

In monorepos, keep resolutions/overrides aligned:

```json
{
  "resolutions": {
    "@tamagui/core": "^3.0.0",
    "@tamagui/web": "^3.0.0",
    "tamagui": "^3.0.0"
  }
}
```

## 2. Migrate Sheet anatomy

`Sheet.Frame` has been replaced by `Sheet.Container` and `Sheet.Background`.
The flat-values codemod above rewrites every `Sheet.Frame` it can prove is
Tamagui's: the element becomes `Sheet.Container`, and a `Sheet.Background`
carrying the surface props (`bg`, `border*`, `shadow*`,
`disableHideBottomOverflow`) is inserted as its first child. A spread on the
Frame and a `styled(Sheet.Frame, …)` target are rewritten too but reported
for review, because the codemod cannot see which of those props are surface
props. Review every changed Sheet against the rules below.

```tsx
// before
<Sheet>
  <Sheet.Overlay />
  <Sheet.Frame padding="4" bg="background" borderTopRadius="6">
    <Sheet.ScrollView>{children}</Sheet.ScrollView>
  </Sheet.Frame>
</Sheet>
```

```tsx
// after
<Sheet>
  <Sheet.Overlay />
  <Sheet.Container padding="4">
    <Sheet.Background bg="background" borderTopRadius="6" />
    <Sheet.ScrollView>{children}</Sheet.ScrollView>
  </Sheet.Container>
</Sheet>
```

Rules to verify:

- `Sheet.Overlay` must be a direct child of `Sheet`.
- `Sheet.Container` owns layout props like `padding`, `gap`, `height`,
  `maxHeight`, and flex props.
- `Sheet.Background` owns visual surface props like `bg`, `borderRadius`,
  `shadow*`, and decorative absolute layers.
- `Sheet.Container` no longer clips with `overflow="hidden"`. Add clipping
  explicitly if your content relied on the old frame clipping.
- `Sheet.Background` owns `disableHideBottomOverflow`.

## 3. Replace removed props and aliases

Search for APIs that need migration or review. This scan deliberately excludes
the supported Config v5 entries and their retained palette names. `color-12`,
`surface1`–`surface4`, and builders imported from `@tamagui/config-v5` do not
require a v6 theme migration to complete this checkpoint.

```bash
rg "createStyledHOC|focusable|fullscreen|themeInverse|<Theme inverse|Sheet\.Frame|styleable\(|inlineWhenUnflattened|\\\$true|getTokenRelative|stepTokenUpOrDown|forceRemoveScrollEnabled|sizeAdjust|selectable=|Select\.Item.*index|enterVariant|exitVariant|enterExitVariant|delayMs|disableTransparencyHide|disableRootThemeClass|themeClassNameOnRoot|isWindowDefined|getExpandedShorthands|usePropsAndStyle|useProps|useStyle|backgroundActive|@tamagui/config/v[34]|@tamagui/animations-moti|@tamagui/babel-plugin|animateOnly"
```

Use these replacements:

| Removed | Replacement |
| --- | --- |
| `focusable` | `tabIndex` |
| `fullscreen` | explicit `position` and `inset` props |
| `themeInverse` | `theme="inverse"` |
| `<Theme inverse>` | `<Theme name="inverse">` |
| `Sheet.Frame` | `Sheet.Container` plus `Sheet.Background` |
| `Component.styleable(fn)` | `createStyledHOC(Component, fn)` |
| `createStyledHOC(Component)<Props>(fn)` | `createStyledHOC(Component, (props: Props, ref) => ...)` |
| forwardRef wrapper statics | direct refs and normal component composition |
| `inlineWhenUnflattened` | remove it |
| deprecated UI kit aliases | import the current component names |
| old platform condition keys | use flat `web:`, `native:`, `ios:`, `android:`, etc. clauses |
| `forceRemoveScrollEnabled` | `disableRemoveScroll` with inverted intent |
| `selectable` on Text | `userSelect` (core maps it to RN's `selectable` on native) |
| `AnimatePresence` `enterVariant` / `exitVariant` / `enterExitVariant` | `custom={{ ... }}` plus a variant on the child that emits `enter:` / `exit:` clauses |
| `Avatar.Fallback` `delayMs` | `delay` |
| `Sheet` `disableTransparencyHide` | `disableHideWhenClosed` |
| `Select.Item` `index` | remove it, registry order is authoritative |
| `TamaguiProvider` / `ThemeProvider` `disableRootThemeClass` and `themeClassNameOnRoot` | `createTamagui({ settings: { addThemeClassName } })` |
| `@tamagui/input` v1 `Input` / `TextArea` | the current `Input` and `TextArea` from `@tamagui/input` |
| `Button` from `@tamagui/button` | `Button` from `tamagui`; `@tamagui/button` ships `ButtonFrame`, `ButtonText`, `ButtonIcon` and `useButton` only |
| `isWindowDefined` | `isBrowser` |
| `createMedia` from `@tamagui/react-native-media-driver` | remove the call, `createTamagui` sets the driver up |
| `getExpandedShorthands` | `getExpandedShorthand(key, props)` when behavior code needs one authored prop and accepts configured shorthands |
| `useProps`, `useStyle(props)`, `usePropsAndStyle` | keep conditional values on styled Tamagui components; use `splitStyleProps` only when a wrapper must partition authored props |
| `createCheckbox` `sizeAdjust` | explicit sizing math or component styles |
| `animateOnly` | `properties` inside the transition, see [Migrate transition values](#13-migrate-transition-values) |
| `transition` array form, `default`, per-property `type` | the [v3 transition grammar](#13-migrate-transition-values) |
| `@tamagui/animations-moti` | `@tamagui/animations-reanimated` |
| `@tamagui/config/reanimated` | `@tamagui/config/animations-reanimated` |
| `accept` option in `styled()` | piece-typed props (e.g. `StylePiece`) or real style keys |
| `'...size'` / `'...fontSize'` spread variant keys | codemod writes `styled.dynamic<TokenType>(...)`; report flags sibling-prop reads for `.resolve` |
| `':string'` / `':number'` / `':boolean'` type-key variants | codemod writes one typed dynamic and combines object returns with `typeof`; report flags other bodies and mixed exact keys |
| `'...'` catch-all variant key | report only; choose the explicit `styled.dynamic<YourValue>(...)` generic yourself |

V2 could spread one style across its base prop, pseudo-style objects such as
`hoverStyle`, media objects such as `$sm`, and platform objects. The removed
hooks had to gather those objects to produce resolved props and styles. In v3,
the base value and every conditional clause for a style live on that style's
single property:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<View opacity={{ default: 1, hover: 0.7, sm: 0.8 }} />
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<View opacity="1 hover:0.7 sm:0.8" />
```

</MDXTabs.Content>
</MDXTabs>

The styled component interprets that value. Pass the property through instead
of flattening the component's styles in JavaScript. If a wrapper must separate
style props from regular props, use `splitStyleProps`:

```tsx
import { splitStyleProps } from '@tamagui/core'

const [styleProps, regularProps] = splitStyleProps(props, {
  expandShorthands: true,
})
```

Pass a filter map to select only some canonical style keys. Rejected style
props remain in the second object, which supports cases such as splitting text
props from frame props without another loop. The filter may also be a callback
that receives `(key, value, originalKey, isStyleProp)`.

If behavior code needs one authored property and supports a configured
shorthand, read it with the singular helper:

```tsx
import { getExpandedShorthand } from '@tamagui/core'

const zIndex = getExpandedShorthand('zIndex', props)
```

`getExpandedShorthand` only chooses the longhand or shorthand property. It does
not resolve tokens or choose an active conditional clause. Neither does
`splitStyleProps`. Use `useMedia()` or `useTheme()` when behavior itself needs
active responsive or theme state.

The curried `createStyledHOC` form is a separate signature break from the
`.styleable()` rename. Move the custom prop type onto the render parameter when
you combine the two calls:

```tsx
// before
const Card = createStyledHOC(CardFrame)<CardProps>((props, ref) => ...)

// after
const Card = createStyledHOC(CardFrame, (props: CardProps, ref) => ...)
```

Spread, resolver-name, and type-key variants have no runtime matching in v3. A
leftover `'...size'`, `Size`, or `number` key only matches that exact literal.
The flat-values codemod rewrites known spread and type keys to one branded
dynamic. Its report leaves catch-all keys, mixed exact branches, and sibling-prop
reads for manual migration:

```tsx
// before
variants: {
  size: {
    '...size': (val, { tokens }) => ({ padding: tokens.size[val] }),
  },
} as const

// after
variants: {
  size: styled.dynamic<SizeTokens>((val, { tokens }) => ({
    padding: tokens.size[val],
  })),
} as const
```

### accept is removed

The `accept` configuration option in `styled()` has been removed in v3. It previously handled two patterns:

1. **Piece-typed style props:** Props that accept style objects (such as `activeStyle` on `Checkbox`, `ToggleGroup`, and `Tabs`, or `contentContainerStyle` on `ScrollView`) now accept a `StylePiece` created with `style()`.
2. **Input color style keys:** `placeholderTextColor`, `selectionColor`, `cursorColor`, and `selectionHandleColor` on `Input` and `TextArea` are now real style properties. On web, they emit CSS rules (`::placeholder`, `caret-color`, `::selection`). On native, they map through the React Native compatibility layer.

```tsx
// before
const MyScrollView = styled(
  ScrollView,
  {},
  {
    accept: {
      contentContainerStyle: 'style',
    } as const,
  }
)

// after
import { ScrollView, style } from 'tamagui'

const contentStyle = style({ padding: 16 })
<ScrollView contentContainerStyle={contentStyle} />
```

Examples:

```tsx
// before
<View focusable fullscreen />
```

```tsx
// after
<View tabIndex={0} position="absolute" inset={0} />
```

```tsx
// before
<Text selectable>Copy me</Text>
<Select.Item index={0} value="first" />

// after
<Text userSelect="text">Copy me</Text>
<Select.Item value="first" />
```

```tsx
// before
<Button themeInverse />
<Theme inverse>
  <Card />
</Theme>
```

```tsx
// after
<Button theme="inverse" />
<Theme name="inverse">
  <Card />
</Theme>
```

### Web-standard style keys

Files you convert to `html.*` should use web-standard style keys. `View` and
`Text` keep accepting the React Native keys with no warnings, so only rename
where you adopt the web contract. Find legacy keys with:

```bash
rg "marginHorizontal|marginVertical|paddingHorizontal|paddingVertical|marginStart|marginEnd|paddingStart|paddingEnd|textAlignVertical|writingDirection|includeFontPadding|elevation|shadowColor|shadowOffset|shadowOpacity|shadowRadius"
```

Use these replacements:

| Legacy key | Replacement |
| --- | --- |
| `marginHorizontal` | `marginInline` (`mx` stays physical left/right, not RTL-aware inline start/end) |
| `marginVertical` | `marginBlock` (`my` also works) |
| `paddingHorizontal` | `paddingInline` (`px` also works) |
| `paddingVertical` | `paddingBlock` (`py` also works) |
| `marginStart` | `marginInlineStart` |
| `marginEnd` | `marginInlineEnd` |
| `paddingStart` | `paddingInlineStart` |
| `paddingEnd` | `paddingInlineEnd` |
| `elevation` | `boxShadow` |
| `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius` | one `boxShadow` string |
| `textAlignVertical` | `verticalAlign` |
| `writingDirection` | `direction` |
| `includeFontPadding` | remove it, standard CSS font metrics govern text bounds |

```tsx
// before
<View marginHorizontal={12} marginVertical={8} writingDirection="rtl" />

// after
<html.div marginInline={12} marginBlock={8} direction="rtl" />
```

On native, `direction` keeps the Yoga `direction` and also maps to
`writingDirection`, while `verticalAlign` maps to `textAlignVertical`, so
web-authored styles apply on both platforms.
Multi-value strings such as `margin="10px 20px"` and `gap="10px 20px"` expand
per CSS slot order on native.

### Image source compatibility

Image prefers web-standard `src` for URLs and native `require()` results.
React Native's `source` remains supported during migration, but is deprecated:

```tsx
// before
<Image
  source={{ uri: 'https://example.com/photo.jpg', width: 200, height: 200 }}
  resizeMode="cover"
/>

// after
<Image
  src="https://example.com/photo.jpg"
  width={200}
  height={200}
  objectFit="cover"
/>
```

The `width` and `height` props control layout. Percentage dimensions also work
when the parent has defined dimensions.

## 4. Remove true token references

The default v3 configs no longer export the legacy `$true` token key. The
flat-values codemod writes `$true` on a style prop as `4`, the bare key the
default config aliased it to, and reports the site with a `legacy-true-token`
warning so you can confirm your config agrees. On the size-typed variant props
`size` and `iconSize` it writes the boolean instead, which
resolves to the component's default size.

```tsx
// before
<XStack gap="$true" p="$true" />
<Button size="$true" />
```

```tsx
// after
<XStack gap="4" p="4" />
<Button size />
```

The codemod does not edit token definitions or custom variants, so search
config files and any remaining code for the alias:

```bash
rg "\\\$true|true:" tamagui.config.* src code
```

Only replace token keys. Boolean variant values like `circular` or `unstyled={false}`
are unrelated.

## 5. Control sizes are named

Every control that takes `size` (Button, Input, Select, Tabs, ListItem, Label,
Card, Toggle, Checkbox, RadioGroup, Switch, Slider, Progress, Avatar, Group)
accepts the same five names: `xs`, `sm`, `md`, `lg`, `xl`. A name is a
rung in the shared `sizing` ladder, never a height: it picks a font size,
horizontal and vertical padding, and a radius, and the control ends up its
line-height plus padding tall. That keeps the frame, its text, and its icon aligned by construction.
The default is `md`.

Under `@tamagui/config/v6` the ladder mirrors shadcn:

| name | font size / line-height | paddingX | paddingY | radius | icon | height |
| ---- | ----------------------- | -------- | -------- | ------ | ---- | ------ |
| `xs` | 12 / 16                 | 8        | 4        | 4      | 12   | 24     |
| `sm` | 14 / 20                 | 12       | 6        | 6      | 16   | 32     |
| `md` | 14 / 20                 | 16       | 8        | 6      | 16   | 36     |
| `lg` | 16 / 24                 | 24       | 8        | 6      | 16   | 40     |
| `xl` | 18 / 28                 | 32       | 10       | 8      | 20   | 48     |

Height excludes the 1px border. `@tamagui/config/v5` ships its own sizing on
the v5 keys with the same geometry pinned, so the same names work under either
config. Button, ListItem, Checkbox, RadioGroup, and Switch derive every value
from the ladder; add rungs by spreading `defaultSizing` (see
[Sizing](/docs/core/sizing)).

```tsx
import { Button } from 'tamagui'

<Button size="sm" />
<Button size="lg" icon={Check} />
```

Token keys and numbers no longer size controls: `size` on a control only takes
a name (or `true` for the default), so `size="4"` on a control is a type error.
Numbers stay geometry on shapes (`Square`, `Circle`, `Avatar` take size tokens)
and font keys on text and icons.

Text components speak Tailwind's own scale (`xs`, `sm`, `base`, `lg`, `xl`,
`2xl` and up). `<Button size="md">` text and `<Paragraph size="sm">` text are
the same 14/20. Text keeps `base` rather than `md` because `text-base` is what
Tailwind users know.

If you also adopt the unstyled primitives from `@tamagui/ui`, those own no size
scale at all, so you provide sizing yourself or through your copied styles.

### An explicit `undefined` prop no longer clears a default

`<Button size={props.size}>` with `props.size` undefined now renders the `md`
default. In v2 an explicitly passed `undefined` replaced the `defaultVariants`
value and the styled-context value for that key, and the control rendered with
no size styles at all. Core now treats an explicit `undefined` the way React
`defaultProps` do: as absent (and the size resolvers default it too). This
applies to every styled component and every `createStyledContext` provider, not
only `size`. To deliberately turn a default variant off, pass `null`:

```tsx
<Button size={maybeSize} />   // undefined falls back to md
<Button size={null} />        // no size rung applied
```

### Smaller size-related removals

- `Checkbox`, `RadioGroup` and `Switch` now step through five real sizes
  (17, 20, 22, 25 and 28px tall). In the first betas `sm`, `md` and `lg` all
  rendered at 22px.
- `Tooltip` no longer accepts `size`. It only ever set the arrow px for
  `TooltipSimple`, which keeps `size` for that purpose.
- `@tamagui/ui` no longer exports a `ListItemIcon` component. The behavior
  package publishes `color` through `ListItemContext`; the icon px is the
  skin's decision (the `tamagui` ListItem still ships `ListItem.Icon`). The
  `ListItemIconProps` type stays exported.
- The unstyled `Slider` and `Slider.Thumb` take `size` as a px number or a font
  size key. Skin size names (`sm`, `md`) belong to the styled `tamagui` Slider,
  which resolves them itself.
- `useToggleGroupItem().color` is `undefined` when no color was set, where it
  used to be an empty string.

## 6. Replace token stepping

`@tamagui/get-token` no longer supports runtime scale stepping. Removed APIs:

- `stepTokenUpOrDown`
- `getTokenRelative`
- the second options argument to `getSize`, `getSpace`, and `getRadius`
- options such as `shift`, `bounds`, and `excludeHalfSteps`

```tsx
// before
const padding = getSpace(size, { shift: -2 })
const radius = getRadius(radiusToken, { shift: 1 })
```

```tsx
// after
import { getVariableValue } from 'tamagui'
import { getSpace, getRadius } from '@tamagui/get-token'

const padding = getVariableValue(getSpace(size)) * 0.6
const radius = getVariableValue(getRadius(radiusToken)) * 1.2
```

If you need to move from `5` to `4`, use explicit token keys or a helper that
only handles numeric token names. Do not rebuild runtime scale sorting in app
code.

## 7. Migrate line height and audit exact font sizes

V3 changes numeric `lineHeight` authored on Tamagui components from an absolute
value to a ratio on both web and native. The migration command above selects the
old source semantics explicitly, so every proven V2 number becomes a px string.
The value does not use a magnitude heuristic: V2 `lineHeight={1.5}` becomes
`lineHeight="1.5px"`, while a new V3 ratio stays `lineHeight={1.5}`.

The codemod follows Tamagui bindings through JSX, `styled()` styles and variants,
resolvers, and inline style objects. It leaves raw React Native and Restyle styles
alone. A shared style object, untyped dynamic expression, or extracted token
`.val` is reported for a manual decision at the Tamagui boundary. Rerunning with
`--source-semantics v2-pixels` is safe because explicit px output is idempotent.

Review existing numeric strings separately. The codemod leaves strings unchanged;
`lineHeight="24"` is a ratio unless `24` names a configured font token. Use
`lineHeight="24px"` if that string previously represented a native pixel length.

Font sizes keep their existing contract:

- `fontSize={17}` is a numeric platform value and keeps the platform-default
  line-height path.
- `fontSize="17px"` is an exact pixel value. Web passes it through as CSS;
  native parses it to a number.

Font configuration is a separate boundary. Numeric `lineHeight` entries remain
absolute pixels, including the existing v5 and v6 scales. Use a numeric string
such as `"1.5"` for a relative font token, or `"24px"` to make an absolute
length explicit.

On native, a text node with its own font size and no local line height keeps a
runtime inheritance boundary, even when its children are literal text. An
ancestor in another module can supply a ratio that must be recomputed at this
node's font size. Token-sized Paragraph and SizableText with their own default
line height can still be flattened by the compiler.

```tsx
// platform-default line height behavior
<Paragraph fontSize={17} />

// exact px behavior
<Paragraph fontSize="17px" />

// V3 relative line height on both platforms
<Paragraph fontSize={20} lineHeight={1.5} />

// explicit absolute line height
<Paragraph lineHeight="24px" />
```

## 8. Update FocusScope usage

FocusScope now renders a `display: contents` wrapper. Function-as-children is
removed; pass JSX children directly.

```tsx
// before
<FocusScope loop>
  {({ ref, onKeyDown, tabIndex }) => (
    <View ref={ref} onKeyDown={onKeyDown} tabIndex={tabIndex} />
  )}
</FocusScope>
```

```tsx
// after
<FocusScope loop>
  <View />
</FocusScope>
```

Use `noFocus` when a surface should temporarily reject all focus:

```tsx
<FocusScope noFocus>
  <Input placeholder="Cannot receive focus" />
</FocusScope>
```

`noFocus` takes precedence over `trapped` and auto-focus behavior. It is web-only;
FocusScope remains a no-op on native.

## 9. Update Dialog, Popover, and Select Adapt usage

Dialog, Popover, and Select now share the same Adapt handoff model. Open state
lives above `AdaptParent`, and adapted sheet content remains mounted until the
sheet finishes hiding.

Use the current Adapt anatomy:

```tsx
<Popover>
  <Popover.Trigger />
  <Popover.Content>
    <Popover.Arrow />
    <Adapt.Contents />
  </Popover.Content>

  <Adapt when="max-md" platform="touch">
    <Sheet modal dismissOnSnapToBottom>
      <Sheet.Container padding="4">
        <Sheet.Background />
        <Adapt.Contents />
      </Sheet.Container>
      <Sheet.Overlay />
    </Sheet>
  </Adapt>
</Popover>
```

Component-specific notes:

- `Dialog.Content` no longer accepts the no-op `size` variant.
- Non-modal `Dialog.Content` no longer enables RemoveScroll while open.
- Dialog, Popover, and Select parts own their presence lifecycles.
- Animation drivers can now complete part-level exits through the typed
  [`onTransition`](#14-update-animation-and-sheet-lifecycle-callbacks) lifecycle.
- `Popover.Content forceMount` now matches Dialog semantics and disables part
  presence gating.
- Removed legacy Popover and Select sheet-controller internals. If app code
  imported internal helpers like `useShowPopoverSheet` or `useSelectBreakpointActive`,
  remove those imports and use Adapt state instead.

## 10. Update Select APIs

Select has a few public API changes and parity additions.

Keep your form props. `Select` still accepts `name` on web, and custom Select
renders hidden `<input>` elements for it, so the selected value(s) submit with a
surrounding form. `form` associates the control with an external form by id. Both
are inert on native.

<Notice theme="red">
  Do not remove `name` during migration. Removing it drops the hidden form inputs
  and breaks form submission. Earlier drafts of this guide told you to delete
  `name`; that was wrong.
</Notice>

```tsx
<form
  onSubmit={(e) => {
    e.preventDefault()
    const data = new FormData(e.currentTarget)
    console.log(data.get('fruit')) // the selected value
  }}
>
  <Select name="fruit" defaultValue="apple">
    {/* ...Select.Trigger, Select.Content, items... */}
  </Select>
  <button type="submit">Save</button>
</form>
```

Removed from `Select` root:

- `autoComplete` was removed. It never drove autofill in the custom Select, so
  delete it.

Added or expanded:

- `Select.Separator`
- `Select.Content onEscapeKeyDown`
- `Select.Content onInteractOutside`
- `data-state="open" | "closed"` on `Select.Trigger`
- `data-state="open" | "closed"` on the web `Select.Viewport`

```tsx
<Select.Content
  onEscapeKeyDown={(event) => {
    console.log('escape', event)
  }}
  onInteractOutside={(event) => {
    console.log('outside', event)
  }}
>
  <Select.Viewport>
    <Select.Group>
      <Select.Label>Fruit</Select.Label>
      <Select.Item value="apple">
        <Select.ItemText>Apple</Select.ItemText>
      </Select.Item>
      <Select.Separator />
      <Select.Item value="orange">
        <Select.ItemText>Orange</Select.ItemText>
      </Select.Item>
    </Select.Group>
  </Select.Viewport>
</Select.Content>
```

## 11. Update themed icon usage

Themed icons now size token values through the current font size scale, not the
space/size token scale. Raw numeric sizes are unchanged.

```tsx
// v3: aligns with font.size.4
<Search size="4" />

// unchanged: exact numeric size
<Search size={18} />
```

Themed icons no longer accept Tamagui media or pseudo props directly because
they no longer run full style resolution.

```tsx
// before
<Search size="$4" $sm={{ opacity: 0.6 }} hoverStyle={{ scale: 1.05 }} />
```

```tsx
// after
const IconFrame = styled(View, {
  opacity: 'sm:0.6',
  scale: 'hover:1.05',
})

<IconFrame>
  <Search size="4" />
</IconFrame>
```

Theme color, `fill`, `stroke`, `size`, `strokeWidth`, `style`, and `testID` still
work.

## 12. Check ScrollView web usage

`@tamagui/scroll-view` now has its own web implementation. It no longer routes
through `react-native-web`.

Covered web surface:

- `scrollTo`
- `scrollToEnd`
- `getScrollableNode`
- RN-shaped `onScroll`
- `contentContainerStyle`
- `horizontal`
- scroll indicator props

Unsupported old lite/RNW props should be replaced:

- momentum scroll events
- `snapTo*` props
- `keyboardDismissMode`
- any app-specific reliance on RNW's legacy style system

## 13. Migrate transition values

V3 has one transition grammar: a CSS transition string, or an object whose keys
are the same values under names. The v2 array form, the `default` key, the
per-property `type` key, inline spring physics, and the `animateOnly` prop are
all gone. The flat-values codemod rewrites every static site, so run it first
and hand-migrate what it flags.

| V2 | V3 |
| --- | --- |
| `transition={['quick', { opacity: 'lazy' }]}` | `transition={{ preset: 'quick', opacity: 'lazy' }}` |
| `transition={{ default: 'quick' }}` | `transition="quick"` |
| `transition={{ x: { type: 'bouncy' } }}` | `transition={{ x: 'bouncy' }}` |
| `transition={{ x: { type: 'bouncy', overshootClamping: true } }}` | `transition={{ x: { preset: 'bouncy', spring: { overshootClamping: true } } }}` |
| `transition={{ damping: 20, stiffness: 250 }}` | `transition={{ spring: { damping: 20, stiffness: 250 } }}` |
| `transition={{ bounciness: 8, speed: 12 }}` | `transition={{ spring: { stiffness: 342.101, damping: 24.684 } }}` |
| `animateOnly={['transform', 'opacity']}` | `properties: 'transform, opacity'` inside the transition |
| `animateOnly={[]}` | `transition="none"` |

The array form and `default` were two more ways to say "the base timing", which
is what a bare string and the `preset` key already say. Per-property `type`
meant a preset name in one place and a spring-or-timing mechanism in another;
in v3 a preset name is always a preset name, and physics always live under
`spring`.

`bounciness`, `speed`, `tension`, and `friction` are removed. The codemod
converts them with React Native's own Origami formulas, so a migrated spring
keeps the motion it had.

### animateOnly is now part of the transition

`animateOnly` was an exclusive filter over the properties a transition named,
which is what a CSS `transition-property` list already is. Name the properties
in the transition itself:

```tsx
// before
<Square transition="quick" animateOnly={['transform', 'opacity']} />
```

```tsx
// after
<Square transition={{ preset: 'quick', properties: 'transform, opacity' }} />
// or, in string form
<Square transition="transform 200ms, opacity 200ms" />
```

A property the transition does not name is set rather than animated, on every
driver. `transition="none"` animates nothing and completes exits immediately,
which is what an empty `animateOnly` array did.

A standalone `transitionProperty` longhand narrows plain-CSS transitions in the
browser, but it does not reach the animation drivers. Use `properties` inside
the transition, or the property token in a transition string, so the list means
the same thing on all four drivers.

### Preset names and values changed

Presets are springs now, defined once and identical on every driver. In v2 the
same name was a different motion per driver: `bouncy` was a 350ms cubic-bezier
on the web, a stiffness-120 spring on React Native, and a stiffness-90 spring on
Motion. Expect timing to shift slightly and check screens where motion matters.

The `'100ms'`-style preset names are removed. A duration is CSS in v3, so
`transition="100ms"` and `transition="100ms ease-out"` work with nothing
configured.

## 14. Update animation and sheet lifecycle callbacks

The untyped, enter-only `onDidAnimate` prop is gone. Every animated component now
takes a typed [`onTransition`](/docs/core/animations#the-ontransition-lifecycle)
that fires at the start and end of enter, exit, and in-place update transitions.

```tsx
// before
<View animation="quick" onDidAnimate={() => {}} />
```

```tsx
// after
<View
  transition="quick"
  onTransition={(e) => {
    // e: { phase: 'start' | 'end', cause: 'enter' | 'exit' | 'update', finished?: boolean }
    if (e.phase === 'end' && e.cause === 'exit') {
      // exit finished
    }
  }}
/>
```

Sheet's bespoke `onAnimationComplete` prop is replaced by a sheet-shaped
`onTransition`:

```tsx
// before
<Sheet onAnimationComplete={() => {}} />
```

```tsx
// after
<Sheet
  onTransition={(e) => {
    // e: { phase, cause: 'open' | 'close' | 'snap', position, finished? }
  }}
/>
```

`onPositionChange` is unchanged.

The sheet no longer fades itself. A fully-closed sheet is hidden with
`display: 'none'` instead of by animating opacity to transparent, and there is no
overlay fade baked in. If you relied on the built-in fade, drive it yourself with
one of the two [overlay fade patterns](/ui/sheet#overlay-fades).
`unmountChildrenWhenHidden` semantics are unchanged.

The stable-2.4.x `disableTransparencyHide` prop is renamed to
`disableHideWhenClosed` (matching `unmountChildrenWhenHidden`). The old name is
removed, not aliased.

`Sheet.Handle` ships no opacity of its own in v3. If you used the default handle
dim or its fade-in on open, set `opacity` (and an `open`-driven opacity) on your
own `Sheet.Handle`.

## 15. Update active-state background colors

Checkbox and Switch checked states, Tabs active tab, and Toggle Group active
toggle used to default to `backgroundActive`. V3 components now read
`background-press`. The frozen v5 themes still retain `backgroundActive`, so
audit the component behavior even when keeping Config v5; the presence of the
old token alone does not mean the config must be migrated to v6.

Each of these components applies its default active background only when you do
not pass `activeStyle`, and a supplied `activeStyle` wins because it is applied
last. Override the active color per-instance with `activeStyle`:

```tsx
<Checkbox activeStyle={{ backgroundColor: 'blue-500' }} />
<Tabs.Tab activeStyle={{ backgroundColor: 'blue-500' }} />
```

If a custom theme defined `backgroundActive` to color these states, move that
color to `background-press` or pass it through `activeStyle`.

```tsx
// before
const themes = { light: { backgroundActive: '#ddd' } }

// after
const themes = { light: { 'background-press': '#ddd' } }
```

## 16. Optional: adopt the Tailwind frontend

Tailwind authoring is optional for v3. Select it by importing components from
`@tamagui/tailwind`; there is no global config mode.

```tsx
import { Text, View, styled } from '@tamagui/tailwind'
```

Regular Tamagui components and Tailwind components can share a tree. Each
component has one styling language: Tailwind components accept `className`,
while components imported from `tamagui` or `@tamagui/core` accept Tamagui
style props.

```tsx
import { View as TamaguiView } from 'tamagui'
import { View as TailwindView } from '@tamagui/tailwind'

<TamaguiView backgroundColor="blue-100">
  <TailwindView className="rounded-lg p-4" />
</TamaguiView>
```

Read [Tailwind for Tamagui](/blog/tailwind-mode) for current utility
coverage and known gaps.

## 17. Migrate createTamagui defaultProps

`createTamagui({ defaultProps })` is removed in v3.
Each of its uses has a more direct replacement:

- **Styling defaults** move to [theme updates](/docs/core/theme#theme-updates): declare
  the value once in `variables`, read it in your component styles, and
  redefine it per subtree on `<ThemeUpdate>` instead of forcing props onto every
  instance of a component.
- **A component's default look** belongs in the component itself — v3
  components are behavior primitives plus styles you own, so edit your copied
  component instead of patching it from config.
- **Prop propagation to children** uses
  [createStyledContext](/docs/core/create-styled-context), which makes the
  shared keys typed props on every styled component that consumes the context.

```tsx
// before
createTamagui({
  defaultProps: { Square: { backgroundColor: 'violet6' } },
})

// after
createTamagui({
  variables: { squareBackground: 'violet-500' },
})
// in your Square styles
styled(View, { backgroundColor: 'squareBackground' })
```

## 18. Migrate off the imperative Toast

v3 removes the old imperative Toast. `@tamagui/toast` (and the `Toast` export from
`tamagui`) is now the composable + `toast()` API, and it's the only Toast — there
is no longer a separate "v2" toast entry point. These removed exports have no
replacement under the same name:

| Removed (v2)                | Replacement (v3)                                             |
| --------------------------- | ----------------------------------------------------------- |
| `ToastProvider` + `ToastViewport` | `<Toast>` + `<Toast.Viewport><Toast.List /></Toast.Viewport>` |
| `useToastController().show(title, opts)` | `toast(title, { description: opts.message, ...opts })` |
| `useToastController().hide()` | `toast.dismiss()`                                           |
| `useToastState()`           | rendering is handled by `<Toast.List>`; use `useToasts()` for the list |

The `toast()` function is global (no provider needed around callers). Mount the
toast parts once at the app root and trigger toasts from anywhere:

```tsx
// before (v1)
import { ToastProvider, ToastViewport, useToastController } from '@tamagui/toast'

function Root({ children }) {
  return (
    <ToastProvider>
      {children}
      <ToastViewport />
    </ToastProvider>
  )
}
function Save() {
  const toast = useToastController()
  return <Button onPress={() => toast.show('Saved!', { message: 'All good.' })}>Save</Button>
}

// after (v3)
import { Toast, toast } from 'tamagui/toast'

function Root({ children }) {
  return (
    <>
      {children}
      <Toast>
        <Toast.Viewport>
          <Toast.List />
        </Toast.Viewport>
      </Toast>
    </>
  )
}
function Save() {
  return <Button onPress={() => toast('Saved!', { description: 'All good.' })}>Save</Button>
}
```

## 19. Replace ThemeableStack and SizableStack

`ThemeableStack` and `SizableStack` (and their `themeableVariants` /
`themeableVariantStyles`) are removed from `@tamagui/stacks`. Their one good idea —
composable chrome variants — moves into the copied layer as the `Surface` fixture
and its `facets`.

- Extending `ThemeableStack`: use `styled(YStack, { … })` and add the styles you
  actually used inline. The removed variants map to plain styles:

  ```tsx
  // before
  const Panel = styled(ThemeableStack, { bordered: true })
  // after
  const Panel = styled(YStack, { borderWidth: 1, borderColor: 'border-color' })
  ```

- `elevate` → a shadow read from generics.
- `bordered` → `borderWidth` + `borderColor: 'border-color'`.
- `circular` → `borderRadius: 100_000` (+ equal width/height for a circle).

- For panels/wells/toolbars, copy the `Surface` fixture from the registry
  (`npx shadcn add surface`). It is a `YStack` + a `level` variant (theme
  `level2-4`) + the composable facets `filled outlined elevated rounded
  interactive`, with nothing on by default:

  ```tsx
  <Surface level={2} filled rounded interactive />
  ```

  Facets read theme generics (`background`, `border-color`, …), never the color
  scale, so they restyle for free under any `level` or `theme` change.

## 20. Verification checklist

Run validation at the layer your app changed.

Code checks:

```bash
npx tamagui check
tsc --noEmit
```

Build checks:

```bash
npm run build
```

Runtime checks:

- Open every screen that uses `Sheet`, especially fit sheets and sheets with
  scrollable content.
- Test `Dialog`, `Popover`, and `Select` at the breakpoints where they Adapt to
  Sheet.
- Verify close animations complete before content unmounts.
- Verify any `onDidAnimate` / Sheet `onAnimationComplete` callbacks were moved to
  `onTransition` and fire as expected.
- Verify sheet overlays still fade if you depended on the old built-in fade.
- Verify Checkbox, Switch, Tabs, and Toggle Group active/checked states still
  read the way you want after the `backgroundActive` removal.
- Inspect Avatar, Tabs, and Group anywhere the V2 default chrome was part of
  the design. Add app-owned skins where needed.
- Verify non-modal Dialogs do not lock page scroll.
- Verify keyboard focus, Escape, outside click, and return focus behavior.
- Inspect icons next to text at every app size token you use.
- Check any custom config tokens that used `true`, numeric font sizes, or token
  stepping.
- After changing Tamagui config, restart Metro with `expo start -c` before
  evaluating compiled output.
- If you use Tailwind mode, compare web and native output for your supported
  utility classes.

## What a clean typecheck will not catch

A flat value is a string program, so most of this grammar is not something
TypeScript can check. The first large app through this migration reached zero
type errors with several things quietly broken, and none of them would have been
found without running it. Each item below is a real defect from that migration.

**Token detection by sigil.** Code shaped like `value[0] !== '$'` was a correct
way to tell a token from a raw color in v2 and is wrong in v3, where tokens have
no sigil. One icon helper doing this passed every token straight through as a
literal SVG fill and blanked every icon in the app. Resolve through the theme
and treat what it does not know as a literal value:

```tsx
// before: the shape of the string decided
const value = color[0] !== '$' ? color : theme[color]?.get()

// after: the theme decides
const value = theme[color]?.get() ?? color
```

**Conditions the codemod cannot reach.** The codemod converts a style object at
a conversion site: a JSX attribute list, a `styled()` config, or a variant
branch. A `hoverStyle` returned from a helper or spread in conditionally is none
of those, so it survives, and v3 forwards an unrecognized `hoverStyle` prop
rather than applying it. The interaction silently stops happening.

Note that hover and press now ride the property they modify, so a helper that
used to return a separate `hoverStyle` object has to own the resting value too.
A caller that still sets its own `bg` next to the spread will overwrite the
whole program:

```tsx
// v2: two different props, both applied
<XStack bg={resting} {...rowStates(active)} />

// v3: one program, so the helper returns all of it
<XStack {...rowStates(active, resting)} />
```

Flat values are space separated, so any color spliced into a program has to be
space free. `rgba(0,0,0,0.5)` is fine and `rgba(0, 0, 0, 0.5)` splits into
garbage clauses.

**Variants that look like style props.** The codemod converts style props and
the size-typed variant props `size` and `iconSize`, since v3 reads
those values as size-scale keys. On one element it rewrites `color="$color12"`
to `color="color12"` and `size="$2"` to `size="2"`. It drops the sigil without
renaming the ramp, so apply the hyphen table above afterwards. A custom variant
that takes a token value keeps its `$` spelling, and it typechecks while
resolving to nothing, so grep for `="$` after the run.

**Half steps are renamed, not removed.** `$0.5` becomes `0-5` and `$1.5` becomes
`1-5`. Keeping the same v5 scale preserves the resolved values through this
spelling change. Moving from v5 to v6 also changes the scale values; it needs
separate mapping and visual review, even when a token has the same name.

**`undefined` inside an interpolated value.** A conditional whose false branch is
`undefined` becomes the literal string `"undefined"` once it is wrapped in a
template literal, which produces invalid padding, color, and font values. Keep
the conditional as an expression instead:

```tsx
// wrong: renders the string "undefined"
py={`${compact ? undefined : '1'}`}

// right
py={compact ? undefined : '1'}
```

**Provider order.** `SafeAreaProvider` now has to wrap `TamaguiProvider`. The v3
provider mounts a tracker that reads safe-area context to publish the inset
tokens, so the v2 nesting throws `NO_INSETS_ERROR` at startup and the whole app
renders an error screen. The message names `SafeAreaProvider`, which points away
from the upgrade.


## Quick reference

```bash
# things that typecheck and are still wrong
rg "\[0\] [!=]== '\\\$'|startsWith\('\\\$'\)"        # token detection by sigil
rg "hoverStyle|pressStyle|focusStyle|enterStyle|exitStyle"  # conditions the codemod missed
rg '\b(size|fontSize)="\$'                          # variants left with a sigil
rg '`\$\{[^`]*undefined[^`]*\}`'                    # "undefined" interpolated into a value
rg 'animateOnly|transition=\{\['                    # v2 transition spellings

# duplicate package / lockfile scan
npx tamagui check

# Sheet anatomy still requiring migration
rg 'Sheet\.Frame'

# APIs requiring migration or review (Config v5 remains supported)
rg "createStyledHOC|focusable|fullscreen|themeInverse|<Theme inverse|Sheet\.Frame|styleable\(|inlineWhenUnflattened|\\\$true|getTokenRelative|stepTokenUpOrDown|forceRemoveScrollEnabled|sizeAdjust|selectable=|Select\.Item.*index|enterVariant|exitVariant|enterExitVariant|delayMs|disableTransparencyHide|disableRootThemeClass|themeClassNameOnRoot|isWindowDefined|getExpandedShorthands|usePropsAndStyle|useProps|useStyle|backgroundActive|@tamagui/config/v[34]|@tamagui/animations-moti|@tamagui/babel-plugin|animateOnly"
```

## v1 to v3 path

For v1 apps, migrate in two passes:

1. Apply the v1 to v2 changes: React 19, React Native 0.81+, TypeScript 5,
   Config v5, `animation` to `transition`, `tag` to `render`, `Stack` to `View`,
   `space` to `gap`, ARIA/web prop renames, native setup imports, and v2
   component API changes.
2. Apply the v2 to v3 changes in this guide.

The CLI migration prompt can generate an AI-agent checklist for either path:

```bash
npx tamagui migrate --from v2
npx tamagui migrate --from v1
```


## guides/how-to-build-a-button

---
title: How to Build a Button
description: Learn how to create a powerful yet simple API for a button with Tamagui and
  compound components
hero: HowToBuildAButton
demoName: BuildAButton
---

<HeroContainer noScroll>
  <BuildAButtonDemo />
</HeroContainer>

<IntroParagraph>
  Deceptively innocuous, designing a robust yet flexible API even for a Button can be
  filled with surprising challenges.
</IntroParagraph>

More than just text in a box, buttons need icons, themes, variants, sizes, often
loading indicators and several interactive states, and always a delicate balance
between sub-components' positions, spacing and style.

All of this ideally delivered in a simple API that still allows complete
customization.

Tamagui allows for building a button with "compound components", a concept
popularized by [Radix](https://www.radix-ui.com/). With the introduction of
`createStyledContext` in version 1.28 this pattern has become especially easy,
so we wrote this guide to show off building more advanced compound component
APIs. While this guide covers a button, this is applicable to many types of UI
components.

So what are compound components? Simply, it's when you have, say, a
`<Button />` that wants children `<Button.Text />` and `<Button.Icon />`.

And why do they exist? Well, we'll explain that and more in this guide.

Keep in mind that this is an advanced use case. Usually you can just grab
Tamagui components off the shelf and use them with inline styles. But sometimes
you need components that want multiple related children.

This guide is more of a primer on designing compound components, teaching advanced
concepts that aren't necessary if you just want to build your app. If you just want a
simple, ready to use Button, you can use the [Tamagui Button](/ui/button)
itself directly.

### The Final Result

To the point, here is the final code we'll end up with for our Button, ready to
copy and paste right into your app:

```tsx
import { getSize, getSpace } from '@tamagui/get-token'
import {
  GetProps,
  SizeTokens,
  View,
  Text,
  createStyledContext,
  getVariableValue,
  styled,
  useTheme,
  withStaticProperties,
} from '@tamagui/core'
import { cloneElement, isValidElement, useContext } from 'react'

export const ButtonContext = createStyledContext({
  size: 'md' as SizeTokens,
})

export const ButtonFrame = styled(View, {
  displayName: 'Button',
  context: ButtonContext,
  backgroundColor: 'background hover:background-hover press:background-press',
  alignItems: 'center',
  flexDirection: 'row',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { tokens }) => ({
      height: tokens.size[name],
      borderRadius: tokens.radius[name],
      // scale the resolved token values to fit this component's proportions
      // these multipliers are a stylistic choice for this design system
      gap: tokens.space[name].val * 0.2,
      paddingHorizontal: getVariableValue(getSpace(name)) * 0.8,
    })),
  } as const,

  defaultVariants: {
    size: 'md',
  },
})

type ButtonProps = GetProps<typeof ButtonFrame>

export const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  context: ButtonContext,
  color: 'color',
  userSelect: 'none',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { font }) => ({
      fontSize: font?.size[name],
    })),
  } as const,
})

const ButtonIcon = (props: { children: any }) => {
  const { size } = useContext(ButtonContext.context)
  const smaller = getVariableValue(getSize(size)) * 0.5
  const theme = useTheme()
  return isValidElement(props.children)
    ? cloneElement(props.children, {
        size: smaller,
        color: theme.color.get(),
      })
    : null
}

export const Button = withStaticProperties(ButtonFrame, {
  Props: ButtonContext.Provider,
  Text: ButtonText,
  Icon: ButtonIcon,
})
```

Now you can use your button like so:

```tsx
export default () => (
  <Button>
    <Button.Icon>
      <Moon />
    </Button.Icon>
    <Button.Text>hi</Button.Text>
  </Button>
)

// multiple icons:
export default () => (
  <Button>
    <Button.Icon>
      <Moon />
    </Button.Icon>
    <Button.Text>hi</Button.Text>
    <Button.Icon>
      <Moon />
    </Button.Icon>
  </Button>
)
```

### Styling Text Color

In v3, `color` is not a direct prop on the Button frame. Instead, style your
text through `Button.Text`. For interactive color changes on hover or press, use
Tamagui's `group` prop to coordinate styles between parent and child:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
export default () => (
  <Button group="btn" bg="pink">
    <Button.Text color={{ default: 'blue', 'group-hover/btn': 'red' }}>
      Hello world
    </Button.Text>
  </Button>
)
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
export default () => (
  <Button group="btn" bg="pink">
    <Button.Text color="blue group-hover/btn:red">
      Hello world
    </Button.Text>
  </Button>
)
```

</MDXTabs.Content>
</MDXTabs>

By setting `group="btn"` on the Button frame, any child can reference that group
with modifiers such as `group-hover/btn:` and `group-press/btn:`.
This is more flexible and explicit than passing `color` directly, as it lets you
independently control text, icon, and frame styles for every interaction state.

This may only be about a hundred lines of code, but there's a lot to take in. And
behind the scenes, there's a lot going on to make this possible.

### From the Start

This guide will build up to this complete example from the ground up, which
should help explain both why many patterns exist, and also how they work.

We start with the assumption that we have a design system set up with tokens
that use keys `sm`, `md`, and `lg` and a few themes:

```tsx
import { createTamagui, createTokens } from '@tamagui/core'

export default createTamagui({
  tokens: createTokens({
    size: {
      sm: 38,
      md: 46,
      lg: 60,
    },
    space: {
      sm: 15,
      md: 20,
      lg: 25,
    },
    radius: {
      sm: 4,
      md: 8,
      lg: 12,
    },
    // ... the rest of your tokens
  }),

  themes: {
    light: {
      background: '#ccc',
      'background-press': '#bbb', // darker background on press
      'background-hover': '#ddd', // lighter background on hover
      color: '#222',
    },
  },

  // ... the rest of your tamagui.config.ts
})
```

If you'd like to see a more complete work-up of a Tamagui config, check out
[the Remix starter source code](https://github.com/tamagui/tamagui/blob/main/code/starters/remix/tamagui.config.ts)
or go ahead and create that starter using `npm create tamagui@latest`.

With that in mind, we can create the outer frame of the button fairly simply,
like so:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
import { View, styled } from '@tamagui/core'

const ButtonFrame = styled(View, {
  // displayName sets the React debugging identity
  displayName: 'Button',

  alignItems: 'center',
  flexDirection: 'row',

  // bare values look for theme first, then fall back to tokens
  backgroundColor: {
    default: 'background',
    hover: 'background-hover',
    press: 'background-press',
  },

  // these all use tokens
  // note that size tokens are used only for these properties:
  //   width, height, minWidth, minHeight, maxWidth and maxHeight
  height: 'md', // 46

  // meanwhile our radius token is used here
  borderRadius: 'md', // 8

  // and space tokens are used for all others
  paddingHorizontal: 'sm', // 25
})
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
import { View, styled } from '@tamagui/core'

const ButtonFrame = styled(View, {
  // displayName sets the React debugging identity
  displayName: 'Button',

  alignItems: 'center',
  flexDirection: 'row',

  // bare values look for theme first, then fall back to tokens
  backgroundColor:
    'background hover:background-hover press:background-press',

  // these all use tokens
  // note that size tokens are used only for these properties:
  //   width, height, minWidth, minHeight, maxWidth and maxHeight
  height: 'md', // 46

  // meanwhile our radius token is used here
  borderRadius: 'md', // 8

  // and space tokens are used for all others
  paddingHorizontal: 'sm', // 25
})
```

</MDXTabs.Content>
</MDXTabs>

This gets us a simple rounded rectangle that uses the `md` tokens from your
design system and the `background` styles from your theme.

The `displayName` property identifies the styled component for configuration and
debugging. V3 does not select a `light_Button` theme from that name. The frame
reads the active theme's semantic `background` values directly. Components that
need to sit above their surroundings wrap their frame in an explicit `level2`
theme boundary.

Finally, the `hover` and `press` object keys (or `hover:` and `press:` string
clauses) make the frame respond to interaction.

Next we'll want a Text component to go inside:

```tsx
import { Text, styled } from '@tamagui/core'

export const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  color: 'color',
  fontFamily: 'body',
  fontSize: 'md',
  lineHeight: 'md',
  userSelect: 'none',
})
```

This is pretty similar to the frame, just with its own name and with a `color`
set rather than a `background`. It reads the same active theme as the frame.
Finally, button text usually isn't selectable so we set `userSelect` to none.

We can use our simple button. It's nicely themed, but only renders at one size:

```tsx
export default () => (
  <Button>
    <ButtonText>Hello world</ButtonText>
  </Button>
)
```

So we'll make it sizeable. First, let's look at how we'd solve this without the
new `createStyledContext` helper, so we can understand why it exists.

We can add some variants:

```tsx
const ButtonFrame = styled(View, {
  displayName: 'Button',
  backgroundColor: 'background',
  alignItems: 'center',
  flexDirection: 'row',

  variants: {
    size: {
      sm: {
        height: 'sm',
        borderRadius: 'sm',
        gap: 4,
      },
      md: {
        height: 'md',
        borderRadius: 'md',
        gap: 6,
      },
      lg: {
        height: 'lg',
        borderRadius: 'lg',
        gap: 8,
      },
    },
  } as const,
})
```

Still, this is somewhat repetitive and prone to typos. To avoid duplication while
also working if we add new sizes later, use a branded
[`styled.dynamic`](/docs/core/variants#dynamic-variants):

```tsx
import { View, styled } from '@tamagui/core'

const ButtonFrame = styled(View, {
  displayName: 'Button',
  backgroundColor: 'background',
  alignItems: 'center',
  flexDirection: 'row',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { tokens }) => ({
      height: tokens.size[name],
      borderRadius: tokens.radius[name],
      gap: tokens.space[name].val * 0.2,
    })),
  } as const,
})

export const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  color: 'color',
  userSelect: 'none',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { font }) => ({
      fontSize: font?.size[name],
    })),
  } as const,
})
```

The generic parameter on `styled.dynamic` is the variant prop's accepted type,
so callback values stay contextually typed under `noImplicitAny`.

So now we can pass in our new `size` property:

```tsx
<ButtonFrame size="md">
  <ButtonText size="md" />
</ButtonFrame>
```

Let's clean up these two components so they are more clearly meant to be
used together (and are easier to import for users):

```tsx
export const Button = ButtonFrame as typeof ButtonFrame & {
  Text: typeof ButtonText
}

Button.Text = ButtonText
```

What is this whole `typeof ButtonFrame` thing? It's just TypeScript being
awkward. Since Tamagui uses this pattern internally for many components, we've
made a small helper:

```tsx
import { withStaticProperties } from '@tamagui/core'

export const Button = withStaticProperties(ButtonFrame, {
  Text: ButtonText,
})
```

Which is functionally the same as the above. So, now our users can do:

```tsx
import { Button } from './OurButton'

export default () => (
  <Button size="md">
    <Button.Text size="md">Hello world</Button.Text>
  </Button>
)
```

### Improving the API

Great. We've gotten our custom Button exported. But there's something quite
unfortunate about our API as it stands, and that is that we have to always pass
`size` to both components. This is brittle and ugly.

One typical way to solve this would be to abstract both of these components into
our own React component:

```tsx
const Button = ({
  size,
  children,
  textProps,
  ...props
}: ViewProps & {
  textProps?: TextProps
}) => (
  <ButtonFrame size={size} {...props}>
    <ButtonText size={size} {...textProps}>
      {children}
    </ButtonText>
  </ButtonFrame>
)
```

But suddenly we have issues. What if a user wants to show an icon? We need to
add `icon` and `iconProps`. And what if they want to change the order? You may
reach for something like `direction="reverse"`. But then what if they want a
loading indicator after, but an icon before. Or maybe they want to show big text
above, and smaller text below.

The problem with abstracting your Button into a single component is that the
internals are surprisingly flexible, and ideally they want to each be styled
independently.

Abstracting the tree structure that's output is our problem. The compound
component API gives us full control - we can customize every piece, even using
the existing `styled` function to re-style each piece, before re-exporting it
again:

```tsx
import { withStaticProperties } from '@tamagui/core'

import { Button } from './OurButton'

const CustomButtonFrame = styled(Button, {
  // override some styles
})

const CustomButtonText = styled(Button.Text, {
  // override some styles
})

export const CustomButton = withStaticProperties(CustomButtonFrame, {
  Text: CustomButtonText,
})

export default () => (
  <CustomButton>
    <CustomButton.Text>Hello world</CustomButton.Text>
    <CustomButton.Text size="sm">(Smaller text)</CustomButton.Text>
  </CustomButton>
)
```

Not to mention by staying with the `styled` world, the Tamagui optimizing
compiler extracts CSS and optimizes our Button components. Note that components
using `createStyledContext` won't be flattened, but CSS extraction and style
optimization still apply - see the [createStyledContext docs](/docs/core/create-styled-context)
for details.

So we want our compound component API both for ergonomics and for performance,
but we need some way to thread our `size` property down from the parent frame to
the inner sub-components.

### Solving size

In React this is typically what context is used for.

Here's how we'd solve for size using context in plain-old React, while still
keeping the compound API:

```tsx
import { createContext, useContext } from 'react'
import { SizeTokens, GetProps, createStyledHOC, withStaticProperties } from '@tamagui/core'
import { Button } from './OurButton'

const SizeContext = createContext<SizeTokens>('md')

const ButtonFrame = createStyledHOC(
  Button,
  ({ size = 'md', ...props }: GetProps<typeof Button>) => {
    return (
      <SizeContext.Provider value={size}>
        <Button size={size} {...props} />
      </SizeContext.Provider>
    )
  }
)

const ButtonText = createStyledHOC(Button.Text, (props: GetProps<typeof Button.Text>) => {
  const size = useContext(SizeContext)
  return <Button.Text size={size} {...props} />
})

export const NewButton = withStaticProperties(ButtonFrame, {
  Text: ButtonText,
})
```

What is `createStyledHOC`?

While it's explained in [the styled docs](/docs/core/styled#createstyledhoc),
the short of it is: if you want a functional component that returns a styled
component _to then be able to be styled again_, you need `createStyledHOC`.

That's because merging things like themes, animations, variants, media queries,
and pseudo queries is quite complex, and if Tamagui doesn't know that there is a
functional component in between some styled components it can lead to unexpected
merging of styles.

More importantly, the above code is once again verbose, duplicative, and
brittle. For example sharing more than just `size` across these components would
require a pretty significant refactor of the context with a lot of logic
memoizing the context value properly. And, once again, by moving into functional
components, your base level views now won't be as optimized by the compiler.

### The solution, createStyledContext

Finally we get to use `createStyledContext`. We just change from `createContext`
to:

```tsx
import { createStyledContext } from '@tamagui/core'

export const ButtonContext = createStyledContext({
  size: 'md' as SizeTokens,
})
```

This returns a slightly modified `React.Context` just like
`createContext` does, so you can use it with `useContext` later on. We
still export a `.context` object with the original type just in case there's any
issue.

And now, bringing back the full example, we add an extra property to each
`styled` component, `context`:

```tsx
import { View, styled, createStyledContext } from '@tamagui/core'

export const ButtonContext = createStyledContext({
  size: 'md' as SizeTokens,
})

const ButtonFrame = styled(View, {
  displayName: 'Button',
  context: ButtonContext,
  backgroundColor: 'background',
  alignItems: 'center',
  flexDirection: 'row',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { tokens }) => ({
      height: tokens.size[name],
      borderRadius: tokens.radius[name],
      gap: tokens.space[name].val * 0.2,
    })),
  } as const,
})

const ButtonText = styled(Text, {
  displayName: 'ButtonText',
  context: ButtonContext,
  color: 'color',
  userSelect: 'none',

  variants: {
    size: styled.dynamic<SizeTokens>((name, { font }) => ({
      fontSize: font?.size[name],
    })),
  } as const,
})

export const Button = withStaticProperties(ButtonFrame, {
  Text: ButtonText,
  Props: ButtonContext.Provider,
})
```

...and we've finally arrived at our destination! We can now do the following:

```tsx
import { Button } from './OurButton'

export default () => (
  <Button size="md">
    <Button.Text>Hello world</Button.Text>
  </Button>
)
```

This time since `Button` knows the `size` property is defined in the `context`
it will automatically pass size down from Button to Text, just like our
hand-rolled version did.

But - we don't have to write terribly verbose and brittle code, we get nice
types and memoization automatically, and the optimizing compiler is happy.

Notice we also exported a new property on Button, `Button.Props`.

Since `createStyledContext` returns a regular `React.Context` value, this works
the same as any other React provider. We can now control the variant from
anywhere above in the React tree:

```tsx
import { Button } from './OurButton'

export default () => (
  <Button.Props size="md">
    <Button>
      <Button.Text>Hello world</Button.Text>
    </Button>
  </Button.Props>
)
```

The only difference from `createContext` is that the `createStyledContext`
Provider just takes props directly rather than inside a `value` object (and of
course the memoization comes for free).

### Adding an Icon

Are we done?

Not quite. One final common piece of a Button is having an icon that sizes and
colors properly as well. But an icon usually comes from a third-party
library, an SVG, or perhaps an icon font.

Let's add a new component, `Button.Icon` and make this work.

Instead of going through `styled`, this component will be just a plain
functional component. It will still work nicely with the Tamagui themes and
sizes, showing how you can use them together with external React components.

```tsx
import { getTokens, useTheme } from '@tamagui/core'
import * as React from 'react'

const ButtonIcon = (props: { children: React.ReactNode }) => {
  const { size } = React.useContext(ButtonContext.context)
  const tokens = getTokens()
  const smallerSize = tokens.size[size].val * 0.5
  const theme = useTheme()
  return React.cloneElement(props.children, {
    width: smallerSize,
    height: smallerSize,
    color: theme.color.get(),
  })
}

// add it to your Button:

export const Button = withStaticProperties(ButtonFrame, {
  Text: ButtonText,
  Icon: ButtonIcon,
  Props: ButtonContext.Provider,
})
```

Now we can use it like this, assuming your Icon accepts `width`, `height`, and
`color`:

```tsx
import { MyIcon } from 'some-icon-library'

export default () => (
  <Button size="lg">
    <Button.Icon>
      <MyIcon />
    </Button.Icon>
    <Button.Text>Hello world</Button.Text>
  </Button>
)
```

Of course you can make your `Button.Icon` work a bit differently if you'd like,
say changing out `children` + `cloneElement` for something like
`<Button.Icon icon={MyIcon} />`. It's up to you.

### Conclusion

We hope this has been helpful in explaining a variety of Tamagui features and
some of the benefits and ideas behind compound components.

There's certainly further you can go in building out your Button, but we think
that in under 150 lines of code you're getting a nearly ideal API, fully typed
sizing and themes, and a great balance of customization to optimization. Note
that the compiler will still extract CSS and optimize these components, though
flattening won't apply when using `createStyledContext`.

If you are working on a smaller app, say one that shows only a few buttons at a
time or with a small set of button variations, then abstracting your Button into
a single functional Button component is totally fine.

But we'd encourage you to give the compound component API a try and see
how you like it.

With the new Tamagui APIs, sharing some props between parent and child
components no longer means carefully adding a forwardRef, re-jigging the types,
and threading context by hand, only to break memoization or scoped values
anyway.


## guides/flat-values

---
title: Flat Conditional Values
description: The V3 flat-value syntax and migration workflow
---

<IntroParagraph>
  V3 puts every condition in the value of the property it changes. Each
  property accepts string clauses or a typed object, and both render identically.
</IntroParagraph>

Tokens and theme values are bare names. V2 condition objects such as
`hoverStyle={{ backgroundColor: ... }}` have no runtime path.

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div
  bg={{ default: 'background', hover: 'background-hover', dark: 'blue-500' }}
  p={{ default: '4', sm: '6' }}
  opacity={{ disabled: 0.5 }}
/>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div
  bg="background hover:background-hover dark:blue-500"
  p="4 sm:6"
  opacity="disabled:0.5"
/>
```

</MDXTabs.Content>
</MDXTabs>

## Value grammar

Typed objects use modifier names as keys and `default` for the base value.
Compound keys such as `'dark:hover'` require every condition to match. These
are per-property values, distinct from the removed V2 condition objects.

String clauses use this grammar:

```txt
value  := base? clause*
clause := modifier (":" modifier)* ":" payload
```

The base and each payload are ordinary property values. A registered modifier
chain starts a new clause; the last matching clause wins.

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div
  p={{ default: '4', sm: '6' }}
  backgroundColor={{ default: 'red', hover: 'blue', 'dark:hover': 'navy' }}
  width={{ default: '100%', md: '42rem' }}
  boxShadow={{ default: '0 2px 8px #0003', hover: '0 4px 16px #0004' }}
  scale={{ default: 1, enter: 0.9, exit: 0.9 }}
/>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div
  p="4 sm:6"
  backgroundColor="red hover:blue dark:hover:navy"
  width="100% md:42rem"
  boxShadow="0 2px 8px #0003 hover:0 4px 16px #0004"
  scale="1 enter:0.9 exit:0.9"
/>
```

</MDXTabs.Content>
</MDXTabs>

Payloads run until the next registered modifier chain, including when they
contain spaces. An empty payload is invalid; clear a property with a real value such as `none`,
`transparent`, `initial`, or `unset`.

Do not put clauses in the raw `transform` prop. Use the flattened transform
family instead:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div
  scale={{ default: 1, hover: 1.05 }}
  rotate={{ default: '0deg', hover: '5deg' }}
/>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div scale="1 hover:1.05" rotate="0deg hover:5deg" />
```

</MDXTabs.Content>
</MDXTabs>

## Token and theme lookup

Quoted identifiers resolve config-first. A configured token, theme key, or
variable wins; a miss remains literal text so CSS keywords and custom values
pass through.

```tsx
<html.div
  p="4"
  bg="background"
  borderColor="border-color"
  width="max-content"
/>
```

Use a qualified token when the same name exists in more than one category:

```tsx
<html.div width="size.4" color="color.blue-500" />
```

A raw number remains a platform value:

```tsx
<html.div p="4" />  // configured space token
<html.div p={4} />   // 4 CSS pixels on web, 4 points on native
```

Built-in multi-part V3 names are kebab-case. The runtime does not guess aliases:

| V2 name | V3 name |
| --- | --- |
| `backgroundHover` | `background-hover` |
| `backgroundPress` | `background-press` |
| `borderColor` | `border-color` |
| `borderColorHover` | `border-color-hover` |
| `placeholderColor` | `placeholder-color` |
| `shadowColor` | `shadow-color` |

## Modifiers

The registry combines built-ins with names from your config.

| Kind | Spellings |
| --- | --- |
| interaction | `hover:` `press:` `focus:` `focus-visible:` `focus-within:` `disabled:` |
| presence | `enter:` `exit:` |
| theme | `dark:` `light:` and configured theme names |
| media | configured keys such as `sm:` `md:` `max-md:` |
| platform | `web:` `native:` `ios:` `android:` `tv:` `androidtv:` `tvos:` |
| group | `group-hover:` and named forms such as `group-hover/card:` |
| container | `@sm:` and named forms such as `@sm/layout:` |

Modifiers in one clause are an AND. For example, `dark:hover:` applies only
while both conditions match.

## Merging

Shorthands and longhands merge one property program at a time. A later base
replaces the earlier base without erasing unrelated clauses:

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div backgroundColor={{ default: 'gray', hover: 'blue' }} bg="red" />
// backgroundColor is red; hover is blue

<html.div p={{ default: '4', sm: '6' }} px="2" />
// left and right bases are 2; their sm clauses remain 6
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div backgroundColor="gray hover:blue" bg="red" />
// backgroundColor is red; hover is blue

<html.div p="4 sm:6" px="2" />
// left and right bases are 2; their sm clauses remain 6
```

</MDXTabs.Content>
</MDXTabs>

## Groups and containers

A group exposes parent state. A query container supplies dimensions.

<MDXTabs codeSyntax defaultValue="string">
<MDXTabs.List>
  <MDXTabs.Tab value="string">String</MDXTabs.Tab>
  <MDXTabs.Tab value="typed">Typed</MDXTabs.Tab>
</MDXTabs.List>

<MDXTabs.Content value="typed">

```tsx
<html.div group>
  <html.span color={{ default: 'gray', 'group-hover': 'black' }} />
</html.div>

<html.div container>
  <html.span width={{ default: '100%', '@sm': '50%' }} />
</html.div>

<html.div group="card" container="card">
  <html.span color={{ default: 'gray', '@sm/card:group-hover/card': 'black' }} />
</html.div>
```

</MDXTabs.Content>

<MDXTabs.Content value="string">

```tsx
<html.div group>
  <html.span color="gray group-hover:black" />
</html.div>

<html.div container>
  <html.span width="100% @sm:50%" />
</html.div>

<html.div group="card" container="card">
  <html.span color="gray @sm/card:group-hover/card:black" />
</html.div>
```

</MDXTabs.Content>
</MDXTabs>

Plain `sm:` is a viewport query. `@sm:` measures the nearest query container.
Only size-measuring media keys register a container form.

## Editor support

For the string spelling, TypeScript can only take autocomplete so far. It
offers each prop's token union plus every bare modifier prefix (`hover:`,
`sm:`, `dark:`), but not the cross product: that union is over a million
members, which TypeScript rejects outright and then returns *no* completions at
all. So the vocabulary lives in a language server instead.

```bash
npm install --save-dev @tamagui/lsp
```

It reads `.tamagui/tamagui.config.json`, the artifact the compiler already
writes, and gives you completions filtered as you type, diagnostics for unknown
modifiers and misspelled values with "did you mean" suggestions, hover showing a
token's resolved value per theme, and inline color swatches.

Completing a clause replaces only that clause, so accepting `background-hover`
in `bg="background hover:back"` keeps the `background` you already wrote.

It speaks stdio LSP, so every editor needs a few lines and no plugin code. The
VS Code extension, which spawns the binary for you, is not on the Marketplace
yet. For Neovim:

```lua
vim.lsp.config.tamagui = {
  cmd = { 'tamagui-lsp' },
  filetypes = { 'typescriptreact', 'javascriptreact' },
  root_markers = { 'tamagui.config.ts', 'package.json' },
}
vim.lsp.enable('tamagui')
```

Helix, Zed, Emacs, Sublime and JetBrains are all a similar few lines; see the
[package README](https://github.com/tamagui/tamagui/blob/main/code/lsp/npm/tamagui-lsp/README.md).

If completions never appear, the server is waiting for the config artifact: run
your dev server or `tamagui generate` once so the compiler emits it. When the
config changes the server picks it up and republishes on its own, with no
editor restart.

For CI and pre-commit, `tamagui check` validates every flat value in a project
and exits non-zero, which is also the right hook for coding agents:

```bash
tamagui check
```

## Migrate an existing app

The codemod in the Tamagui repository is the migration path. It recognizes old
token spellings and V2 condition objects, rewrites every statically eligible site,
and reports anything that still needs a human decision.

For example, this V2 source is migration input only:

```tsx
<View
  bg="$background"
  hoverStyle={{ bg: '$backgroundHover' }}
  $theme-dark={{ bg: '$blue10' }}
  $sm={{ p: '$6' }}
  p="$4"
/>
```

It becomes:

```tsx
<View
  bg="background hover:background-hover dark:blue10"
  p="4 sm:6"
/>
```

That output preserves the old palette name because the codemod cannot choose a
new shade for a custom design system. Check the active config before changing
it. `blue10` remains valid when the application keeps the frozen v5 pack. If
the application moved to v6, replace it with the intended v6 token, for
example `dark:blue-500`, before running the converted application.

Run write mode from your project root against one or more files or directories:

```bash
npx @tamagui/codemod-flat-values --write \
  --report flat-values-report.md \
  --json flat-values-report.json \
  path/to/src path/to/app.tsx
```

The write is transactional. A source or generated parse error means no files
are written. A path that matches no source file exits with status 2, so a typo
cannot look like a clean migration.

The report records host capability checks, values that require relocation, and
syntax the tool cannot safely infer. Common manual cases include:

- a condition that changes a component variant rather than a style property;
- a dynamic condition object or value whose type is not provable;
- a named container whose declaring parent is outside the scanned file;
- a transform array or other structured native value;
- ordering across an opaque spread that may set the same property.

Fix those rows directly in flat syntax. Do not add a compatibility setting or
restore a V2 condition-object parser.

After the write, search the migrated source for old authoring:

```bash
rg -n --glob '*.{ts,tsx,js,jsx}' \
  'hoverStyle|pressStyle|focusStyle|focusVisibleStyle|focusWithinStyle|disabledStyle|enterStyle|exitStyle|\$[A-Za-z][A-Za-z0-9-]*\s*[:=]' \
  path/to/src

rg -n --glob '*.{ts,tsx,js,jsx}' \
  '\$[A-Za-z0-9_.-]+' \
  path/to/src
```

Legacy spellings should remain only in explicit migration fixtures or tooling
that reads V2 source. Then typecheck, build, and exercise state, media, theme,
group, container, platform, and presence behavior on every target your app
ships.

The codemod package itself can be checked with:

```bash
bun run test
bun run typecheck
```


## guides/expo

---
title: Expo Guide
description: How to set up Tamagui with Expo
---

<IntroParagraph>
  Set up Tamagui in an Expo project that targets iOS, Android, and web.
</IntroParagraph>

## Install

<Notice theme="blue">
  To support dark mode, update your `app.json` to `app.config.ts` and set
  `userInterfaceStyle` to `"automatic"`.
</Notice>

### Native

Create a new [Expo](https://docs.expo.dev/get-started/create-a-project/#initialize-a-new-project) project:

```bash
yarn dlx create-expo-app -t expo-template-blank-typescript
```

<Notice theme="blue">
  This guide assumes Expo is configured with TypeScript support.
</Notice>

The following steps enable the optimizing compiler while preserving your existing Expo Babel configuration.

Add `@tamagui/cli`, which carries the Metro plugin along with the CLI and the
other bundler integrations:

```bash
yarn add -D @tamagui/cli
```

If Metro is the only bundler this project will ever use, `yarn add
@tamagui/metro-plugin` on its own is a smaller install and exports exactly the
same things.

Wrap the Expo Metro config with `withTamagui`. If you have a `tamagui.build.ts`
(recommended; see
[compiler install docs](/docs/intro/compiler-install#configuration-with-tamaguibuildts)),
no options are needed. Otherwise, pass them inline:

```js fileName="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/cli/metro')

module.exports = withTamagui(getDefaultConfig(__dirname), {
  components: ['tamagui'],
  config: './tamagui.config.ts',
})
```

If you're using a monorepo, see the [Metro guide](/docs/guides/metro).

### Expo Router / Web

- First, follow the [Metro guide](/docs/guides/metro) to enable web support.

Add `@tamagui/config` and `tamagui` to your `package.json` and install them. Then create a `tamagui.config.ts`:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const tamaguiConfig = createTamagui(defaultConfig)

export default tamaguiConfig

export type Conf = typeof tamaguiConfig

declare module 'tamagui' {
  interface TamaguiCustomConfig extends Conf {}
}
```

Then update `app/_layout.tsx`:

```tsx showMore fileName="app/_layout.tsx"
import '../tamagui.generated.css'

import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native'
import { Stack } from 'expo-router'
import { useColorScheme } from 'react-native'
import { TamaguiProvider } from 'tamagui'

import { tamaguiConfig } from '../tamagui.config'

export default function RootLayout() {
  const colorScheme = useColorScheme()

  return (
    // add this
    <TamaguiProvider config={tamaguiConfig} defaultTheme={colorScheme!}>
      <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
        <Stack>
          <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
          <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
        </Stack>
      </ThemeProvider>
    </TamaguiProvider>
  )
}
```

### Setup Tamagui

From here on out you can follow the [Installation](/docs/intro/installation) and [Configuration](/docs/core/configuration) docs.

## Loading fonts

Install the `expo-font` package:

```bash
npx expo install expo-font
```

Load your fonts so React Native can recognize them. There are several ways to do this:

<Spacer size="6" />

<InlineTabs id="font" defaultValue="tamagui">
<InlineTabs.List>
    <InlineTabs.Tab value="tamagui">Tamagui</InlineTabs.Tab>
    <InlineTabs.Tab value="expo">Expo Google Fonts</InlineTabs.Tab>
</InlineTabs.List>

<InlineTabs.Content value="tamagui">
Use the `@tamagui/font-inter` package, a pre-configured version of the Inter font that works with Tamagui:

Import the `useFonts` hook and load the fonts:

```tsx fileName="App.tsx"
import { useFonts } from 'expo-font'

function App() {
  const [loaded] = useFonts({
    Inter: require('@tamagui/font-inter/otf/Inter-Medium.otf'),
    InterBold: require('@tamagui/font-inter/otf/Inter-Bold.otf'),
  })

  useEffect(() => {
    if (loaded) {
      // can hide splash screen here
    }
  }, [loaded])

  if (!loaded) {
    return null
  }

  return <MyApp />
}
```

</InlineTabs.Content>

<InlineTabs.Content value="expo">
Use the `@expo-google-fonts` package, a collection of Google Fonts that work with Expo:

You can find the [full list of
fonts](https://github.com/expo/google-fonts/tree/master/font-packages) and usage
instructions in the [Expo documentation](https://github.com/expo/google-fonts).

Install the font package:

```bash
npx expo install @expo-google-fonts/inter
```

Import the `useFonts` hook and load the fonts:

```tsx fileName="App.tsx"
import { useFonts, Inter_400Regular, Inter_900Black } from '@expo-google-fonts/inter'

function App() {
  const [loaded] = useFonts({
    Inter_400Regular,
    Inter_900Black,
  })

  useEffect(() => {
    if (loaded) {
      // can hide splash screen here
    }
  }, [loaded])

  if (!loaded) {
    return null
  }

  return <MyApp />
}
```

</InlineTabs.Content>
</InlineTabs>

For more information on loading fonts in Expo, see the [Expo
documentation](https://docs.expo.dev/develop/user-interface/fonts/).

## First time starting Expo

The first time running your project with Tamagui, be sure to clear the cache:

```bash
npx expo start -c
```

Your `package.json` scripts should look something like this:

```json fileName="package.json"
{
  "scripts": {
    "start-native": "expo start -c",
    "start-web": "expo start -c",
    "android": "yarn expo run:android",
    "ios": "yarn expo run:ios",
    "web": "expo start --web"
  }
}
```


## guides/theme-builder

---
title: Creating Themes with Tamagui
description: Generate typed themes from color tokens and a recipe tree
demoName: ThemeBuilder
---

<HeroContainer noScroll>
  <ThemeBuilderDemo />
</HeroContainer>

<IntroParagraph>
  Tamagui v3 creates theme suites with one function: `createThemes(tokens, tree,
  { getTheme })`. The tree describes names and inheritance. Your `getTheme`
  function turns each recipe into a plain theme record.
</IntroParagraph>

The default recipe helpers live in `@tamagui/themes/builder`. The generated
default themes live in `@tamagui/themes`, so applications using
`@tamagui/config/v6` do not run the generator at startup.

## Start with the default themes

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui(defaultConfig)
```

The default suite contains light and dark roots, relative levels, `inverse`,
`accent`, `brand`, and the `red`, `yellow`, and `green` semantic colors.

## Build a theme tree

```ts fileName="themes.ts"
import {
  createThemes,
  getTheme,
  levels,
  tokens,
} from '@tamagui/themes/builder'

export const tree = {
  light: { scheme: 'light', palette: 'gray' },
  dark: { scheme: 'dark', palette: 'gray' },
  children: {
    ...levels(),
    accent: {
      palette: 'brand',
      treatment: 'tint',
      children: levels(),
    },
    inverse: ({ parent }) => ({
      scheme: parent.scheme === 'light' ? 'dark' : 'light',
      children: levels(),
    }),
    red: {
      palette: 'red',
      treatment: 'tint',
      children: levels(2),
    },
  },
} as const

export const themes = createThemes(tokens, tree, { getTheme })
export type Themes = typeof themes
```

The roots must be named `light` and `dark`. A child inherits its parent's recipe
fields by shallow merge. `children` and `values` are structural keys; every
other field is application-defined data passed to `getTheme`.

Generated names flatten the path:

```text
light
├── light_level2
│   └── light_level2_level2
├── light_accent
│   └── light_accent_level2
├── light_inverse
└── light_red
    └── light_red_level2
```

The same children attach below `dark`. Definition-local children attach only
below that definition.

## Resolve recipes with getTheme

The default resolver combines two small helpers:

```tsx
import {
  fromShades,
  ramp,
  scales,
  type GetThemeContext,
  type DefaultRecipe,
} from '@tamagui/themes/builder'

export function getTheme({ recipe }: GetThemeContext<typeof tokens, DefaultRecipe>) {
  const scale =
    scales[recipe.treatment ?? 'normal'][recipe.scheme][recipe.level ?? 1]

  return {
    ...ramp(recipe.palette, recipe.scheme, scale),
    ...fromShades(recipe.palette, scale),
  }
}
```

`ramp()` emits the adaptive `color-1` through `color-11` keys. `color-1` is nearest
the background and `color-11` is nearest the foreground in every theme. Pass the
scale so a bold light theme, whose background is deeper than its type, runs its
ramp deep to pale; without it the direction follows the scheme alone.
`fromShades()` maps numeric shades in a semantic scale to the active palette and
passes exact token names or color literals through.

These numbers describe steps relative to the theme's own scheme. They are not
Tailwind's absolute `50` through `950` scale. Only the hyphenated spelling
changed.

All generated values resolve against `tokens.color` immediately. A misspelled
token or unsupported value fails generation and reports the nearest token name.

## Relative levels

`levels()` creates self-nesting `level2`, `level3`, and `level4` children.
Their names are relative operations:

```tsx
<Theme name="level2">
  <Panel>
    <Button>{/* the Button's own level2 boundary resolves to level 3 */}</Button>
  </Panel>
</Theme>
```

At the configured maximum, deeper levels saturate. The generated names remain
valid aliases, but identical resolved maps share one parsed theme and one CSS
declaration block.

Pass a lower maximum for color themes when only one raised step is useful:

```tsx
red: {
  palette: 'red',
  treatment: 'tint',
  children: levels(2),
}
```

This creates a real `light_red_level2` map. Deeper relative paths resolve to the
same map instead of falling back to a neutral level.

## One-theme values

Recipe fields inherit. `values` apply only to the theme defined at that node:

```tsx
const tree = {
  light: {
    scheme: 'light',
    palette: 'gray',
    values: { 'border-color': 'transparent' },
  },
  dark: { scheme: 'dark', palette: 'gray' },
} as const
```

Values are applied after `getTheme`, so they are useful for a precise override.
Put data in the recipe when descendants must retain it.

You may omit `getTheme` entirely when every node supplies its theme through
`values`.

## Function children

A definition function receives the resolved parent recipe and may return a
definition or `null`:

```tsx
inverse: ({ parent }) => ({
  scheme: parent.scheme === 'light' ? 'dark' : 'light',
})
```

Returning `null` skips that path. The default `inverse` theme uses this ordinary
mechanism. Its resolved maps deduplicate with the opposite root, so inverse adds
names without duplicating declarations.

## Customize scales and treatments

The default `scales` object has `normal`, `bold`, and `tint` treatments in both
schemes at levels 1 through 4. Each level is plain data. `raise(scale, steps)`
shifts background and border shades along the `white`, `50` through `950`,
`black` ladder and clamps at its ends.

```tsx
import { raise, scales } from '@tamagui/themes/builder'

const subtleLight = {
  ...raise(scales.tint.light[1], 1),
  'border-color': 200,
}
```

Add a key to your own scales object and reference it with a recipe field. Then
use that field in your resolver. `createThemes` does not reserve `scheme`,
`palette`, `level`, or `treatment`; these are conventions implemented by the
default resolver.

## No component themes, templates, or masks

V3 does not inspect styled component display names or look for uppercase theme name
segments. A Button gets a raised theme because its skin creates a `level2`
boundary, the same operation available to application code.

The v2 builder options `componentThemes`, `templates`, `masks`,
`childrenThemes`, and `grandChildrenThemes` have no v3 equivalent. Express the
structure directly in `tree`, semantic values in scale objects, and exact
single-theme changes in `values`.

## Pre-generate a custom suite

Runtime generation is small, but a shared design system can emit the flat module
once:

```bash
npx tamagui generate-themes ./src/themes.input.ts ./src/themes.generated.ts
```

The input module exports `themes` or exports it as the default. Import the
generated module from your Tamagui config so the authoring helpers stay out of
the client bundle.

See [v6 Colors](/docs/core/config-v6-colors) for a complete custom-palette
example and [Surfaces and levels](/docs/core/surfaces) for using relative levels
in components.


## guides/metro

---
title: Metro Guide
description: How to set up Tamagui with Metro
---

<IntroParagraph>
  Expo's default Metro configuration runs Tamagui directly, with an optional
  plugin for config loading and CSS extraction.
</IntroParagraph>

## Basic Setup

The default Expo Metro configuration works out of the box:

```js fileName="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config')

module.exports = getDefaultConfig(__dirname)
```

## With Metro Plugin (Recommended)

For better dev experience, use the Metro plugin, which loads your Tamagui
config and watches for changes. It ships inside `@tamagui/cli` along with the
CLI and the other bundler integrations:

```bash
yarn add -D @tamagui/cli
```

If Metro is the only bundler this project will ever use, `yarn add
@tamagui/metro-plugin` on its own is a smaller install and exports exactly the
same things.

If you have a `tamagui.build.ts` (recommended; see
[compiler install docs](/docs/intro/compiler-install#configuration-with-tamaguibuildts)),
no options are needed:

```js fileName="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/cli/metro')

const config = getDefaultConfig(__dirname)

// reads from tamagui.build.ts automatically
module.exports = withTamagui(config)
```

Or pass options inline:

```js fileName="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/cli/metro')

const config = getDefaultConfig(__dirname)

module.exports = withTamagui(config, {
  components: ['tamagui'],
  config: './tamagui.config.ts',
})
```

## Optimized Production Builds

For maximum optimization, use the `tamagui build` command which pre-compiles
your components:

```bash
# Optimize and build, then restore source files
tamagui build --target web ./app -- expo export --platform web
```

The `--` syntax runs the command after optimization, then automatically restores
your source files. Add this to your `package.json`:

```json
{
  "scripts": {
    "build:web": "expo export --platform web",
    "build:web:optimized": "tamagui build --target web ./app -- expo export --platform web"
  }
}
```

## Debugging

To debug the compiler output, add `// debug` at the top of a file:

```tsx
// debug
import { YStack } from 'tamagui'

export function MyComponent() {
  return <YStack flex={1} bg="background" />
}
```

This will print detailed compiler output showing what optimizations are
happening:

```
[✅] flattened YStack div
```

Use `// debug-verbose` for even more detailed output.


## guides/create-tamagui-app

---
title: Bootstrapping
description: Starter kits for React Native
---

<IntroParagraph>
  Start a Tamagui app from a template with the native and web tooling already
  connected.
</IntroParagraph>

## Templates

There are five starter templates:

- Next + Expo - A production-ready monorepo with Expo Router, Solito, and
  Next.js.
- Remix - Remix with Vite.
- Takeout Free, Takeout Pro, and Takeout Pro Classic - [Takeout](/takeout)
  starters, with the paid tiers more robust and supported.

## Usage

```bash
npm create tamagui@latest
```

Check out
[the source of the templates](https://github.com/tamagui/starter-free).

A big shout out to [Fernando Rojo](https://twitter.com/fernandotherojo) for
creating [Solito](https://solito.dev), a great library for sharing all your
views between Expo and Next.js, and the bootstrap repo we borrowed from.

## Starting out

The starter-free app requires yarn to run.

To run the app:

```bash
cd myapp
yarn
yarn web # Web local dev
yarn native # Expo local dev (only for `starter-free`)
```

## Included packages (`starter-free`)

- `tamagui` for cross-platform views, themes and animations
- `solito` for cross-platform navigation
- `expo-router` for having same routing concepts between web and native
- Expo
- Next.js 13

Together they let you build universal apps from one codebase.

## Folder layout

- `apps` entry points for each app
  - `expo`
  - `next`

- `packages` shared packages across apps
  - `app` you'll be importing most files from `app/`
    - `features` (don't use a `screens` folder. organize by feature.)
    - `provider` (all the providers that wrap the app, and some no-ops for Web.)
    - `navigation` only for starter-free template, contains the navigation code
      for RN

You can add other folders inside of `packages/` if you know what you're doing
and have a good reason to.

## Start the app

- Install dependencies: `yarn`

- Next.js local dev: `yarn web`
  - Runs `yarn next`
- Expo local dev: `yarn native`
  - Runs `expo start`

## Add new dependencies

### Pure JS dependencies

If you're installing a JavaScript-only dependency that will be used across
platforms, install it in `packages/app`:

```bash
cd packages/app
yarn add date-fns
cd ../..
yarn
```

### Native dependencies

If you're installing a library with any native code, you must install it in
`apps/expo`:

```bash
cd apps/expo
yarn add react-native-reanimated

cd ../..
yarn
```

You can also install the native library inside of `packages/app` if you want to
get autoimport for that package inside of the `app` folder. However, you need to
be careful and install the _exact_ same version in both packages. If the
versions mismatch at all, you'll potentially get terrible bugs. This is a
classic monorepo issue. I use `lerna-update-wizard` to help with this (you don't
need to use Lerna to use that lib).


## guides/vite

---
title: Vite Guide
description: How to set up Tamagui with Vite
---

<IntroParagraph>
  Tamagui's Vite integration loads your config and can extract component styles
  to CSS at build time.
</IntroParagraph>

The Vite plugin and the `tamaguiAliases` helper are exported from `@tamagui/cli/vite`.

## Install

<Notice theme="yellow">
  The Vite plugin is ESM-only. Your project must have `"type": "module"` in its
  `package.json` (or use `.mjs`/`.mts` config files). CJS (`require()`) is not supported.
</Notice>

For a full-featured example, you can create a new app using `npm create tamagui@latest`
and select the 'Remix' option, which includes a Vite setup.

Create a new [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) project:

```bash
npm create vite@latest
```

Add `@tamagui/cli`, which carries the Vite plugin along with the CLI and the other bundler integrations:

```bash
yarn add -D @tamagui/cli
```

If Vite is the only bundler this project will ever use, `yarn add @tamagui/vite-plugin` on its own is a smaller install and exports exactly the same things. Swap the import in the examples below if you go that way.

### Configuration

Update your `vite.config.ts`. If you have a `tamagui.build.ts` (recommended;
see [compiler install docs](/docs/intro/compiler-install#configuration-with-tamaguibuildts)),
no options are needed:

```tsx fileName="vite.config.ts"
import { tamaguiPlugin } from '@tamagui/cli/vite'

export default {
  plugins: [
    // reads from tamagui.build.ts automatically
    tamaguiPlugin(),
  ].filter(Boolean),
}
```

Or pass options inline:

```tsx fileName="vite.config.ts"
import { tamaguiPlugin } from '@tamagui/cli/vite'

export default {
  plugins: [
    tamaguiPlugin({
      config: 'src/tamagui.config.ts',
      components: ['tamagui'],
      disableExtraction: true,
    }),
  ].filter(Boolean),
}
```

During development, the plugin evaluates your configuration through Vite's module
runner and watches its imported dependencies. Saving a token or theme updates
`outputCSS`, `.tamagui/tamagui.config.json`, and `.tamagui/prompt.md` before the
browser reloads. Unchanged artifacts are not rewritten. You do not need to run
`tamagui generate` after each edit.

Use `disableExtraction: true` to keep runtime styling while retaining configuration
generation. `disable: true` disables configuration loading as well.

Or use a minimal manual setup for Vite that just adds compatibility for react-native-web and React Native extensions:

```tsx showMore
config.define = {
  __DEV__: `${process.env.NODE_ENV === 'development' ? true : false}`,
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
}

config.resolve.alias['react-native'] = 'react-native-web'

// set up web extensions
config.optimizeDeps.esbuildOptions = {
  ...config.optimizeDeps.esbuildOptions,
  resolveExtensions: [
    '.web.js',
    '.web.jsx',
    '.web.ts',
    '.web.tsx',
    '.mjs',
    '.js',
    '.mts',
    '.ts',
    '.jsx',
    '.tsx',
    '.json',
  ],
  loader: {
    '.js': 'jsx',
  },
}
```

### Custom Aliases with tamaguiAliases

For advanced use cases where you need more control over alias ordering in your Vite config, you can use the `tamaguiAliases` helper function:

```tsx fileName="vite.config.ts"
import { tamaguiAliases } from '@tamagui/cli/vite'

export default {
  resolve: {
    alias: [
      // your custom aliases first
      { find: '@app', replacement: '/src' },
      // then tamagui aliases
      ...tamaguiAliases({
        // use @tamagui/react-native-web-lite for smaller bundle
        rnwLite: true,
        // or 'without-animated' for even smaller bundle (no Animated API)
        // rnwLite: 'without-animated',
        // alias react-native-svg to @tamagui/react-native-svg
        svg: true,
      }),
    ],
  },
}
```

This is useful when you need to ensure specific alias resolution order or when using a custom Vite setup without the full `tamaguiPlugin`.


## guides/next-js

---
title: Next.js Guide
description: How to set up Tamagui with Next.js
---

<IntroParagraph>
  Add Tamagui to a Next.js app with shared configuration, SSR-safe themes, and
  optional compiler extraction.
</IntroParagraph>

Running `npm create tamagui@latest` lets you choose the configured `starter-free`
Next.js app as a starting point.

Create a new [Next.js](https://nextjs.org/docs/getting-started/installation)
project:

```bash
npx create-next-app@latest
```

We recommend starting with our default config which gives you media queries and
other nice things:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui' // or '@tamagui/core'

const appConfig = createTamagui(defaultConfig)

export type AppConfig = typeof appConfig

declare module 'tamagui' {
  // or '@tamagui/core'
  // overrides TamaguiCustomConfig so your custom types
  // work everywhere you import `tamagui`
  interface TamaguiCustomConfig extends AppConfig {}
}

export default appConfig
```

## Setup

Next.js uses Turbopack by default. In dev mode, Tamagui works without any setup.
For production builds, use the Tamagui CLI to optimize your build.

Install the CLI:

```bash
yarn add -D @tamagui/cli
```

Create `tamagui.build.ts`:

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from '@tamagui/core'

export default {
  components: ['@tamagui/core'], // or ['tamagui']
  config: './tamagui.config.ts',
  outputCSS: './public/tamagui.generated.css',
} satisfies TamaguiBuildOptions
```

Your `next.config.ts` needs some configuration:

```ts fileName="next.config.ts"
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      resolveAlias: {
        'react-native': 'react-native-web',
        'react-native-svg': '@tamagui/react-native-svg',
      },
    },
  },
}

export default nextConfig
```

<Notice theme="blue">
  The `transpilePackages` array may need additional packages depending on which Tamagui
  packages you use. If you see module resolution errors, try adding the problematic
  package to this array.
</Notice>

### Build Scripts

The CLI can wrap your build command, optimizing files beforehand and restoring
them after:

```json fileName="package.json"
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "tamagui build --target web ./src -- next build"
  }
}
```

The `--` separator tells the CLI to run `next build` after optimization, then
restore your source files automatically.

You can also target specific files or use `--include`/`--exclude` patterns:

```bash
# Target specific files
tamagui build --target web ./src/components/Button.tsx ./src/components/Card.tsx -- next build

# Use glob patterns
tamagui build --target web --include "src/components/**/*.tsx" --exclude "src/components/**/*.test.tsx" ./src -- next build
```

### CSS Setup

The CLI generates theme CSS to `outputCSS`. Commit this file to git and import
it in your layout:

```tsx fileName="app/layout.tsx"
import '../public/tamagui.generated.css'
import { TamaguiProvider } from '@tamagui/core'
import config from '../tamagui.config'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TamaguiProvider config={config}>{children}</TamaguiProvider>
      </body>
    </html>
  )
}
```

With React 19, Tamagui automatically injects runtime styles via style tags. The
`outputCSS` file handles themes and tokens that are generated at build time.

Run `npx tamagui build` once to generate the initial CSS file, then commit it.

### CI Verification

Use `--expect-optimizations` to fail builds if the compiler optimizes fewer than
the expected minimum number of components:

```json
{
  "build": "tamagui build --target web --expect-optimizations 5 ./src -- next build"
}
```

This will fail the build if fewer than 5 components are optimized, helping catch
configuration issues in CI.

## Themes

We've created a package called `@tamagui/next-theme` that properly supports SSR
light/dark themes while respecting user system preferences. It assumes your
themes are named `light` and `dark`, but you can override this. This is
pre-configured in the create-tamagui starter.

```bash
yarn add @tamagui/next-theme
```

Here's how to set up your `NextTamaguiProvider.tsx`:

```tsx fileName="NextTamaguiProvider.tsx"
'use client'

import { ReactNode } from 'react'
import { NextThemeProvider, useRootTheme } from '@tamagui/next-theme'
import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from '../tamagui.config'

export const NextTamaguiProvider = ({ children }: { children: ReactNode }) => {
  const [theme, setTheme] = useRootTheme()

  return (
    <NextThemeProvider
      skipNextHead
      // change default theme (system) here:
      // defaultTheme="light"
      onChangeTheme={(next) => {
        setTheme(next as any)
      }}
    >
      <TamaguiProvider config={tamaguiConfig} defaultTheme={theme}>
        {children}
      </TamaguiProvider>
    </NextThemeProvider>
  )
}
```

Then update your `app/layout.tsx`:

```tsx fileName="app/layout.tsx"
import '../public/tamagui.generated.css'
import { Metadata } from 'next'
import { NextTamaguiProvider } from './NextTamaguiProvider'

export const metadata: Metadata = {
  title: 'Your page title',
  description: 'Your page description',
  icons: '/favicon.ico',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextTamaguiProvider>{children}</NextTamaguiProvider>
      </body>
    </html>
  )
}
```

## NextThemeProvider

`NextThemeProvider` lets you set the theme for your app and provides a hook to
access the current theme and toggle between themes.

```bash
yarn add @tamagui/next-theme
```

<PropsTable
  data={[
    {
      name: 'skipNextHead',
      required: false,
      type: 'boolean',
      description: `Required in app router. The internal usage of next/head is not supported in the app directory, so you need to add it.`,
    },
    {
      name: 'enableSystem',
      required: false,
      type: 'boolean',
      description: `Whether to switch between dark and light themes based on prefers-color-scheme.`,
    },
    {
      name: 'defaultTheme',
      required: false,
      type: 'string',
      description:
        'If enableSystem is `false`, the default theme is light. Default theme name (for v0.0.12 and lower the default was light).',
    },
    {
      name: 'forcedTheme',
      required: false,
      type: 'string',
      description: 'Forced theme name for the current page.',
    },
    {
      name: 'onChangeTheme',
      required: false,
      type: '(name: string) => void',
      description:
        'Used to change the current theme. The function receives the theme name as a parameter.',
    },
    {
      name: 'systemTheme',
      required: false,
      type: 'string',
      description: 'System theme name for the current page.',
    },
    {
      name: 'enableColorScheme',
      required: false,
      type: 'boolean',
      description: `Whether to indicate to browsers which color scheme is used (dark or light) for built-in UI like inputs and buttons.`,
    },
    {
      name: 'disableTransitionOnChange',
      required: false,
      type: 'boolean',
      description: `Disable all CSS transitions when switching themes.`,
    },
    {
      name: 'storageKey',
      required: false,
      type: 'string',
      description: `Key used to store theme setting in localStorage.`,
    },
    {
      name: 'themes',
      required: false,
      type: 'string[]',
      description: `List of all available theme names.`,
    },
    {
      name: 'value',
      required: false,
      type: 'ValueObject',
      description: `Mapping of theme name to HTML attribute value. Object where key is the theme name and value is the attribute value.`,
    },
  ]}
/>

### Theme toggle

If you need to access the current theme, say for a toggle button, you will then
use the `useThemeSetting` hook. We'll release an update in the future that makes
this automatically work better with Tamagui's built-in `useThemeSetting`.

```tsx fileName="SwitchThemeButton.tsx"
import { useState } from 'react'
import { Button, useIsomorphicLayoutEffect } from 'tamagui'
import { useThemeSetting, useRootTheme } from '@tamagui/next-theme'

export const SwitchThemeButton = () => {
  const themeSetting = useThemeSetting()
  const [theme] = useRootTheme()

  const [clientTheme, setClientTheme] = useState<string | undefined>('light')

  useIsomorphicLayoutEffect(() => {
    setClientTheme(themeSetting.forcedTheme || themeSetting.current || theme)
  }, [themeSetting.current, themeSetting.resolvedTheme])

  return <Button onPress={themeSetting.toggle}>Change theme: {clientTheme}</Button>
}
```

---

## For Older Versions

The following sections cover setup for older Next.js versions using Webpack
instead of Turbopack.

### Webpack Plugin

If you aren't using Turbopack, you may want the optional `@tamagui/next-plugin`,
which smooths out a few settings. See the
[compiler install docs](/docs/intro/compiler-install) for more options.

Add `@tamagui/next-plugin` to your project:

```bash
yarn add @tamagui/next-plugin
```

## Pages Router

### next.config.js

Set up the optional Tamagui plugin in `next.config.js`:

```js showMore fileName="next.config.js"
const { withTamagui } = require('@tamagui/next-plugin')

module.exports = function (name, { defaultConfig }) {
  let config = {
    ...defaultConfig,
    // ...your configuration
  }
  const tamaguiPlugin = withTamagui({
    config: './tamagui.config.ts',
    components: ['tamagui'],
  })
  return {
    ...config,
    ...tamaguiPlugin(config),
  }
}
```

### pages/\_document.tsx

If you're using React Native Web components, gather the `react-native-web`
styles in `_document.tsx`:

```tsx fileName="_document.tsx"
import NextDocument, {
  DocumentContext,
  Head,
  Html,
  Main,
  NextScript,
} from 'next/document'
import { StyleSheet } from 'react-native'

export default class Document extends NextDocument {
  static async getInitialProps({ renderPage }: DocumentContext) {
    const page = await renderPage()

    // @ts-ignore RN doesn't have this type
    const rnwStyle = StyleSheet.getSheet()

    return {
      ...page,
      styles: (
        <style
          id={rnwStyle.id}
          dangerouslySetInnerHTML={{ __html: rnwStyle.textContent }}
        />
      ),
    }
  }
  render() {
    return (
      <Html lang="en">
        <Head>
          <meta id="theme-color" name="theme-color" />
          <meta name="color-scheme" content="light dark" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}
```

Tamagui automatically injects styles at runtime. You can optionally generate a
static CSS file; see [Static CSS Output](#static-css-output-pages-router).

### pages/\_app.tsx

Add `TamaguiProvider`:

```tsx fileName="_app.tsx"
import { NextThemeProvider } from '@tamagui/next-theme'
import { AppProps } from 'next/app'
import Head from 'next/head'
import React, { useMemo } from 'react'
import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from '../tamagui.config'

export default function App({ Component, pageProps }: AppProps) {
  // memo to avoid re-render on dark/light change
  const contents = useMemo(() => {
    return <Component {...pageProps} />
  }, [pageProps])

  return (
    <>
      <Head>
        <title>Your page title</title>
        <meta name="description" content="Your page description" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <NextThemeProvider>
        <TamaguiProvider config={tamaguiConfig} disableInjectCSS>
          {contents}
        </TamaguiProvider>
      </NextThemeProvider>
    </>
  )
}
```

<Notice theme="blue">
  Use `disableInjectCSS` for SSR apps to prevent duplicate style injection. Only omit it
  for client-only apps without server rendering.
</Notice>

### Themes (Pages Router)

We've created a package called `@tamagui/next-theme` that properly supports SSR
light/dark themes while respecting user system preferences. It assumes your
themes are named `light` and `dark`, but you can override this. This is
pre-configured in the create-tamagui starter.

```bash
yarn add @tamagui/next-theme
```

Here's how to set up your `_app.tsx`:

```tsx fileName="_app.tsx"
import { NextThemeProvider, useRootTheme } from '@tamagui/next-theme'
import { AppProps } from 'next/app'
import Head from 'next/head'
import React, { useMemo } from 'react'
import { TamaguiProvider, createTamagui } from 'tamagui'

// you usually export this from a tamagui.config.ts file:
import { defaultConfig } from '@tamagui/config/v6'
const tamaguiConfig = createTamagui(defaultConfig)

// make TypeScript type everything based on your config
type Conf = typeof tamaguiConfig
declare module '@tamagui/core' {
  interface TamaguiCustomConfig extends Conf {}
}

export default function App({ Component, pageProps }: AppProps) {
  const [theme, setTheme] = useRootTheme()

  // memo to avoid re-render on dark/light change
  const contents = useMemo(() => {
    return <Component {...pageProps} />
  }, [pageProps])

  return (
    <>
      <Head>
        <title>Your page title</title>
        <meta name="description" content="Your page description" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <NextThemeProvider
        // change default theme (system) here:
        // defaultTheme="light"
        onChangeTheme={setTheme as any}
      >
        <TamaguiProvider
          config={tamaguiConfig}
          disableInjectCSS
          defaultTheme={theme}
        >
          {contents}
        </TamaguiProvider>
      </NextThemeProvider>
    </>
  )
}
```

### Static CSS Output (Pages Router)

You can generate a static CSS file for your themes and tokens. There are two
ways to do this:

#### Option 1: Using the CLI

The simplest approach is to use the Tamagui CLI to generate the CSS file:

```bash
npx tamagui generate
```

This outputs CSS to `.tamagui/tamagui.generated.css`. Copy it to your public folder or
configure `outputCSS` in your `tamagui.build.ts`:

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from '@tamagui/core'

export default {
  components: ['tamagui'],
  config: './tamagui.config.ts',
  outputCSS: './public/tamagui.generated.css',
} satisfies TamaguiBuildOptions
```

Then import it in your `_app.tsx`:

```tsx fileName="_app.tsx"
import '../public/tamagui.generated.css'
```

#### Option 2: Using the Next.js Plugin

You can also have the plugin generate CSS during your Next.js build:

```js fileName="next.config.js"
const tamaguiPlugin = withTamagui({
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: process.env.NODE_ENV === 'production' ? './public/tamagui.generated.css' : null,
  // faster dev mode, keeps debugging helpers:
  disableExtraction: process.env.NODE_ENV === 'development',
})
```

Then import it in your `_app.tsx`:

```tsx fileName="_app.tsx"
import '../public/tamagui.generated.css'
```

With `outputCSS`, you don't need `getCSS()` in your `_document.tsx`; all styles are
handled by the static CSS file and runtime style injection.

## App Router (Webpack)

Tamagui includes Server Components support for the Next.js app directory with
[`use client`](https://nextjs.org/docs/app/building-your-application/rendering/client-components#using-client-components-in-nextjs)
support.

Note that `"use client"` components do render on the server, and since Tamagui
extracts to CSS statically and uses inline `<style />` tags for non-static
styling, you get excellent performance out of the box.

### next.config.js

The Tamagui plugin is optional but helps with compatibility with the rest of the
React Native ecosystem. It requires CommonJS for now because the optimizing
compiler uses various resolving features that haven't been ported to ESM yet.
Rename your `next.config.mjs` to `next.config.js` before adding it:

```js fileName="next.config.js"
const { withTamagui } = require('@tamagui/next-plugin')

module.exports = function (name, { defaultConfig }) {
  let config = {
    ...defaultConfig,
    // ...your configuration
  }

  const tamaguiPlugin = withTamagui({
    config: './tamagui.config.ts',
    components: ['tamagui'],
    appDir: true,
  })

  return {
    ...config,
    ...tamaguiPlugin(config),
  }
}
```

<Notice theme="blue">
  You need to pass the `appDir` boolean to `@tamagui/next-plugin`.
</Notice>

### app/layout.tsx

Create a new component to add `TamaguiProvider`:

<Notice theme="blue">
  The internal usage of `next/head` is not supported in the app directory, so you need to add the `skipNextHead` prop to your `<NextThemeProvider>`.
</Notice>

```tsx fileName="NextTamaguiProvider.tsx"
'use client'

import { ReactNode } from 'react'
import { StyleSheet } from 'react-native'
import { useServerInsertedHTML } from 'next/navigation'
import { NextThemeProvider } from '@tamagui/next-theme'
import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from '../tamagui.config'

export const NextTamaguiProvider = ({ children }: { children: ReactNode }) => {
  // only if using react-native-web components like ScrollView:
  useServerInsertedHTML(() => {
    // @ts-ignore
    const rnwStyle = StyleSheet.getSheet()
    return (
      <>
        <style
          dangerouslySetInnerHTML={{ __html: rnwStyle.textContent }}
          id={rnwStyle.id}
        />
      </>
    )
  })

  return (
    <NextThemeProvider skipNextHead>
      <TamaguiProvider config={tamaguiConfig}>
        {children}
      </TamaguiProvider>
    </NextThemeProvider>
  )
}
```

The `getNewCSS` helper in Tamagui will keep track of the last call and only return new
styles generated since the last usage.

Then add it to your `app/layout.tsx`:

```tsx fileName="layout.tsx"
import { Metadata } from 'next'
import { NextTamaguiProvider } from './NextTamaguiProvider'

export const metadata: Metadata = {
  title: 'Your page title',
  description: 'Your page description',
  icons: '/favicon.ico',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextTamaguiProvider>{children}</NextTamaguiProvider>
      </body>
    </html>
  )
}
```

<Notice theme="green">
  You can use `suppressHydrationWarning` to avoid the warning about mismatched content
  during hydration in dev mode.
</Notice>

### app/page.tsx

Now you're ready to start adding components to `app/page.tsx`:

```tsx fileName="page.tsx"
'use client'

import { Button } from 'tamagui'

export default function Home() {
  return <Button>Hello world!</Button>
}
```

### Themes (App Router Webpack)

We've created a package called `@tamagui/next-theme` that properly supports SSR
light/dark themes while respecting user system preferences. It assumes your
themes are named `light` and `dark`, but you can override this. This is
pre-configured in the create-tamagui starter.

```bash
yarn add @tamagui/next-theme
```

Here's how to set up your `NextTamaguiProvider.tsx`:

```tsx fileName="NextTamaguiProvider.tsx"
'use client'

import { ReactNode } from 'react'
import { StyleSheet } from 'react-native'
import { useServerInsertedHTML } from 'next/navigation'
import { NextThemeProvider, useRootTheme } from '@tamagui/next-theme'
import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from '../tamagui.config'

export const NextTamaguiProvider = ({ children }: { children: ReactNode }) => {
  const [theme, setTheme] = useRootTheme()

  // only needed if using react-native-web components:
  useServerInsertedHTML(() => {
    // @ts-ignore
    const rnwStyle = StyleSheet.getSheet()
    return (
      <style
        dangerouslySetInnerHTML={{ __html: rnwStyle.textContent }}
        id={rnwStyle.id}
      />
    )
  })

  return (
    <NextThemeProvider
      skipNextHead
      // change default theme (system) here:
      // defaultTheme="light"
      onChangeTheme={(next) => {
        setTheme(next as any)
      }}
    >
      <TamaguiProvider config={tamaguiConfig} defaultTheme={theme}>
        {children}
      </TamaguiProvider>
    </NextThemeProvider>
  )
}
```

### Static CSS Output (App Router Webpack)

You can generate a static CSS file for your themes and tokens. Use either the
CLI or the Next.js plugin:

```js fileName="next.config.js"
const tamaguiPlugin = withTamagui({
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: process.env.NODE_ENV === 'production' ? './public/tamagui.generated.css' : null,
  // faster dev mode, keeps debugging helpers:
  disableExtraction: process.env.NODE_ENV === 'development',
})
```

Then link the generated CSS file in your `app/layout.tsx`:

```tsx fileName="app/layout.tsx"
import '../public/tamagui.generated.css'
```

With React 19, Tamagui automatically injects runtime styles via style tags on the
server. The `outputCSS` file handles themes and tokens generated at build time, so you
don't need any `getCSS()` calls in your provider.


## guides/one

---
title: One Guide
description: How to set up Tamagui with One
---

<IntroParagraph>
  [One](https://onestack.dev) is a Vite-based React framework for web, iOS, and
  Android with built-in Tamagui integration.
</IntroParagraph>

## Install

First, create a new One project:

```bash
npx one
```

Add Tamagui and its dependencies. `@tamagui/cli` carries the Vite plugin used
below, alongside the CLI and the other bundler integrations:

```bash
yarn add tamagui @tamagui/config
yarn add -D @tamagui/cli
```

## Configuration

Create a `tamagui.config.ts` file in your project root:

```tsx fileName="tamagui.config.ts"
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

const tamaguiConfig = createTamagui(defaultConfig)

export default tamaguiConfig

// this is important!
export type Conf = typeof tamaguiConfig

declare module 'tamagui' {
  interface TamaguiCustomConfig extends Conf {}
}
```

Update your `vite.config.ts`:

```tsx fileName="vite.config.ts"
import { one } from 'one/vite'
import { tamaguiPlugin } from '@tamagui/cli/vite'
import type { UserConfig } from 'vite'

export default {
  plugins: [
    one({
      web: {
        defaultRenderMode: 'ssg',
      },
    }),
    tamaguiPlugin({
      config: './tamagui.config.ts',
      components: ['tamagui'],
    }),
  ],

  // Vite 6 style configuration
  ssr: {
    noExternal: true,
  },

  optimizeDeps: {
    include: ['@tamagui/core', '@tamagui/config'],
  },

  build: {
    cssTarget: 'safari15',
  },
} satisfies UserConfig
```

## Setup Tamagui Provider

Update your root layout file (typically `app/_layout.tsx`):

```tsx fileName="app/_layout.tsx"
import { TamaguiProvider } from 'tamagui'
import { Slot } from 'one'
import config from '../tamagui.config'

export default function Layout() {
  return (
    <TamaguiProvider config={config}>
      <Slot />
    </TamaguiProvider>
  )
}
```

## Usage

Now you can use Tamagui components in your One app:

```tsx fileName="app/index.tsx"
import { Button, YStack, html } from 'tamagui'

export default function Home() {
  return (
    <YStack flex={1} justify="center" items="center" p="4" gap="4">
      <html.h1 fontSize="6">Welcome to Tamagui with One!</html.h1>
      <Button>Click me</Button>
    </YStack>
  )
}
```

## Themes

To support light and dark modes, use One's built-in color scheme support along with Tamagui's theming system. Update your root layout:

```tsx fileName="app/_layout.tsx"
import { TamaguiProvider, Theme } from 'tamagui'
import { Slot } from 'one'
import { useColorScheme } from 'react-native'
import config from '../tamagui.config'

export default function Layout() {
  const colorScheme = useColorScheme()

  return (
    <TamaguiProvider config={config} defaultTheme={colorScheme}>
      <Theme name={colorScheme}>
        <Slot />
      </Theme>
    </TamaguiProvider>
  )
}
```

## Performance

For better performance, use the `outputCSS` option in the Tamagui Vite plugin:

```tsx fileName="vite.config.ts"
tamaguiPlugin({
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: process.env.NODE_ENV === 'production' ? './public/tamagui.generated.css' : null,
})
```

Then import the CSS in your root layout:

```tsx fileName="app/_layout.tsx"
import '../public/tamagui.generated.css'
// ... rest of your imports and component
```

## Next Steps

You now have Tamagui set up with [One](https://onestack.dev).


## guides/zero-runtime

---
title: Zero-runtime mode
description: Build a web entry with generated CSS and no Tamagui component runtime
---

<IntroParagraph>
  Zero-runtime mode compiles eligible web entries to React host elements and one
  CSS artifact with no Tamagui component runtime in their JavaScript graph.
</IntroParagraph>

This experimental tier is for pages whose Tamagui styling can be fully resolved
at build time.

React and React DOM remain. Ordinary React host elements can still use React's
`style` prop, which sits outside the Tamagui zero-runtime contract.

Use this mode for static product, documentation, content, and marketing
surfaces. Put behavior that needs the full Tamagui runtime in a separately built
island.

## Supported integrations

Tamagui 3 qualifies zero entries and full-runtime islands on:

- Vite web
- Next.js with the webpack Tamagui integration
- Metro web

Native builds always use the full runtime. A cross-platform project can enable
the option in its shared build config because the integration keeps native on
the full path.

## Audit an app first

Start with report mode in the same `tamagui.build.ts` used by your bundler:

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  experimental: {
    zeroRuntime: 'report',
  },
} satisfies TamaguiBuildOptions
```

Report mode performs zero-runtime analysis and writes its receipts, while the
build keeps the full runtime and exits successfully. It is an audit tool rather
than a runtime tier. Fix each reported site or assign its owning module to an
island before enforcing the mode.

## Enforce the zero entry

Enforcement requires an `outputCSS` path:

```ts fileName="tamagui.build.ts"
import type { TamaguiBuildOptions } from 'tamagui'

export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: './.tamagui/zero/tamagui-zero.css',
  experimental: {
    zeroRuntime: true,
  },
} satisfies TamaguiBuildOptions
```

Keep the generated `.tamagui` directory out of source control. The bundler owns
the CSS artifact and only marks the JavaScript graph as zero-runtime after that
artifact exists. Vite injects the zero stylesheet from its entry. Next and
Metro publish the artifact for the application document to link:

```html
<link rel="stylesheet" href="/tamagui-zero.css" />
```

Do not set `TAMAGUI_RUNTIME` in the shell. It is generated output owned by the
integration, which inlines either `"full"` or `"zero"` after resolving the
public build option and artifact.

The zero root has no `TamaguiProvider`. Configuration evaluation happens in a
separate full-runtime build environment, and the integration turns its tokens,
fonts, themes, root rules, and extracted atomic rules into the generated
stylesheet.

```tsx
import { useState } from 'react'
import { Theme, html } from 'tamagui'

export function Page() {
  const [dark, setDark] = useState(false)

  return (
    <Theme name={dark ? 'dark' : 'light'}>
      <html.div backgroundColor="background" padding="6">
        <html.p color="color">This component tree lowers completely.</html.p>
        <button onClick={() => setDark((value) => !value)}>toggle theme</button>
      </html.div>
    </Theme>
  )
}
```

The compiler can enumerate the two literal theme names in this example. Theme
switching becomes a class change and does not ship Tamagui theme state.

## The eight authoring rules

An enforced build collects every violation, sorts the report by source
location, then fails. The contract is:

1. Pass props explicitly. Prop spreads on Tamagui and `html.*` elements are
   rejected because the compiler cannot prove they are style-free.
2. Use literal component targets. A dynamic component expression must resolve
   to one lowerable host component.
3. Keep Tamagui style values build-time data. This covers element props,
   `styled()` definitions, variants, and direct `Theme` values.
4. Keep config and themes static. Use compiler-visible `Theme` names and direct
   theme values. Runtime theme mutation and `TamaguiProvider` belong in an
   island.
5. Use the CSS animation driver. Static CSS transitions lower; presence,
   layout-driven animation, dynamic driver selection, and non-CSS drivers need
   an island.
6. Use lowerable components. A component that cannot become one host element
   is island-only.
7. Express design state in CSS. JavaScript reads such as `useMedia`, `useTheme`,
   `getConfig`, `getToken`, and `useAnimationDriver` need the full runtime.
8. Keep the module graph erasable. Bare side-effect Tamagui imports are
   rejected, and an island must be reached through its generated loader rather
   than a static import.

The final bundler gate checks the emitted module graph as well as compiler
diagnostics. A build fails if any forbidden Tamagui module remains reachable,
even when the compiler could not attribute that path to a precise source site.

## Full-runtime islands

Declare island roots as project-relative globs:

```ts fileName="tamagui.build.ts"
export default {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  outputCSS: './.tamagui/zero/tamagui-zero.css',
  experimental: {
    zeroRuntime: {
      islands: ['src/islands/DetailsIsland.tsx'],
    },
  },
}
```

The integration generates a loader and a separate full-runtime entry for each
island. Import the loader from zero code:

```tsx
import DetailsIsland from '../.tamagui/zero/DetailsIsland.loader'

export function Page() {
  return <DetailsIsland productId="42" />
}
```

A direct import of `src/islands/DetailsIsland.tsx` is a build error. The island
is compiled with the full runtime, mounts its own provider, and receives the
static theme context at its compiler-visible mount point. Island server output
is a deterministic placeholder. The client loads and mounts the island after
hydration, so content that must appear in server HTML needs a full-runtime route
or a lowerable zero component.

All declared island CSS is included in the same generated stylesheet as the
zero entry. Island JavaScript remains a separate download.

## Animation scope

Static CSS transitions remain CSS. Component animation machinery does not ship
in the zero entry. Four numeric hooks are the one optional Tamagui client leaf:

```ts
useAnimatedNumber
useAnimatedNumberStyle
useAnimatedNumbersStyle
useAnimatedNumberReaction
```

When one of these hooks is imported from `tamagui` or `@tamagui/core`, the
compiler rewrites it directly to the small CSS animated-number entry. No other
Tamagui client module is allowlisted.

## Keep generated CSS small

Zero-runtime moves design-system work from client JavaScript into CSS, so theme
reachability matters. The first release does not automatically prune a broad
theme pack. Narrow themes and tokens in `tamagui.config.ts` to what the entry
uses.

The repository starter's two-theme, five-color-token config produced 2,695
bytes gzip of CSS for its real screen. The unnarrowed v6 config measured 17,243
bytes gzip. These are configuration outcomes, so use your emitted artifact as
the measurement for your app.

## Start from the working fixture

`code/starters/zero-runtime` in the Tamagui repository contains one source tree
built with Vite, Next webpack, and Metro web. It demonstrates a providerless
root, static theme switching, a CSS transition, a narrowed config, one modal
island, graph receipts, size ceilings, and Playwright coverage.

Run its complete measurement and browser checks with:

```bash
cd code/starters/zero-runtime
bun run measure
bun run test
```

The retained 2026-08-18 receipt found zero Tamagui modules, zero forbidden
modules, and zero compiler violations in all six base and island builds. A
separate fully flattened probe measured seven gzip bytes above its hand-written
React control. That number describes the conforming probe, not an ordinary
full-runtime Tamagui app.


## guides/developing

---
title: Developing with Tamagui
description: Tips and tricks
---

<IntroParagraph>
  Tamagui includes runtime and compiler tools for understanding how a component
  renders and where its styles came from.
</IntroParagraph>

### Debugging

Tamagui has several ways of giving you more insight into what's happening at
compile-time.

#### Visualizer

You can set up a simple visualizer that shows a heads-up display when you
hold "Option" (or any key you define) after a short delay, revealing
the styled component display names and even the file numbers and components they are in
(if you have the compiler plugin installed) as an overlay over your app in
development mode.

```tsx
import { setupDev } from '@tamagui/core'

setupDev({
  // can just be true as well for defaulting to key: Alt + delay: 800
  visualizer: {
    key: 'Alt',
    delay: 800,
  },
})
```

#### Debug Pragma

To see what's being extracted, why, and every step along the optimization
pipeline, add `// debug` to the top of any file. Adding `// debug-verbose` will
show even more information, including more granular timings.

If you're developing in your design system package that is built with
@tamagui/build, esbuild will strip this banner. You can try using `//! debug`
(esbuild only preserves comments at the top that start with `//!`), but still
occasionally esbuild will insert a helper above the comment, breaking it, so be
sure to check the built file in `dist/jsx`.

#### Debug Prop

Adding `debug` to any Tamagui component outputs detailed information about
what's happening at runtime. Use it like so:

```tsx
import { Button } from 'tamagui'

export default () => <Button debug>Hello world</Button>
```

You'll see props, styles, and a variety of variables relevant to processing
them.

You can do `<Button debug="break" />` to have it break at the beginning of
rendering, or `<Button debug="verbose" />` to have it output more detailed debug
information.

#### DEBUG Environment Variable

If you set `DEBUG=tamagui` before your build command, you get the full
debug output of every file built. This is useful for seeing everything that's
happening across every file and is especially helpful for diagnosing production
issues.

### Runtime introspection

In development mode, Tamagui sets the variable `Tamagui` onto `globalThis` with
a lot of helpful internals, including your entire parsed config from
`tamagui.config.ts`.

Beyond your config, you have:

- **allSelectors**: All the selectors inserted by Tamagui (before runtime).

#### Inspecting Components

Any `styled()` component will have a `staticConfig` property attached to it:

```tsx
const Circle = styled(View, {
  borderRadius: 1000,
})

console.log(Circle.staticConfig) // lots of helpful information
```

- `variants` contains the merged variants including parents.
- `defaultProps` is the extracted props left to use as defaults on the
  component.

The React `displayName` is available on the component itself, rather than in
`staticConfig`.

### Classes generated

Tamagui generates helpful CSS classes. For components created with `styled()`
where a `displayName` is set like this:

```tsx
const MyButton = styled(View, {
  displayName: 'MyButton',
  backgroundColor: 'red',
})
```

Tamagui adds the classname `is_MyButton`. This is a useful escape hatch for
attaching CSS to any extra component. All the default Tamagui components have
their display name set.

For components that extend a Text-based component, a further classname is set of
the format `font_[fontFamily]`. So if you do:

```tsx
<Paragraph fontFamily="body" />
```

The classnames `tm-paragraph` and `font_body` will be output to DOM.


## guides/webpack

---
title: Webpack Guide
description: How to set up Tamagui with Webpack
---

<IntroParagraph>
  Configure Webpack to compile Tamagui components and extract their styles.
</IntroParagraph>

First, install [Webpack and webpack-cli](https://webpack.js.org/guides/installation/):

```bash
yarn add -D webpack webpack-cli
```

Then install the Tamagui plugin:

```bash
yarn add -D tamagui-loader
```

### Configuration

Add the plugin to your `webpack.config.js`. If you have a `tamagui.build.ts`
(recommended; see
[compiler install docs](/docs/intro/compiler-install#configuration-with-tamaguibuildts)),
no options are needed:

```js fileName="webpack.config.js"
const { TamaguiPlugin } = require('tamagui-loader')

// reads from tamagui.build.ts automatically
config.plugins.push(new TamaguiPlugin())
```

Or pass options inline:

```js fileName="webpack.config.js"
const { TamaguiPlugin } = require('tamagui-loader')

config.plugins.push(
  new TamaguiPlugin({
    config: './src/tamagui.config.ts',
    components: ['tamagui'],
  })
)
```

Or use a minimal manual setup:

```tsx showMore fileName="webpack.config.js"
// some stuff for react-native
config.plugins.push(
  new webpack.DefinePlugin({
    process: {
      env: {
        __DEV__: process.env.NODE_ENV === 'development' ? 'true' : 'false',
        NODE_ENV: JSON.stringify(process.env.NODE_ENV),
      },
    },
  })
)

config.resolve.alias['react-native$'] = 'react-native-web'

// set up web extensions
compiler.options.resolve.extensions = [
  '.web.tsx',
  '.web.ts',
  '.web.js',
  '.ts',
  '.tsx',
  '.js',
]
```

## Usage

To run the server locally, install [webpack-dev-server](https://github.com/webpack/webpack-dev-server):

```bash
yarn add -D webpack-dev-server
```

Start the server with:

```bash
yarn run webpack serve
```


## guides/design-systems

---
title: Design Systems
description: Put together your own design system.
---

<IntroParagraph>
  Build a shared component package that keeps its types, themes, and compiler
  optimizations in every app that consumes it.
</IntroParagraph>

If you only use `styled()` inside your app, the compiler cannot optimize those
components, because it needs to know about them at build time.

Let's break down how to set this up in more detail.

## Step 1: Create a package

Your design system needs to live in its own npm module, which can be private to
just your app. That way you can later direct the compiler to look for that
package.

Design systems can extend from each other. In fact, `tamagui` extends
`@tamagui/core`, which contains simple base-level components.

So, for example, if you'd like to use the Tamagui `XStack`, `YStack`, `Button`
and `Paragraph` in your design system, you would add `tamagui` to your design
system's package.json.

If you want to build more from scratch, then use `@tamagui/core` and only import
either the `View` or `Text` components. For the purpose of this guide, we'll use
`@tamagui/core`.

Add package.json:

```json
{
  "name": "@ourapp/components",
  "types": "./types/index.d.ts",
  "main": "dist/cjs",
  "module": "dist/esm",
  "module:jsx": "dist/jsx",
  "files": ["types", "src", "dist"],
  "sideEffects": ["*.css"],
  "dependencies": {
    "@tamagui/core": "*"
  },
  "scripts": {
    "build": "tamagui-build",
    "watch": "tamagui-build --watch"
  },
  "devDependencies": {
    "@tamagui/build": "*"
  }
}
```

If using TypeScript, a `tsconfig.json` of your choosing:

```json fileName="tsconfig.json"
{
  "compilerOptions": {
    "types": ["node", "react"],
    "lib": ["dom", "esnext"],
    "baseUrl": "./",
    "outDir": "dist"
  },
  "include": ["./**/*.ts"],
  "exclude": ["node_modules/**/*"]
}
```

There are a few things to note here:

- We're using `@tamagui/build` to build this package, which is a small script
  built around `esbuild` and `typescript` that makes sure you output your
  components _with JSX preserved_.
- We then set `module:jsx`, which then needs to be added to your webpack
  `resolve.mainFields`.
  - The Next.js plugin handles this for you automatically.
- `sideEffects` field is important, otherwise webpack will remove the generated
  CSS in production.

## Step 2: Create your design system

Check the [configuration](/docs/core/configuration) for more detail on this
step.

You'll be creating a `tamagui.config.ts` at the root of your app. It will
contain a full suite of tokens, themes, and fonts exported onto a single named
`config` export.

## Step 3: Define and export components

Now, create and export your components. You can re-export components from
`tamagui` or `@tamagui/core` as well. Let's create a Circle component:

`Circle.tsx`:

```tsx
import { GetProps, type SizeTokens, YStack, styled } from 'tamagui' // or '@tamagui/core' if extending just that

// one function drives both the numeric and the size-token cases
const getCircleSize = styled.dynamic<SizeTokens | number>((size, { tokens }) => {
  const value = tokens.size[size] ?? size
  return { width: value, height: value }
})

export const Circle = styled(YStack, {
  alignItems: 'center',
  justifyContent: 'center',
  borderRadius: 100_000_000,
  overflow: 'hidden',

  variants: {
    size: getCircleSize,
  } as const,
})

export type CircleProps = GetProps<typeof Circle>
```

<Notice theme="yellow">
  v3 removed runtime spread, resolver-name, and type-key variant matching. Brand
  value-to-style functions with `styled.dynamic`; its generic parameter is the
  accepted prop type, and one function handles the whole value domain.
</Notice>

And then export from `index.tsx`:

```tsx
export * from './Circle'
```

## Step 4: Set up your build

Now in your app, add `@ourapp/components` and `tamagui` (since we are extending
it) to your package.json, and update your tamagui build configuration.

### Webpack

In your `webpack.config.js`:

```js
{
  loader: 'tamagui-loader',
  options: {
    config: './tamagui.config.ts',
    components: ['@ourapp/components', 'tamagui'],
  },
}
```

### Next.js

In your `next.config.js`:

```js
export default withPlugins([
  withTamagui({
    config: './tamagui.config.ts',
    components: ['@ourapp/components', 'tamagui'],
  }),
])
```

### React Native

In your `metro.config.js`:

```js
const { getDefaultConfig } = require('@react-native/metro-config')
const { withTamagui } = require('@tamagui/metro-plugin')

module.exports = withTamagui(getDefaultConfig(__dirname), {
  config: './tamagui.config.ts',
  components: ['@ourapp/components', 'tamagui'],
})
```

### Configuration notes

You only need `tamagui` in your `components` array if you extend it, otherwise
no need. You can also extend your own base level module so long as they export
Tamagui `styled` components.

## Step 5: Test it out

In your app, you should now be able to import and use your Circle component.
Using the debug pragma, you can also verify the extraction is working. Make sure
the build settings `logTimings: true` and `disableExtraction: false` are set so
you can see the compiler at work:

Anywhere in your app:

```tsx
import { Circle } from '@ourapp/components'

export default () => <Circle size="10" />
```

When it compiles you should see something like:

```bash
tamagui built app.tsx in 16ms (1 optimized, 1 flattened)
```

To get more information on any extraction, use the `// debug` pragma:

```tsx
// debug
// ^ the above pragma will direct Tamagui to output a lot of information on the extraction
import { Circle } from '@ourapp/components'

export default () => <Circle size="10" />
```

You should see much more log output with details on how it extracted, including
the final CSS and JS.