Gluestack UI V5:components

Gluestack UI v5 — Component Patterns

This sub-skill focuses on component usage, compound component patterns, icon handling, and provider setup for gluestack-ui v5 (NativeWind v5 / UniWind).

Rule 1: Gluestack Components Over React Native Primitives

Always use Gluestack components instead of direct React Native imports:

Correct Pattern

import { Box } from "@/components/ui/box";
import { Text } from "@/components/ui/text";
import { Pressable } from "@/components/ui/pressable";

const Component = () => (
  <Box className="p-4">
    <Text className="text-foreground">Hello</Text>
    <Pressable
      <Text>Press Me</Text>
    </Pressable>
  </Box>
);

Incorrect Pattern

import { View, Text, TouchableOpacity } from "react-native";

const Component = () => (
  <View style={{ padding: 16 }}>
    <Text style={{ color: "#333" }}>Hello</Text>
    <TouchableOpacity
      <Text>Press Me</Text>
    </TouchableOpacity>
  </View>
);

Exceptions

• Platform-specific code where RN primitives are explicitly required
• Deep integration with native modules
• Performance-critical paths where wrapper overhead matters (rare, must document)

Rule 2: Use Component Props Over className Utilities

Always prefer component props over className utilities when a component provides built-in props. This ensures type safety, better maintainability, and consistent styling.

Component Props vs className

Many Gluestack components provide props that map to common styling needs. Use these props instead of className utilities:

Correct Pattern: Using Component Props

// ✅ CORRECT: Using space prop instead of gap className
<VStack space="lg">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</VStack>

// ✅ CORRECT: Using Button variant and size props
<Button variant="outline" size="lg">
  <ButtonText>Click Me</ButtonText>
</Button>

// ✅ CORRECT: Using Heading size prop
<Heading size="2xl" bold>
  Title
</Heading>

// ✅ CORRECT: Using Text size and bold props
<Text size="sm" bold>
  Important text
</Text>

// ✅ CORRECT: Using HStack space prop
<HStack space="md" className="items-center">
  <Text>Label</Text>
  <Button size="sm">
    <ButtonText>Action</ButtonText>
  </Button>
</HStack>

Incorrect Pattern: Using className Instead of Props

// ❌ INCORRECT: Using gap className instead of space prop
<VStack className="gap-4">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</VStack>

// ❌ INCORRECT: Using className for button styling instead of variant/size props
<Button className="bg-primary px-8 py-2">
  <ButtonText>Click Me</ButtonText>
</Button>

// ❌ INCORRECT: Using text size className instead of size prop
<Heading className="text-2xl font-bold">
  Title
</Heading>

// ❌ INCORRECT: Using className for spacing instead of space prop
<HStack className="gap-2 items-center">
  <Text>Label</Text>
  <Button size="sm">
    <ButtonText>Action</ButtonText>
  </Button>
</HStack>

When to Use className vs Props

Use Props When:

• Component provides a built-in prop for the styling (size, variant, space, etc.)
• You want type safety and autocomplete
• The styling is part of the component's design system

Use className When:

• Component doesn't provide a prop for the specific styling needed
• You need custom styling not covered by props
• Combining multiple utilities that don't have prop equivalents
• Layout utilities (flex, items-center, justify-between, etc.)

Combining Props and className

You can combine props with className for additional styling:

// ✅ CORRECT: Using space prop + className for additional styling
<VStack space="lg" className="p-4 bg-card rounded-lg">
  <Heading size="xl">Title</Heading>
  <Text size="sm">Description</Text>
</VStack>

// ✅ CORRECT: Using variant prop + className for custom adjustments
<Button variant="outline" size="lg" className="w-full">
  <ButtonText>Full Width Button</ButtonText>
</Button>

Space Prop Mapping

The space prop on VStack/HStack maps to standard spacing:

Benefits of Using Props

1. Type Safety - TypeScript will catch invalid prop values
2. Autocomplete - IDE provides suggestions for valid values
3. Consistency - Enforces design system values
4. Maintainability - Easier to refactor and update
5. Documentation - Props are self-documenting
6. Performance - Props are optimized by the component system

