# Radix Themes Native Documentation

> A React Native port of Radix Themes - An open-source component library optimized for fast development, easy maintenance, and accessibility.

## Installation

```bash
npm install radix-native-ui
```

## Peer Dependencies

- `react` >= 18
- `react-native` >= 0.70
- `expo` >= 48

## Quick Start

```tsx
import { ThemeProvider, Button, Text, Flex, Card, Heading } from 'radix-native-ui';

export default function App() {
  return (
    <ThemeProvider>
      <Card>
        <Flex direction="column" gap={3}>
          <Heading size={4}>Welcome</Heading>
          <Text>Build beautiful mobile apps with Radix Themes Native.</Text>
          <Button onPress={() => console.log('Pressed!')}>Get Started</Button>
        </Flex>
      </Card>
    </ThemeProvider>
  );
}
```

---

## ThemeProvider

Wrap your app with ThemeProvider to enable theming.

### Props

#### Theme Configuration

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `accentColor` | `Color` | `'indigo'` | Primary accent color for the theme |
| `grayColor` | `'mauve' \| 'olive' \| 'sage' \| 'sand' \| 'slate' \| 'gray'` | `'mauve'` | Gray scale color |
| `radius` | `'none' \| 'small' \| 'medium' \| 'large' \| 'full'` | `'medium'` | Border radius scale |
| `scaling` | `number` | `1` | Overall scaling factor (1 = 100%) |
| `panelBackground` | `'solid' \| 'translucent'` | `'solid'` | Panel background style |

#### Runtime Behavior

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `appearance` | `'light' \| 'dark' \| 'inherit'` | `'inherit'` | Color scheme preference. Use 'inherit' to follow device/parent settings |
| `forcedMode` | `'light' \| 'dark'` | `undefined` | Force a specific mode, overriding device and parent settings |
| `hasBackground` | `boolean` | `true` | Whether to apply background color |
| `onModeChange` | `(mode: 'light' \| 'dark') => void` | `undefined` | Callback when theme mode changes |

#### Legacy Support

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `themeOptions` | `Partial<Theme>` | `undefined` | Theme options object (legacy - use flat props instead). Flat props take precedence |

#### Toast Configuration

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `toastConfig` | `ToastConfig` | `undefined` | Configuration options for toast notifications |

### Available Accent Colors

`amber`, `blue`, `bronze`, `brown`, `crimson`, `cyan`, `gold`, `grass`, `green`, `indigo`, `iris`, `jade`, `lime`, `mint`, `orange`, `pink`, `plum`, `purple`, `red`, `ruby`, `sky`, `teal`, `tomato`, `violet`, `yellow`

### Gray Scale Variants

`gray`, `mauve`, `olive`, `sage`, `sand`, `slate`

---

## Hooks

### useTheme

Returns the current theme object.

```tsx
const theme = useTheme();
// Returns: Theme object with colors, typography, spacing, etc.
```

### useThemeMode

Returns the current theme mode.

```tsx
const mode = useThemeMode();
// Returns: 'light' | 'dark'
```

### useThemeActions

Returns theme actions and current mode.

```tsx
const { setMode, toggleMode, mode } = useThemeActions();
// setMode: (mode: ThemeMode) => void
// toggleMode: () => void
// mode: ThemeMode
```

---

## Components

### Layout Components

#### Box

Primitive container with styling props.

```tsx
<Box
  padding={4}
  backgroundColor="gray.2"
  borderRadius={2}
>
  Content
</Box>
```

#### Flex

Flexbox layout component.

```tsx
<Flex
  direction="row"
  align="center"
  justify="between"
  gap={3}
>
  <Text>Left</Text>
  <Text>Right</Text>
</Flex>
```

**Props:**
- `direction`: `'row' | 'column' | 'row-reverse' | 'column-reverse'`
- `align`: `'start' | 'center' | 'end' | 'stretch' | 'baseline'`
- `justify`: `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`
- `wrap`: `'wrap' | 'nowrap' | 'wrap-reverse'`
- `gap`: `number` (uses theme scale)

#### Grid

Grid layout component.

```tsx
<Grid columns={3} gap={4}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
  <Box>Item 3</Box>
</Grid>
```

#### Container

Responsive container with max-width.

```tsx
<Container size={3} responsive>
  Content
</Container>
```

#### Inset

Padding component with overflow clipping.

```tsx
<Inset side="all" p={4} clip="overflow">
  <Image source={{ uri: '...' }} />
</Inset>
```

---

### Typography Components

#### Text

```tsx
<Text size={3} weight="medium" color="blue">
  Text content
</Text>
```

**Props:**
- `size`: `1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9` (default: 3)
- `weight`: `'light' | 'regular' | 'medium' | 'bold'`
- `align`: `'left' | 'center' | 'right'`
- `color`: `string`
- `truncate`: `boolean`

