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:

| React Native | Gluestack Equivalent | | ------------------------------------ | ---------------------------------------------- | | View from "react-native" | Box from "@/components/ui/box" | | Text from "react-native" | Text from "@/components/ui/text" | | TouchableOpacity from "react-native" | Pressable from "@/components/ui/pressable" | | ScrollView from "react-native" | ScrollView from "@/components/ui/scroll-view" | | Image from "react-native" | Image from "@/components/ui/image" | | TextInput from "react-native" | Input, InputField from "@/components/ui/input" | | FlatList from "react-native" | FlatList from "@/components/ui/flat-list" |

Correct Pattern

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

const Component = () => (
  
    Hello
    
      Press Me
    
  
);

Incorrect Pattern

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

const Component = () => (
  
    Hello
    
      Press Me
    
  
);

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:

| Component | Use Prop Instead of className | Available Values | |-----------|------------------------------|-----------------| | VStack / HStack | space instead of gap-* | xs, sm, md, lg, xl, 2xl, 3xl, 4xl | | Button | variant instead of bg-* classes | default, destructive, outline, secondary, ghost, link | | Button | size instead of px-* py-* classes | default, sm, lg, icon | | Heading | size instead of text-* classes | xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl | | Text | size instead of text-* classes | 2xs, xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl | | Heading / Text | bold prop instead of font-bold | boolean | | Heading / Text | isTruncated prop instead of truncate | boolean | | VStack / HStack | reversed prop instead of flex-*-reverse | boolean |

Correct Pattern: Using Component Props

// ✅ CORRECT: Using space prop instead of gap className

  Item 1
  Item 2

// ✅ CORRECT: Using Button variant and size props

  Click Me

// ✅ CORRECT: Using Heading size prop

  Title

// ✅ CORRECT: Using Text size and bold props

  Important text

// ✅ CORRECT: Using HStack space prop

  Label
  
    Action
  

Incorrect Pattern: Using className Instead of Props

// ❌ INCORRECT: Using gap className instead of space prop

  Item 1
  Item 2

// ❌ INCORRECT: Using className for button styling instead of variant/size props

  Click Me

// ❌ INCORRECT: Using text size className instead of size prop

  Title

// ❌ INCORRECT: Using className for spacing instead of space prop

  Label
  
    Action
  

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

  Title
  Description

// ✅ CORRECT: Using variant prop + className for custom adjustments

  Full Width Button

Space Prop Mapping

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

| space prop | Gap Value | Equivalent className | |------------|-----------|---------------------| | xs | 4px | gap-1 | | sm | 8px | gap-2 | | md | 12px | gap-3 | | lg | 16px | gap-4 | | xl | 20px | gap-5 | | 2xl | 24px | gap-6 | | 3xl | 28px | gap-7 | | 4xl | 32px | gap-8 |

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

  
    
  
  

// ✅ CORRECT: Right icon (interactive) wrapped in InputSlot

  
   setShowPassword(!showPassword)}>
    
  

// ✅ CORRECT: Both left and right icons wrapped in InputSlot

  
    
  
  
  
    
  

Incorrect: InputIcon Used Directly (Will Break)

// ❌ INCORRECT: InputIcon used directly without InputSlot

    {/* ❌ Missing InputSlot wrapper */}
  

// ❌ INCORRECT: InputIcon outside Input structure
  {/* ❌ Must be inside Input > InputSlot */}

  

Button Component Patterns

Correct Pattern

// ✅ CORRECT: Button with text and icon

  Click Me
  

// ✅ CORRECT: Button with only text

  Submit

// ✅ CORRECT: Button with only icon

  

// ✅ CORRECT: Button with loading state

  {isLoading ? (
    <>
      
      Loading...
    
  ) : (
    Submit
  )}

Incorrect Pattern

// ❌ INCORRECT: Text not wrapped in ButtonText
Click Me

// ❌ INCORRECT: Direct text children

  Click Me  {/* ❌ Must use ButtonText */}

// ❌ INCORRECT: Icon not wrapped in ButtonIcon

  Next
    {/* ❌ Must use ButtonIcon */}

FormControl Component Patterns

Correct Pattern