Rule 6: Gluestack Compound Component Pattern

Use Gluestack's composable compound component pattern for complex components. This is REQUIRED for proper rendering, styling, and functionality. Compound components provide proper context sharing, styling inheritance, and accessibility.

Critical Rule: InputIcon MUST Be Wrapped in InputSlot

ALL InputIcon components MUST be wrapped in InputSlot, regardless of whether they're on the left or right side of the input. This is required for proper styling, positioning, and interaction handling.

Input Component Patterns

Correct: InputIcon Wrapped in InputSlot (Required)

// ✅ CORRECT: Left icon wrapped in InputSlot
<Input>
  <InputSlot>
    <InputIcon as={MailIcon} className="text-muted-foreground" />
  </InputSlot>
  <InputField placeholder="Enter email" />
</Input>

// ✅ CORRECT: Right icon (interactive) wrapped in InputSlot
<Input>
  <InputField placeholder="Enter password" secureTextEntry={!showPassword} />
  <InputSlot => setShowPassword(!showPassword)}>
    <InputIcon as={showPassword ? EyeOffIcon : EyeIcon} className="text-muted-foreground" />
  </InputSlot>
</Input>

// ✅ CORRECT: Both left and right icons wrapped in InputSlot
<Input>
  <InputSlot>
    <InputIcon as={SearchIcon} className="text-muted-foreground" />
  </InputSlot>
  <InputField placeholder="Search..." />
  <InputSlot
    <InputIcon as={XIcon} className="text-muted-foreground" />
  </InputSlot>
</Input>

Incorrect: InputIcon Used Directly (Will Break)

// ❌ INCORRECT: InputIcon used directly without InputSlot
<Input>
  <InputIcon as={MailIcon} />  {/* ❌ Missing InputSlot wrapper */}
  <InputField placeholder="Enter email" />
</Input>

// ❌ INCORRECT: InputIcon outside Input structure
<InputIcon as={MailIcon} />  {/* ❌ Must be inside Input > InputSlot */}
<Input>
  <InputField placeholder="Enter email" />
</Input>

Button Component Patterns

Correct Pattern

// ✅ CORRECT: Button with text and icon
<Button variant="default" size="md">
  <ButtonText>Click Me</ButtonText>
  <ButtonIcon as={ChevronRightIcon} />
</Button>

// ✅ CORRECT: Button with only text
<Button>
  <ButtonText>Submit</ButtonText>
</Button>

// ✅ CORRECT: Button with only icon
<Button size="icon">
  <ButtonIcon as={SearchIcon} />
</Button>

// ✅ CORRECT: Button with loading state
<Button isDisabled={isLoading}>
  {isLoading ? (
    <>
      <ButtonSpinner />
      <ButtonText>Loading...</ButtonText>
    </>
  ) : (
    <ButtonText>Submit</ButtonText>
  )}
</Button>

Incorrect Pattern

// ❌ INCORRECT: Text not wrapped in ButtonText
<Button>Click Me</Button>

// ❌ INCORRECT: Direct text children
<Button>
  Click Me  {/* ❌ Must use ButtonText */}
</Button>

// ❌ INCORRECT: Icon not wrapped in ButtonIcon
<Button>
  <ButtonText>Next</ButtonText>
  <ChevronRightIcon />  {/* ❌ Must use ButtonIcon */}
</Button>

FormControl Component Patterns

Correct Pattern

// ✅ CORRECT: Complete FormControl with label, input, and error
<FormControl isInvalid={!!errors.email}>
  <FormControlLabel>
    <FormControlLabelText>Email Address</FormControlLabelText>
  </FormControlLabel>
  <Input>
    <InputSlot>
      <InputIcon as={MailIcon} />
    </InputSlot>
    <InputField
      placeholder="Enter email"
      value={email}
     
    />
  </Input>
  {errors.email && (
    <FormControlError>
      <FormControlErrorIcon as={AlertCircleIcon} />
      <FormControlErrorText>{errors.email}</FormControlErrorText>
    </FormControlError>
  )}
  <FormControlHelper>
    <FormControlHelperText>We'll never share your email</FormControlHelperText>
  </FormControlHelper>