#### Heading

```tsx
<Heading size={4} weight="bold">
  Heading
</Heading>
```

**Props:**
- `size`: `1 | 2 | 3 | 4 | 5` (default: 3)
- `weight`: `'light' | 'regular' | 'medium' | 'bold'`

#### Strong, Em, Code, Kbd

```tsx
<Strong>Bold text</Strong>
<Em>Italic text</Em>
<Code>const x = 42;</Code>
<Kbd>Cmd + C</Kbd>
```

---

### Form Components

#### Button

```tsx
<Button
  variant="classic"
  size={2}
  color="blue"
  onPress={handlePress}
>
  Click me
</Button>
```

**Props:**
- `variant`: `'classic' | 'solid' | 'soft' | 'outline' | 'ghost'` (default: 'classic')
- `size`: `1 | 2 | 3` (default: 2)
- `color`: `string` (accent color name)
- `disabled`: `boolean`
- `loading`: `boolean`
- `highContrast`: `boolean`
- `onPress`: `(event: GestureResponderEvent) => void`
- `width`: `number | string`

#### TextField

```tsx
<TextField
  value={value}
  onChangeText={setValue}
  placeholder="Enter text"
  variant="surface"
  size={2}
/>
```

**Props:**
- `value`: `string`
- `onChangeText`: `(text: string) => void`
- `placeholder`: `string`
- `variant`: `'classic' | 'surface' | 'soft'`
- `size`: `1 | 2 | 3`
- `disabled`: `boolean`
- `error`: `string`
- `secureTextEntry`: `boolean`

#### Checkbox

```tsx
<Checkbox
  checked={checked}
  onCheckedChange={setChecked}
/>
```

#### Switch

```tsx
<Switch
  checked={enabled}
  onCheckedChange={setEnabled}
  size="medium"
/>
```

#### RadioGroup

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <Radio value="option1">Option 1</Radio>
  <Radio value="option2">Option 2</Radio>
</RadioGroup>
```

#### Select

```tsx
<Select
  value={selected}
  onValueChange={setSelected}
  items={[
    { label: 'Option A', value: 'a' },
    { label: 'Option B', value: 'b' },
  ]}
  placeholder="Select an option"
/>
```

#### Slider

```tsx
<Slider
  value={[20, 80]}
  onValueChange={setRange}
  min={0}
  max={100}
  step={1}
/>
```

---

### Data Display Components

#### Avatar

```tsx
<Avatar
  src="https://example.com/avatar.jpg"
  alt="User avatar"
  fallback="JD"
  size={4}
/>
```

#### Badge

```tsx
<Badge color="green" variant="soft">
  Active
</Badge>
```

**Props:**
- `variant`: `'solid' | 'soft' | 'outline'`
- `size`: `1 | 2 | 3`
- `color`: `string`
- `highContrast`: `boolean`

#### Card

```tsx
<Card variant="elevated" size={2}>
  <Text>Card content</Text>
</Card>
```

**Props:**
- `variant`: `'elevated' | 'outlined' | 'flat'`
- `size`: `1 | 2 | 3`

#### Progress

```tsx
<Progress value={75} max={100} size="medium" />
```

#### Spinner

```tsx
<Spinner size="medium" color="blue" />
```

---

### Overlay Components

#### Dialog

```tsx
<Dialog.Root open={open} onOpenChange={setOpen}>
  <Dialog.Trigger>
    <Button>Open Dialog</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Dialog Title</Dialog.Title>
      <Dialog.Description>Dialog description</Dialog.Description>
      <Dialog.Close>
        <Button>Close</Button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>
```

#### AlertDialog

```tsx
<AlertDialog.Root>
  <AlertDialog.Trigger>
    <Button>Delete</Button>
  </AlertDialog.Trigger>
  <AlertDialog.Portal>
    <AlertDialog.Overlay />
    <AlertDialog.Content>
      <AlertDialog.Title>Confirm Delete</AlertDialog.Title>
      <AlertDialog.Description>
        Are you sure you want to delete this item?
      </AlertDialog.Description>
      <Flex gap={2}>
        <AlertDialog.Cancel>
          <Button variant="soft">Cancel</Button>
        </AlertDialog.Cancel>
        <AlertDialog.Action>
          <Button color="red">Delete</Button>
        </AlertDialog.Action>
      </Flex>
    </AlertDialog.Content>
  </AlertDialog.Portal>
</AlertDialog.Root>
```

#### Popover

```tsx
<Popover.Root>
  <Popover.Trigger>
    <Button>Open Popover</Button>
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Content>
      <Text>Popover content</Text>
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>
```

#### Tooltip

```tsx
<Tooltip.Root>
  <Tooltip.Trigger>
    <IconButton icon={<InfoIcon />} />
  </Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Content>
      <Text>Tooltip text</Text>
    </Tooltip.Content>
  </Tooltip.Portal>
