gluestack-ui-v4:creating-components

Gluestack UI v4 - Creating Components

This sub-skill provides practical guidance for creating new components using gluestack-ui v4, from planning to implementation.

Component Creation Workflow

Step 1: Plan Component Structure

Before writing code, answer these questions:

1. What is the component's purpose?

   • Form input, data display, navigation, layout, etc.

2. Which Gluestack components do I need?

   • Check official docs: https://v4.gluestack.io/ui/docs/components/${componentName}/
   • Use Gluestack wrappers, not React Native primitives

3. Does it need compound components?

   • Multiple related sub-components (Header, Body, Footer)
   • Icon + Text combinations
   • Label + Input patterns

4. What props should it accept?

   • Size variants: sm, md, lg
   • Visual variants: default, outline, ghost
   • State props: isDisabled, isInvalid, isLoading
   • Custom className for overrides

5. Does it need variants?

   • If yes, use tva (Tailwind Variant Authority)
   • Define base styles and variant options

Step 2: Check Official Documentation

ALWAYS verify component usage before creating:

# Visit official docs for the component
https://v4.gluestack.io/ui/docs/components/${componentName}/

Check for:

• Latest API and props
• Required sub-components
• Usage examples
• Accessibility features

Step 3: Create Component File

Follow this file structure:

components/
├── ui/                      # Gluestack UI components (copy-paste)
│   ├── box/
│   ├── button/
│   └── input/
└── custom/                  # Your custom components
    ├── profile-card/
    │   └── index.tsx
    └── login-form/
        └── index.tsx

Component Templates

Template 1: Simple Component (No Variants)

Use when component has consistent styling without variants.

import React from 'react';
import { Box } from '@/components/ui/box';
import { Text } from '@/components/ui/text';
import { Heading } from '@/components/ui/heading';

interface ProfileCardProps {
  readonly name: string;
  readonly email: string;
  readonly className?: string;
}

export const ProfileCard = ({ name, email, className }: ProfileCardProps) => {
  return (
    <Box className={`bg-card rounded-lg border border-border p-4 ${className || ''}`}>
      <Heading size="lg" className="text-card-foreground">
        {name}
      </Heading>
      <Text size="sm" className="text-muted-foreground mt-1">
        {email}
      </Text>
    </Box>
  );
};