</FormControl>

Incorrect Pattern

// ❌ INCORRECT: Missing sub-components
<FormControl>
  <Text>Email</Text>  {/* ❌ Must use FormControlLabel > FormControlLabelText */}
  <InputField />  {/* ❌ Must wrap in Input */}
</FormControl>

// ❌ INCORRECT: Error text not wrapped
<FormControl isInvalid={hasError}>
  <Input>
    <InputField />
  </Input>
  {hasError && <Text>Error message</Text>}  {/* ❌ Must use FormControlError > FormControlErrorText */}
</FormControl>

Card Component Patterns

Correct Pattern

// ✅ CORRECT: Complete Card structure
<Card>
  <CardHeader>
    <Heading size="lg">Card Title</Heading>
    <Text className="text-muted-foreground">Subtitle</Text>
  </CardHeader>
  <CardBody>
    <Text>Card content goes here</Text>
  </CardBody>
  <CardFooter>
    <Button variant="outline">
      <ButtonText>Cancel</ButtonText>
    </Button>
    <Button>
      <ButtonText>Confirm</ButtonText>
    </Button>
  </CardFooter>
</Card>

Incorrect Pattern

// ❌ INCORRECT: Direct children without sub-components
<Card>
  <Heading>Title</Heading>  {/* ❌ Must use CardHeader */}
  <Text>Content</Text>  {/* ❌ Must use CardBody */}
</Card>

Checkbox Component Patterns

Correct Pattern

// ✅ CORRECT: Checkbox with label
<Checkbox
  value="terms"
  isChecked={accepted}
  => setAccepted(isChecked)}
>
  <CheckboxIndicator>
    <CheckboxIcon as={CheckIcon} />
  </CheckboxIndicator>
  <CheckboxLabel>I accept the terms and conditions</CheckboxLabel>
</Checkbox>

Incorrect Pattern

// ❌ INCORRECT: Missing sub-components
<Checkbox isChecked={accepted}>
  <Text>Accept terms</Text>  {/* ❌ Must use CheckboxLabel */}
</Checkbox>

// ❌ INCORRECT: Icon not wrapped properly
<Checkbox>
  <CheckIcon />  {/* ❌ Must use CheckboxIndicator > CheckboxIcon */}
  <CheckboxLabel>Accept</CheckboxLabel>
</Checkbox>

Select Component Patterns

Correct Pattern

// ✅ CORRECT: Select with trigger and options
<Select>
  <SelectTrigger>
    <SelectInput placeholder="Select option" />
    <SelectIcon as={ChevronDownIcon} />
  </SelectTrigger>
  <SelectPortal>
    <SelectBackdrop />
    <SelectContent>
      <SelectDragIndicatorWrapper>
        <SelectDragIndicator />
      </SelectDragIndicatorWrapper>
      <SelectItem label="Option 1" value="1">
        <SelectItemText>Option 1</SelectItemText>
      </SelectItem>
      <SelectItem label="Option 2" value="2">
        <SelectItemText>Option 2</SelectItemText>
      </SelectItem>
    </SelectContent>
  </SelectPortal>
</Select>

Compound Component Reference Table

Key Principles

1. Always use sub-components - Never place raw text, icons, or elements directly as children
2. InputIcon requires InputSlot - This is mandatory, not optional
3. Text content requires text sub-components - ButtonText, AlertText, etc.
4. Icons require icon sub-components - ButtonIcon, InputIcon (inside InputSlot), etc.
5. Check official docs - Component structures may vary; always verify at https://gluestack.io/ui/docs/components/${componentName}/

Common Mistakes to Avoid

// ❌ MISTAKE: InputIcon without InputSlot
<Input>
  <InputIcon as={MailIcon} />
  <InputField />
</Input>

// ❌ MISTAKE: Button text not wrapped
<Button>Submit</Button>

