UI Components

Build beautiful interfaces with gluestack-ui v3 and NativeWind.

gluestack-ui v3

AppLighter uses gluestack-ui v3 for UI components. Unlike traditional component libraries, gluestack-ui is a copy-paste component system - you own the code and can customize everything.

Why gluestack-ui?

| Feature | Benefit | |---------|---------| | Copy-paste | No dependency lock-in, full control over code | | NativeWind | Tailwind CSS styling with className | | Accessible | ARIA-compliant, keyboard navigation | | Dark mode | Built-in light/dark theme support | | Cross-platform | Works on iOS, Android, and Web |

Available Components

AppLighter includes these pre-configured gluestack-ui components:

Layout

Box - Flexible container
VStack / HStack - Vertical/horizontal stacks
Center - Centered container
Divider - Visual separator

Forms

Button - Action buttons with variants
Input - Text input fields
Textarea - Multi-line text input
Checkbox - Selection checkboxes
Switch - Toggle switches
Select - Dropdown selects

Feedback

Alert - Status messages
Toast - Notification popups
Spinner - Loading indicators
Progress - Progress bars

Overlay

Modal - Dialog windows
Actionsheet - Bottom sheets
Menu - Dropdown menus
Tooltip - Hover tooltips

Data Display

Avatar - User avatars
Badge - Status badges
Card - Content cards
Image - Optimized images

Usage Example

import { Box, VStack, Text, Button } from '@/components/ui'

export function WelcomeCard() {
  return (
    <Box className="bg-card rounded-2xl p-6 border border-border">
      <VStack space="md">
        <Text className="text-2xl font-bold text-foreground">
          Welcome to AppLighter
        </Text>
        <Text className="text-muted-foreground">
          Build production-ready mobile apps faster.
        </Text>
        <Button action="primary" size="lg">
          <ButtonText>Get Started</ButtonText>
        </Button>
      </VStack>
    </Box>
  )
}

Component Structure

Components are located in components/ui/:

components/
├── ui/
│   ├── box/
│   │   └── index.tsx
│   ├── button/
│   │   └── index.tsx
│   ├── input/
│   │   └── index.tsx
│   ├── text/
│   │   └── index.tsx
│   └── ...
└── index.ts          # Barrel exports

Styling with NativeWind

All components use NativeWind for Tailwind CSS styling:

// Using className prop
<Box className="bg-primary rounded-xl p-4 shadow-lg">
  <Text className="text-primary-foreground font-semibold">
    Styled with Tailwind
  </Text>
</Box>

// Using theme variables
<Button className="bg-destructive hover:bg-destructive/90">
  <ButtonText>Delete</ButtonText>
</Button>

Theme Variables

Use semantic theme variables for consistent styling:

| Variable | Light | Dark | Usage | |----------|-------|------|-------| | background | white | zinc-950 | Page background | | foreground | zinc-950 | zinc-50 | Primary text | | card | white | zinc-900 | Card backgrounds | | primary | violet-600 | violet-500 | Primary actions | | muted | zinc-100 | zinc-800 | Secondary elements | | border | zinc-200 | zinc-800 | Borders |

Customizing Components

Since components are copy-pasted, you can modify them directly:

// components/ui/button/index.tsx
import { Pressable, Text } from 'react-native'
import { tv } from 'tailwind-variants'

const buttonVariants = tv({
  base: 'flex-row items-center justify-center rounded-xl',
  variants: {
    action: {
      primary: 'bg-primary',
      secondary: 'bg-secondary',
      // Add your own variant
      brand: 'bg-gradient-to-r from-violet-600 to-indigo-600',
    },
    size: {
      sm: 'px-3 py-2',
      md: 'px-4 py-3',
      lg: 'px-6 py-4',
    },
  },
  defaultVariants: {
    action: 'primary',
    size: 'md',
  },
})

Adding New Components

To add a new gluestack-ui component:

Visit gluestack.io/ui/docs
Find the component you need
Copy the component code
Paste into components/ui/[component-name]/index.tsx
Export from components/index.ts

# Example: Adding Accordion component
mkdir -p components/ui/accordion
# Copy code from gluestack docs
# Add export to components/index.ts

Dark Mode

Components automatically adapt to dark mode:

import { useColorScheme } from 'react-native'

function ThemedComponent() {
  const colorScheme = useColorScheme()

  return (
    <Box className="bg-card">
      {/* Automatically uses dark theme colors */}
      <Text className="text-foreground">
        Current theme: {colorScheme}
      </Text>
    </Box>
  )
}