🌊 FlowUI (expo-flow-ui)

Beautiful, accessible, animated Expo & React Native UI components — copied directly into your project.

FlowUI is a shadcn/ui equivalent for Expo & React Native. Instead of installing a rigid npm package with locked styling and version conflicts, FlowUI copies the TypeScript source code directly into your project. You own 100% of the code and can customize every single component to match your app's exact design needs.

🚀 Why FlowUI?

• 📱 Native-First Primitives: Built exclusively with react-native components (View, Text, Pressable, Modal, TextInput). Zero DOM or HTML overhead.
• ⚡ Reanimated 3 Motion: Smooth 60FPS spring physics, fluid micro-interactions, and built-in haptic touch feedback.
• 🎨 Light & Dark Mode: Dynamic theme system with useColor() and useFlowTheme() hooks that automatically react to system color scheme changes.
• 🛠️ Full Source Ownership: All components live inside your @/components/ui/ folder. No third-party package dependencies breaking on Expo SDK updates.
• 🔒 TypeScript Native: 100% written in strict TypeScript with autocomplete for variants, sizes, and props.

⚡ Quick Start

1. Initialize FlowUI in your Expo Project

Run the initialization command in your project root:

npx expo-flow-ui init

This automatically sets up your project structure:

your-project/
├── theme/
│   ├── colors.ts      # Light & Dark color tokens
│   └── globals.ts     # Component heights, font sizes, border radii, spacing
├── hooks/
│   ├── useColor.ts     # Theme color resolution hook
│   └── useFlowTheme.ts # Full palette & scheme access hook
└── components/ui/
    ├── text.tsx       # Core typography component
    ├── view.tsx       # Core container component
    └── button.tsx     # Base button component

2. Add Components as You Need Them

Add individual components into your codebase:

# Add specific components
npx expo-flow-ui add button
npx expo-flow-ui add card
npx expo-flow-ui add input
npx expo-flow-ui add modal
npx expo-flow-ui add toast

Or run without arguments for an interactive CLI selector:

npx expo-flow-ui add

3. List All Available Components

npx expo-flow-ui list

🧩 Usage Examples

Button & Card

import React from 'react';
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Text } from '@/components/ui/text';

export function ExampleCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome to FlowUI</CardTitle>
        <CardDescription>Copy-paste React Native components for Expo.</CardDescription>
      </CardHeader>
      <CardContent>
        <Text variant="body">
          FlowUI components render natively with Reanimated spring physics.
        </Text>
      </CardContent>
      <CardFooter>
        <Button variant="outline">Cancel</Button>
        <Button variant="default" onPress={() => console.log('Saved!')}>
          Save Changes
        </Button>
      </CardFooter>
    </Card>
  );
}

Toast Notification System

import React from 'react';
import { ToastProvider, useToast } from '@/components/ui/toast';
import { Button } from '@/components/ui/button';

function NotificationDemo() {
  const toast = useToast();

  return (
    <Button
      variant="success"
      onPress={() => toast.success('Account Created!', 'Welcome aboard.')}
    >
      Show Success Toast
    </Button>
  );
}

export default function App() {
  return (
    <ToastProvider>
      <NotificationDemo />
    </ToastProvider>
  );
}

📦 Component Overview (15)

| Component | Key Sub-components / Variants | Description | |---|---|---| | button | default, destructive, success, outline, secondary, ghost, link | Spring-animated button with 4 sizes, haptics & loading state | | text | heading, title, subtitle, body, caption, label, link, muted | Themed typography component with automatic headers | | view | transparent prop | Theme-aware container view | | card | CardHeader, CardTitle, CardDescription, CardContent, CardFooter | Elevated container card for grouped content | | badge | default, secondary, destructive, success, outline, warning | Status pill descriptor | | input | filled, outline, type="textarea", type="password" | Form input & Textarea with label, error, and password toggle | | spinner | default, ring, dots, pulse | Animated loading indicator with speed options | | separator | horizontal, vertical | Divider line matching theme border color | | avatar | AvatarImage, AvatarFallback, online={true} | Circular user avatar with initials fallback & status dot | | switch | Reanimated position & color spring | Animated toggle switch with label & error text | | checkbox | indeterminate={true}, scale physics | Checkbox supporting indeterminate state & labels | | modal | ModalHeader, ModalContent, ModalFooter | Full-screen or dialog modal with backdrop blur/overlay | | tabs | TabsList, TabsTrigger, TabsContent | Compound tab navigation with animated selection | | accordion | AccordionItem, AccordionTrigger, AccordionContent | Collapsible section with rotating chevron animation | | toast | ToastProvider, useToast(), toast.success(), toast.error() | Global auto-dismissing toast banner system |

🎨 Theme Customization

FlowUI includes a clean @/theme/colors.ts file that you can customize for your brand colors:

// @/theme/colors.ts
export const lightColors = {
  background: '#ffffff',
  foreground: '#09090b',
  primary: '#3b82f6',
  primaryForeground: '#ffffff',
  card: '#ffffff',
  border: '#e4e4e7',
  // Add your custom brand colors here!
};

export const darkColors = {
  background: '#09090b',
  foreground: '#fafafa',
  primary: '#3b82f6',
  primaryForeground: '#ffffff',
  card: '#18181b',
  border: '#27272a',
};

Access colors anywhere in your app:

import { useColor } from '@/hooks/useColor';

const primary = useColor('primary');
const background = useColor('background');

⚙️ Peer Dependencies

For components with animations and icons, make sure your Expo app has these standard packages installed:

npx expo install react-native-reanimated

📜 License

MIT © FlowUI — Free for personal and commercial use.