// ❌ MISTAKE: FormControl error not using sub-components
<FormControl isInvalid={true}>
  <InputField />
  <Text className="text-red-500">Error</Text>  {/* ❌ Use FormControlError */}
</FormControl>

// ❌ MISTAKE: Checkbox without proper structure
<Checkbox>
  <Text>Label</Text>  {/* ❌ Use CheckboxLabel */}
</Checkbox>

Rule 9: Copy-Paste Philosophy

Gluestack-ui uses a copy-paste approach. Components are copied into your codebase, not installed as npm packages.

IMPORTANT: Before copying or using any component, verify the latest usage patterns, sub-components, and API at https://gluestack.io/ui/docs/components/${componentName}/

Correct Pattern

1. Check official v5 docs - Visit https://gluestack.io/ui/docs/components/${componentName}/ to verify latest API and patterns
2. Copy component files from gluestack-ui into your components/ui/ directory
3. Import from your local components directory
4. Customize as needed

// Import from your local components
import { Button, ButtonText } from "@/components/ui/button";
import { Box } from "@/components/ui/box";

Incorrect Pattern

// Don't try to import from a package
import { Button } from "@gluestack-ui/button"; // ❌ This doesn't exist

Rule 10: Provider Setup

Always wrap your app with GluestackUIProvider to enable theming and component functionality.

Correct Pattern

import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider";

export default function App() {
  return (
    <GluestackUIProvider>
      <YourApp />
    </GluestackUIProvider>
  );
}

Theme Switching in v5

v5 supports two styling engines with different theme-switching APIs:

• NativeWind v5: Uses Appearance.setColorScheme() (same as v4). Theme tokens in global.css use @media (prefers-color-scheme: dark) + .dark/.light class selectors for web.
• UniWind: Uses Uniwind.setTheme('light' | 'dark' | 'system'). Theme tokens use :where(.dark, .dark *) / :where(.light, .light *) selectors.

After re-adding GluestackUIProvider via npx gluestack-ui@alpha add gluestack-ui-provider, the provider handles theme switching automatically for your chosen engine.

Rule 11: Icon Usage

Use icons from @/components/ui/icon following this priority:

1. Pre-built icons - Use icons already exported from components/ui/icon/index.tsx (e.g., ChevronRightIcon, SearchIcon, CheckIcon)
2. Lucide Icons (Recommended) - If the icon is not available in components/ui/icon/index.tsx, use Lucide Icons if available
3. Custom icons with createIcon - If neither is available, create custom icons using the createIcon function

Icon Resolution Hierarchy

1. Check if icon exists in @/components/ui/icon (e.g., ChevronRightIcon, SearchIcon)
2. Use Lucide Icons if available (recommended for missing icons)
3. Create custom icon using createIcon function

Using Pre-built Icons

import { ChevronRightIcon, SearchIcon } from '@/components/ui/icon';
import { Icon } from '@/components/ui/icon';
import { Button, ButtonIcon } from '@/components/ui/button';

<Button>
  <ButtonText>Next</ButtonText>
  <ButtonIcon as={ChevronRightIcon} />
</Button>

<Icon as={SearchIcon} size="md" className="text-foreground" />

Using Lucide Icons (Recommended)

When an icon is not available in components/ui/icon/index.tsx, use Lucide Icons:

import { Icon } from "@/components/ui/icon";
import { Heart } from "lucide-react-native";

<Icon as={Heart} size="md" className="text-foreground" />;

Creating Custom Icons with createIcon

If an icon is not available in components/ui/icon/index.tsx and not available in Lucide Icons, create a custom icon using the createIcon function:

import { Icon, createIcon } from "@/components/ui/icon";
import { Path } from "react-native-svg";

function App() {
  const CustomIcon = createIcon({
    viewBox: "0 0 32 32",
    path: (
      <>
        <Path
          d="M9.5 14.6642L15.9999 9.87633V12.1358L9.5 16.9236V14.6642Z"
          fill="grey"
        />
        <Path
          d="M22.5 14.6642L16.0001 9.87639V12.1359L22.5 16.9237V14.6642Z"
          fill="grey"
        />
      </>
    ),
  });

  return <Icon as={CustomIcon} size="xl" className="text-foreground" />;
}