</Tooltip.Root>
```

#### DropdownMenu

```tsx
<DropdownMenu.Root>
  <DropdownMenu.Trigger>
    <Button>Menu</Button>
  </DropdownMenu.Trigger>
  <DropdownMenu.Portal>
    <DropdownMenu.Content>
      <DropdownMenu.Item onSelect={handleEdit}>Edit</DropdownMenu.Item>
      <DropdownMenu.Item onSelect={handleCopy}>Copy</DropdownMenu.Item>
      <DropdownMenu.Separator />
      <DropdownMenu.Item onSelect={handleDelete}>Delete</DropdownMenu.Item>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>
```

#### Toast

```tsx
// Using the toast hook
import { useToast } from 'radix-native-ui';

function MyComponent() {
  const { toast } = useToast();

  return (
    <Button onPress={() => toast({ title: 'Success!', description: 'Action completed.' })}>
      Show Toast
    </Button>
  );
}
```

---

### Disclosure Components

#### Accordion

```tsx
<Accordion.Root type="single" collapsible>
  <Accordion.Item value="item-1">
    <Accordion.Header>
      <Accordion.Trigger>First Item</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Content>Content for first item</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="item-2">
    <Accordion.Header>
      <Accordion.Trigger>Second Item</Accordion.Trigger>
    </Accordion.Header>
    <Accordion.Content>Content for second item</Accordion.Content>
  </Accordion.Item>
</Accordion.Root>
```

**Accordion.Root Props:**
- `type`: `'single' | 'multiple'` (required)
- `value`: `string | string[]` (controlled)
- `defaultValue`: `string | string[]`
- `onValueChange`: `(value: string | string[]) => void`
- `collapsible`: `boolean` (for single type)
- `disabled`: `boolean`
- `size`: `'1' | '2' | '3'`

---

### Utility Components

#### AspectRatio

```tsx
<AspectRatio ratio={16 / 9}>
  <Image source={{ uri: '...' }} />
</AspectRatio>
```

#### ScrollArea

```tsx
<ScrollArea>
  <Flex direction="column" gap={2}>
    {items.map(item => (
      <Text key={item.id}>{item.name}</Text>
    ))}
  </Flex>
</ScrollArea>
```

#### VisuallyHidden

```tsx
<VisuallyHidden>
  <Text>Screen reader only text</Text>
</VisuallyHidden>
```

---

## Color Scale Structure

Each color has a 12-step scale:

| Step | Purpose |
|------|---------|
| 1 | App background |
| 2 | Subtle background |
| 3 | UI element background |
| 4 | Hovered UI element background |
| 5 | Active / Selected UI element background |
| 6 | Subtle borders |
| 7 | UI element border, focus ring |
| 8 | Hovered UI element border |
| 9 | Solid backgrounds |
| 10 | Hovered solid backgrounds |
| 11 | Low-contrast text |
| 12 | High-contrast text |

---

## Spacing Scale

| Step | Value |
|------|-------|
| 0 | 0px |
| 1 | 4px |
| 2 | 8px |
| 3 | 12px |
| 4 | 16px |
| 5 | 20px |
| 6 | 24px |
| 7 | 32px |
| 8 | 40px |
| 9 | 48px |
| 10 | 64px |
| 11 | 80px |
| 12 | 96px |
| 13 | 128px |

---

## Typography Scale

| Size | Font Size | Line Height |
|------|-----------|-------------|
| 1 | 11px | 16px |
| 2 | 12px | 18px |
| 3 | 14px | 20px |
| 4 | 16px | 24px |
| 5 | 18px | 26px |
| 6 | 20px | 28px |
| 7 | 24px | 32px |
| 8 | 30px | 36px |
| 9 | 36px | 40px |

---

## Migration from Web Radix Themes

| Web | React Native |
|-----|--------------|
| `onClick` | `onPress` |
| `onChange` | `onChangeText` / `onValueChange` |
| CSS properties | StyleSheet props |
| CSS variables | Theme context values |

```tsx
// Web
<Box css={{ p: '$4', bg: '$gray2' }}>
  <Button onClick={handleClick}>Click</Button>
</Box>

// React Native
<Box padding={4} backgroundColor="gray.2">
  <Button onPress={handlePress}>Click</Button>
</Box>
```

---

## Links

- **GitHub**: https://github.com/Copy-Labs/radix-ui-native-kilo
- **npm**: https://www.npmjs.com/package/radix-native-ui
- **Original Radix Themes**: https://www.radix-ui.com/themes