// ✅ CORRECT: Complete FormControl with label, input, and error

  
    Email Address
  
  
    
      
    
    
  
  {errors.email && (
    
      
      {errors.email}
    
  )}
  
    We'll never share your email
  

Incorrect Pattern

// ❌ INCORRECT: Missing sub-components

  Email  {/* ❌ Must use FormControlLabel > FormControlLabelText */}
    {/* ❌ Must wrap in Input */}

// ❌ INCORRECT: Error text not wrapped

  
    
  
  {hasError && Error message}  {/* ❌ Must use FormControlError > FormControlErrorText */}

Card Component Patterns

Correct Pattern

// ✅ CORRECT: Complete Card structure

  
    Card Title
    Subtitle
  
  
    Card content goes here
  
  
    
      Cancel
    
    
      Confirm
    
  

Incorrect Pattern

// ❌ INCORRECT: Direct children without sub-components

  Title  {/* ❌ Must use CardHeader */}
  Content  {/* ❌ Must use CardBody */}

Checkbox Component Patterns

Correct Pattern

// ✅ CORRECT: Checkbox with label
 setAccepted(isChecked)}
>
  
    
  
  I accept the terms and conditions

Incorrect Pattern

// ❌ INCORRECT: Missing sub-components

  Accept terms  {/* ❌ Must use CheckboxLabel */}

// ❌ INCORRECT: Icon not wrapped properly

    {/* ❌ Must use CheckboxIndicator > CheckboxIcon */}
  Accept

Select Component Patterns

Correct Pattern

// ✅ CORRECT: Select with trigger and options

  
    
    
  
  
    
    
      
        
      
      
        Option 1
      
      
        Option 2
      
    
  

Compound Component Reference Table

| Component | Required Sub-Components | Optional Sub-Components | Notes | |-----------|------------------------|------------------------|-------| | Input | InputField | InputSlot, InputIcon | InputIcon MUST be inside InputSlot | | Button | ButtonText | ButtonIcon, ButtonSpinner | Text content must use ButtonText | | Card | None | CardHeader, CardBody, CardFooter | Structure for organization | | FormControl | None | FormControlLabel, FormControlError, FormControlHelper | Wrapper for form fields | | Checkbox | CheckboxIndicator, CheckboxLabel | CheckboxIcon | Icon goes inside Indicator | | Select | SelectTrigger, SelectInput | SelectIcon, SelectContent, SelectItem | Complex structure required | | Alert | AlertText | AlertIcon, AlertTitle | Text must use AlertText | | Toast | ToastTitle | ToastDescription, ToastCloseButton | Title required for display |

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

  
  

// ❌ MISTAKE: Button text not wrapped
Submit

// ❌ MISTAKE: FormControl error not using sub-components

  
  Error  {/* ❌ Use FormControlError */}

// ❌ MISTAKE: Checkbox without proper structure

  Label  {/* ❌ Use CheckboxLabel */}

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 (
    
      
    
  );
}

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';

  Next
  

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";

;

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: (
      <>
        
        
      
    ),
  });

  return ;
}

Correct Pattern

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

  Continue
  
;

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

;

// 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: (
    
  ),
});

;

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";

  
;

CRITICAL: Semantic Token Usage in Components

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

✅ CORRECT: Semantic Tokens

// ✅ Text colors
Main content
Secondary text
Error message

// ✅ Background colors
Main area
Card content
Primary action

// ✅ Border colors
Standard border
Input field

// ✅ Alpha values
Subtle background
Muted text

❌ PROHIBITED: Generic and Numbered Tokens

// ❌ NEVER use typography tokens
Heading
Description

// ❌ NEVER use neutral tokens
Card
Text

// ❌ NEVER use gray/slate tokens
Background
Content

// ❌ NEVER use numbered colors
Primary
Error

// ❌ NEVER use opacity utilities
Muted

Common Form Patterns

// Complete form with InputIcon properly wrapped in InputSlot

  
    Email
  
  
    
      
    
    
  
  {hasError && (
    
      
      Invalid email
    
  )}

// Password input with show/hide toggle

  
    
  
  
   setShowPassword(!showPassword)}>
    
  

Reference

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gluestack
• Source: gluestack/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.