Installation

1. Install packages

Install the core native package along with the shared tokens and icon packages.

pnpm add @tac-ui/native @tac-ui/tokens @tac-ui/icon-native

Icons are provided by @tac-ui/icon-native, a React Native SVG port of the icon set used in @tac-ui/web. Pass any icon as a child or prop where components accept React.ReactNode.

2. Peer dependencies

Tac UI Native requires the following peer dependencies. Most are already present in standard React Native / Expo projects.

If you are using Expo, install react-native-svg via:

npx expo install react-native-svg react-native-reanimated

Then follow the react-native-reanimated setup guide to add the Babel plugin.

3. Add the Provider

Wrap your application root with TacNativeProvider to enable theming. It injects the active theme tokens into a React context consumed by all child components.

import { TacNativeProvider } from '@tac-ui/native';

export default function App() {
  return (
    <TacNativeProvider defaultMode="system">
      {/* your screens here */}
    </TacNativeProvider>
  );
}

The defaultMode prop accepts "light", "dark", or "system". When set to "system", the provider follows the device color scheme automatically via useColorScheme.

4. Use Components

Import components directly from @tac-ui/native. All components accept a style prop for local overrides and forward refs where applicable.

import { View } from 'react-native';
import { Button, Input, Card } from '@tac-ui/native';

export default function LoginScreen() {
  return (
    <View style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
      <Card>
        <Input label="Email" placeholder="[email protected]" />
        <Input label="Password" secureTextEntry />
        <Button variant="primary" onPress={() => {}}>
          Sign In
        </Button>
      </Card>
    </View>
  );
}

5. Customize Design Tokens

Pass a theme prop to TacNativeProvider to override any token. The theme object is deeply merged with the default tokens, so you only need to specify the values you want to change. See the Customization guide for the full token reference (token names are shared across web and native).

import { TacNativeProvider } from '@tac-ui/native';

const brandTheme = {
  light: {
    primary: '#96784A',       // warm amber
    primaryHover: '#84693C',
    radiusMd: 12,             // rounder corners (px)
  },
  dark: {
    primary: '#B89462',
    primaryHover: '#96784A',
  },
};

export default function App() {
  return (
    <TacNativeProvider defaultMode="system" theme={brandTheme}>
      {/* your screens */}
    </TacNativeProvider>
  );
}

Project Structure

The monorepo packages consumed by native projects: