@vantara-native/ui

React Native + TypeScript UI component library for the Vantara mobile app ecosystem (Expo, NativeWind). Split out of @vantara-ui/ui (the web/DOM library) so mobile components have their own dedicated tokens, build pipeline, and Storybook — see Guidance/TOKENS.md for why.

Table of Contents

1. Installation
2. Quick Start
3. NativeWind / Tailwind Integration
4. Component Catalog
5. TypeScript Support
6. Troubleshooting

Installation

Prerequisites

• Node.js 20+
• React 18+ or 19+
• React Native >=0.72.0 (Expo SDK 51+ recommended)
• NativeWind 4.x
• lucide-react-native + react-native-svg (required for AppIcon)

Install

npm install @vantara-native/ui react-native nativewind
npm install lucide-react-native react-native-svg   # required for AppIcon

Verify

npm list @vantara-native/ui
# └── @vantara-native/[email protected]

Quick Start

1. Extend your app's Tailwind/NativeWind config

// tailwind.config.js
const nativeConfig = require('@vantara-native/ui/tailwind');

module.exports = {
  presets: [nativeConfig],
  content: [
    './App.tsx',
    './src/**/*.{ts,tsx}',
    './node_modules/@vantara-native/ui/dist/**/*.{js,mjs}',
  ],
};

Make sure NativeWind's babel plugin is configured per NativeWind's own setup guide — @vantara-native/ui assumes NativeWind is already wired into your Metro/Babel config.

2. Import components

import { Heart } from 'lucide-react-native';
import { AppButton, AppText, AppIcon } from '@vantara-native/ui';

export function FavoriteLabel() {
  return (
    <>
      <AppIcon icon={Heart} size="md" color="#D97941" />
      <AppText variant="label">Favorites</AppText>
    </>
  );
}

export function PayBillButton({ onPress }: { onPress: () => void }) {
  return (
    <AppButton variant="primary" onPress={onPress}>
      Pay Bill
    </AppButton>
  );
}

3. Import tokens directly (optional)

import { primitiveColors, spacing } from '@vantara-native/ui/tokens';

NativeWind / Tailwind Integration

Every component accepts a className prop and is styled entirely through NativeWind utility classes bound to this package's design tokens (see Guidance/TOKENS.md). There is no shipped CSS — styles resolve at build time via your app's own Metro/NativeWind pipeline, driven by the ./tailwind preset above.

Component Catalog

Atoms

| Component | Purpose | |-----------|---------| | AppButton | Primary/secondary pressable action | | AppText | Body, label, helper, and heading typography (xs–xl sizes) | | AppIcon | Wrapper over lucide-react-native icons | | AppStatusBadge | Compact status pill |

Molecules

| Component | Purpose | |-----------|---------| | AppAlertBanner | Inline alert/notice banner (info/warning/danger tones) | | AppShortcutTile | Dashboard shortcut tile | | AppListRow | List row with leading icon, label, and trailing content | | AppPaymentMethodCard | Saved payment method summary card | | AppBillSummaryCard | Bill breakdown + total summary card |

Organisms

| Component | Purpose | |-----------|---------| | AppGreetingHeader | Home screen greeting header |

Full usage examples and variants: run npm run storybook (see Guidance/STORYBOOK.md).

TypeScript Support

Full TypeScript support out of the box — every component ships its own prop types (AppButtonProps, AppTextVariant, etc.), importable alongside the component:

import type { AppButtonProps, AppButtonVariant } from '@vantara-native/ui';

Troubleshooting

"Cannot find module 'react-native'" (or similar peer errors) after install — react-native, nativewind, lucide-react-native, and react-native-svg are peer dependencies, not bundled. Install them directly in your app.

NativeWind classes have no effect — confirm your app's tailwind.config.js extends @vantara-native/ui/tailwind as a preset (not just added to content), and that NativeWind's Babel plugin is active.

Storybook / dev environment issues — see Guidance/STORYBOOK.md.

Publishing a new version — see Guidance/PUBLISHING.md.

Related docs

| Topic | Document | |-------|----------| | Design tokens | Guidance/TOKENS.md | | Storybook workflow | Guidance/STORYBOOK.md | | Publishing to npm | Guidance/PUBLISHING.md |