Correct Pattern

// Using pre-built icon
import { ChevronRightIcon } from "@/components/ui/icon";
import { Button, ButtonIcon } from "@/components/ui/button";

<Button>
  <ButtonText>Continue</ButtonText>
  <ButtonIcon as={ChevronRightIcon} />
</Button>;

// Using Lucide icon (when not in components/ui/icon)
import { Icon } from "@/components/ui/icon";
import { Heart } from "lucide-react-native";

<Icon as={Heart} size="md" className="text-foreground" />;

// Creating custom icon
import { Icon, createIcon } from "@/components/ui/icon";
import { Path } from "react-native-svg";

const CustomIcon = createIcon({
  viewBox: "0 0 24 24",
  path: (
    <Path
      d="M12 2L2 7L12 12L22 7L12 2Z"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
    />
  ),
});

<Icon as={CustomIcon} size="md" className="text-foreground" />;

Incorrect Pattern

// ❌ Don't import icons from external packages directly
import { Heart } from "@some-icon-package";

// ❌ Don't use raw SVG components without createIcon
import Svg, { Path } from "react-native-svg";

<Svg>
  <Path d="..." />
</Svg>;

CRITICAL: Semantic Token Usage in Components

When using any component, you MUST use ONLY semantic color tokens.

✅ CORRECT: Semantic Tokens

// ✅ Text colors
<Text className="text-foreground">Main content</Text>
<Text className="text-muted-foreground">Secondary text</Text>
<Text className="text-destructive">Error message</Text>

// ✅ Background colors
<Box className="bg-background">Main area</Box>
<Box className="bg-card">Card content</Box>
<Box className="bg-primary">Primary action</Box>

// ✅ Border colors
<Box className="border border-border">Standard border</Box>
<Input className="border-input">Input field</Input>

// ✅ Alpha values
<Box className="bg-primary/10">Subtle background</Box>
<Text className="text-foreground/70">Muted text</Text>

❌ PROHIBITED: Generic and Numbered Tokens

// ❌ NEVER use typography tokens
<Text className="text-typography-900">Heading</Text>
<Text className="text-typography-600">Description</Text>

// ❌ NEVER use neutral tokens
<Box className="bg-neutral-100">Card</Box>
<Text className="text-neutral-700">Text</Text>

// ❌ NEVER use gray/slate tokens
<Box className="bg-gray-50">Background</Box>
<Text className="text-gray-900">Content</Text>

// ❌ NEVER use numbered colors
<Box className="bg-blue-600">Primary</Box>
<Text className="text-red-500">Error</Text>

// ❌ NEVER use opacity utilities
<Text className="text-black opacity-70">Muted</Text>

Common Form Patterns

// Complete form with InputIcon properly wrapped in InputSlot
<FormControl isInvalid={hasError}>
  <FormControlLabel>
    <FormControlLabelText>Email</FormControlLabelText>
  </FormControlLabel>
  <Input>
    <InputSlot>
      <InputIcon as={MailIcon} className="text-muted-foreground" />
    </InputSlot>
    <InputField
      placeholder="Enter email"
      value={email}
     
    />
  </Input>
  {hasError && (
    <FormControlError>
      <FormControlErrorIcon as={AlertCircleIcon} />
      <FormControlErrorText>Invalid email</FormControlErrorText>
    </FormControlError>
  )}
</FormControl>

// Password input with show/hide toggle
<Input>
  <InputSlot>
    <InputIcon as={LockIcon} className="text-muted-foreground" />
  </InputSlot>
  <InputField
    placeholder="Enter password"
    secureTextEntry={!showPassword}
    value={password}
   
  />
  <InputSlot => setShowPassword(!showPassword)}>
    <InputIcon
      as={showPassword ? EyeOffIcon : EyeIcon}
      className="text-muted-foreground"
    />
  </InputSlot>
</Input>

Reference

Always verify component usage at: https://gluestack.io/ui/docs/components/${componentName}/