gluestack-ui - Components
Expert knowledge of gluestack-ui's universal component library for building accessible, performant UI across React and React Native platforms.
Overview
gluestack-ui provides 50+ unstyled, accessible components that work seamlessly on web and mobile. Components are copy-pasteable into your project and styled with NativeWind (Tailwind CSS for React Native).
Key Concepts
Component Installation
Add components using the CLI:
# Initialize gluestack-ui in your project
npx gluestack-ui init
# Add individual components
npx gluestack-ui add button
npx gluestack-ui add input
npx gluestack-ui add modal
# Add multiple components
npx gluestack-ui add button input select modal
# Add all components
npx gluestack-ui add --allComponent Anatomy
Every gluestack-ui component follows a consistent pattern:
import { Button, ButtonText, ButtonSpinner, ButtonIcon } from '@/components/ui/button';
// Components are composable with sub-components
<Button size="md" variant="solid" action="primary">
<ButtonIcon as={PlusIcon} />
<ButtonText>Add Item</ButtonText>
<ButtonSpinner />
</Button>Variants, Sizes, and Actions
Components support consistent prop APIs:
// Button variants
<Button variant="solid">Solid</Button>
<Button variant="outline">Outline</Button>
<Button variant="link">Link</Button>
// Button sizes
<Button size="xs">Extra Small</Button>
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra Large</Button>
// Button actions (semantic colors)
<Button action="primary">Primary</Button>
<Button action="secondary">Secondary</Button>
<Button action="positive">Positive</Button>
<Button action="negative">Negative</Button>Core Components
Button
Interactive button with loading states and icons:
import { Button, ButtonText, ButtonSpinner, ButtonIcon } from '@/components/ui/button';
import { SaveIcon } from 'lucide-react-native';
function SaveButton({ isLoading, onPress }: { isLoading: boolean; onPress: () => void }) {
return (
<Button
size="md"
variant="solid"
action="primary"
isDisabled={isLoading}
onPress={onPress}
>
{isLoading ? (
<ButtonSpinner />
) : (
<ButtonIcon as={SaveIcon} />
)}
<ButtonText>{isLoading ? 'Saving...' : 'Save'}</ButtonText>
</Button>
);
}Input
Text input with labels and validation:
import {
FormControl,
FormControlLabel,
FormControlLabelText,
FormControlHelper,
FormControlHelperText,
FormControlError,
FormControlErrorIcon,
FormControlErrorText,
} from '@/components/ui/form-control';
import { Input, InputField, InputSlot, InputIcon } from '@/components/ui/input';
import { AlertCircleIcon, MailIcon } from 'lucide-react-native';
function EmailInput({ value, onChange, error }: {
value: string;
onChange: (text: string) => void;
error?: string;
}) {
return (
<FormControl isInvalid={!!error}>
<FormControlLabel>
<FormControlLabelText>Email</FormControlLabelText>
</FormControlLabel>
<Input variant="outline" size="md">
<InputSlot pl="$3">
<InputIcon as={MailIcon} />
</InputSlot>
<InputField
placeholder="Enter your email"
value={value}
onChangeText={onChange}
keyboardType="email-address"
autoCapitalize="none"
/>
</Input>
{error ? (
<FormControlError>
<FormControlErrorIcon as={AlertCircleIcon} />
<FormControlErrorText>{error}</FormControlErrorText>
</FormControlError>
) : (
<FormControlHelper>
<FormControlHelperText>We'll never share your email</FormControlHelperText>
</FormControlHelper>
)}
</FormControl>
);
}Select
Dropdown selection component:
import {
Select,
SelectTrigger,
SelectInput,
SelectIcon,
SelectPortal,
SelectBackdrop,
SelectContent,
SelectDragIndicatorWrapper,
SelectDragIndicator,
SelectItem,
} from '@/components/ui/select';
import { ChevronDownIcon } from 'lucide-react-native';
function CountrySelect({ value, onValueChange }: {
value: string;
onValueChange: (value: string) => void;
}) {
return (
<Select selectedValue={value} onValueChange={onValueChange}>
<SelectTrigger variant="outline" size="md">
<SelectInput placeholder="Select country" />
<SelectIcon as={ChevronDownIcon} mr="$3" />
</SelectTrigger>
<SelectPortal>
<SelectBackdrop />
<SelectContent>
<SelectDragIndicatorWrapper>
<SelectDragIndicator />
</SelectDragIndicatorWrapper>
<SelectItem label="United States" value="us" />
<SelectItem label="Canada" value="ca" />
<SelectItem label="United Kingdom" value="uk" />
<SelectItem label="Australia" value="au" />
</SelectContent>
</SelectPortal>
</Select>
);
}Modal
Dialog overlay component:
import {
Modal,
ModalBackdrop,
ModalContent,
ModalHeader,
ModalCloseButton,
ModalBody,
ModalFooter,
} from '@/components/ui/modal';
import { Heading } from '@/components/ui/heading';
import { Text } from '@/components/ui/text';
import { Button, ButtonText } from '@/components/ui/button';
import { CloseIcon, Icon } from '@/components/ui/icon';
function ConfirmModal({ isOpen, onClose, onConfirm, title, message }: {
isOpen: boolean;
onClose: () => void;
onConfirm: () => void;
title: string;
message: string;
}) {
return (
<Modal isOpen={isOpen} onClose={onClose} size="md">
<ModalBackdrop />
<ModalContent>
<ModalHeader>
<Heading size="lg">{title}</Heading>
<ModalCloseButton>
<Icon as={CloseIcon} />
</ModalCloseButton>
</ModalHeader>
<ModalBody>
<Text>{message}</Text>
</ModalBody>
<ModalFooter>
<Button variant="outline" action="secondary" onPress={onClose}>
<ButtonText>Cancel</ButtonText>
</Button>
<Button action="negative" onPress={onConfirm}>
<ButtonText>Delete</ButtonText>
</Button>
</ModalFooter>
</ModalContent>
</Modal>
);
}Toast
Notification component:
import {
Toast,
ToastTitle,
ToastDescription,
useToast,
} from '@/components/ui/toast';
function NotificationExample() {
const toast = useToast();
const showToast = () => {
toast.show({
placement: 'top',
render: ({ id }) => (
<Toast nativeID={`toast-${id}`} action="success" variant="solid">
<ToastTitle>Success!</ToastTitle>
<ToastDescription>Your changes have been saved.</ToastDescription>
</Toast>
),
});
};
return (
<Button onPress={showToast}>
<ButtonText>Show Toast</ButtonText>
</Button>
);
}Accordion
Expandable content sections:
import {
Accordion,
AccordionItem,
AccordionHeader,
AccordionTrigger,
AccordionTitleText,
AccordionIcon,
AccordionContent,
AccordionContentText,
} from '@/components/ui/accordion';
import { ChevronDownIcon, ChevronUpIcon } from 'lucide-react-native';
function FAQAccordion({ items }: { items: { question: string; answer: string }[] }) {
return (
<Accordion type="multiple" defaultValue={['item-0']}>
{items.map((item, index) => (
<AccordionItem key={index} value={`item-${index}`}>
<AccordionHeader>
<AccordionTrigger>
{({ isExpanded }) => (
<>
<AccordionTitleText>{item.question}</AccordionTitleText>
<AccordionIcon as={isExpanded ? ChevronUpIcon : ChevronDownIcon} />
</>
)}
</AccordionTrigger>
</AccordionHeader>
<AccordionContent>
<AccordionContentText>{item.answer}</AccordionContentText>
</AccordionContent>
</AccordionItem>
))}
</Accordion>
);
}Checkbox and Radio
Selection controls:
import {
Checkbox,
CheckboxIndicator,
CheckboxIcon,
CheckboxLabel,
} from '@/components/ui/checkbox';
import {
RadioGroup,
Radio,
RadioIndicator,
RadioIcon,
RadioLabel,
} from '@/components/ui/radio';
import { CheckIcon, CircleIcon } from 'lucide-react-native';
function TermsCheckbox({ isChecked, onChange }: {
isChecked: boolean;
onChange: (checked: boolean) => void;
}) {
return (
<Checkbox value="terms" isChecked={isChecked} onChange={onChange}>
<CheckboxIndicator>
<CheckboxIcon as={CheckIcon} />
</CheckboxIndicator>
<CheckboxLabel>I agree to the terms and conditions</CheckboxLabel>
</Checkbox>
);
}
function ShippingOptions({ value, onChange }: {
value: string;
onChange: (value: string) => void;
}) {
return (
<RadioGroup value={value} onChange={onChange}>
<Radio value="standard">
<RadioIndicator>
<RadioIcon as={CircleIcon} />
</RadioIndicator>
<RadioLabel>Standard Shipping (5-7 days)</RadioLabel>
</Radio>
<Radio value="express">
<RadioIndicator>
<RadioIcon as={CircleIcon} />
</RadioIndicator>
<RadioLabel>Express Shipping (2-3 days)</RadioLabel>
</Radio>
<Radio value="overnight">
<RadioIndicator>
<RadioIcon as={CircleIcon} />
</RadioIndicator>
<RadioLabel>Overnight Shipping (1 day)</RadioLabel>
</Radio>
</RadioGroup>
);
}Best Practices
1. Use Composition Over Configuration
Compose components with sub-components for flexibility:
// Good: Composable structure
<Button>
<ButtonIcon as={PlusIcon} />
<ButtonText>Add</ButtonText>
</Button>
// Avoid: Prop-heavy configuration
<Button icon={PlusIcon} text="Add" iconPosition="left" />2. Leverage FormControl for Form Fields
Wrap inputs in FormControl for consistent validation:
<FormControl isRequired isInvalid={!!error}>
<FormControlLabel>
<FormControlLabelText>Password</FormControlLabelText>
</FormControlLabel>
<Input>
<InputField type="password" />
</Input>
<FormControlError>
<FormControlErrorText>{error}</FormControlErrorText>
</FormControlError>
</FormControl>3. Handle Platform Differences
Use platform-specific logic when needed:
import { Platform } from 'react-native';
function ResponsiveModal({ children }: { children: React.ReactNode }) {
return (
<Modal size={Platform.OS === 'web' ? 'lg' : 'full'}>
<ModalContent>
{children}
</ModalContent>
</Modal>
);
}4. Use Proper Loading States
Show loading feedback for async operations:
function SubmitButton({ isLoading, onPress }: {
isLoading: boolean;
onPress: () => void;
}) {
return (
<Button isDisabled={isLoading} onPress={onPress}>
{isLoading && <ButtonSpinner mr="$2" />}
<ButtonText>{isLoading ? 'Submitting...' : 'Submit'}</ButtonText>
</Button>
);
}5. Create Reusable Component Wrappers
Build app-specific components on top of gluestack-ui:
// components/app/PrimaryButton.tsx
import { Button, ButtonText, ButtonSpinner } from '@/components/ui/button';
interface PrimaryButtonProps {
children: string;
isLoading?: boolean;
onPress: () => void;
}
export function PrimaryButton({ children, isLoading, onPress }: PrimaryButtonProps) {
return (
<Button
size="lg"
variant="solid"
action="primary"
isDisabled={isLoading}
onPress={onPress}
className="rounded-full"
>
{isLoading && <ButtonSpinner mr="$2" />}
<ButtonText>{children}</ButtonText>
</Button>
);
}Common Patterns
Form with Validation
import { useState } from 'react';
import { VStack } from '@/components/ui/vstack';
import { Button, ButtonText } from '@/components/ui/button';
import { FormControl, FormControlError, FormControlErrorText } from '@/components/ui/form-control';
import { Input, InputField } from '@/components/ui/input';
interface FormData {
email: string;
password: string;
}
interface FormErrors {
email?: string;
password?: string;
}
function LoginForm({ onSubmit }: { onSubmit: (data: FormData) => void }) {
const [formData, setFormData] = useState<FormData>({ email: '', password: '' });
const [errors, setErrors] = useState<FormErrors>({});
const validate = (): boolean => {
const newErrors: FormErrors = {};
if (!formData.email) {
newErrors.email = 'Email is required';
} else if (!/\S+@\S+\.\S+/.test(formData.email)) {
newErrors.email = 'Invalid email format';
}
if (!formData.password) {
newErrors.password = 'Password is required';
} else if (formData.password.length < 8) {
newErrors.password = 'Password must be at least 8 characters';
}
setErrors(newErrors);
return Object.keys(newErrors).length === 0;
};
const handleSubmit = () => {
if (validate()) {
onSubmit(formData);
}
};
return (
<VStack space="md">
<FormControl isInvalid={!!errors.email}>
<Input>
<InputField
placeholder="Email"
value={formData.email}
onChangeText={(text) => setFormData({ ...formData, email: text })}
/>
</Input>
<FormControlError>
<FormControlErrorText>{errors.email}</FormControlErrorText>
</FormControlError>
</FormControl>
<FormControl isInvalid={!!errors.password}>
<Input>
<InputField
placeholder="Password"
type="password"
value={formData.password}
onChangeText={(text) => setFormData({ ...formData, password: text })}
/>
</Input>
<FormControlError>
<FormControlErrorText>{errors.password}</FormControlErrorText>
</FormControlError>
</FormControl>
<Button onPress={handleSubmit}>
<ButtonText>Login</ButtonText>
</Button>
</VStack>
);
}Data List with Actions
import { HStack } from '@/components/ui/hstack';
import { VStack } from '@/components/ui/vstack';
import { Box } from '@/components/ui/box';
import { Text } from '@/components/ui/text';
import { Heading } from '@/components/ui/heading';
import { Button, ButtonIcon } from '@/components/ui/button';
import { Pressable } from '@/components/ui/pressable';
import { TrashIcon, EditIcon } from 'lucide-react-native';
interface Item {
id: string;
title: string;
description: string;
}
function ItemList({ items, onEdit, onDelete }: {
items: Item[];
onEdit: (id: string) => void;
onDelete: (id: string) => void;
}) {
return (
<VStack space="sm">
{items.map((item) => (
<Box
key={item.id}
className="p-4 bg-background-50 rounded-lg border border-outline-200"
>
<HStack justifyContent="space-between" alignItems="center">
<VStack space="xs" flex={1}>
<Heading size="sm">{item.title}</Heading>
<Text size="sm" className="text-typography-500">
{item.description}
</Text>
</VStack>
<HStack space="xs">
<Button
size="sm"
variant="outline"
action="secondary"
onPress={() => onEdit(item.id)}
>
<ButtonIcon as={EditIcon} />
</Button>
<Button
size="sm"
variant="outline"
action="negative"
onPress={() => onDelete(item.id)}
>
<ButtonIcon as={TrashIcon} />
</Button>
</HStack>
</HStack>
</Box>
))}
</VStack>
);
}Anti-Patterns
Do Not Mix Styling Approaches
// Bad: Mixing inline styles with NativeWind
<Button style={{ backgroundColor: 'blue' }} className="p-4">
<ButtonText>Click</ButtonText>
</Button>
// Good: Use NativeWind classes consistently
<Button className="bg-blue-500 p-4">
<ButtonText>Click</ButtonText>
</Button>Do Not Skip Accessibility Props
// Bad: Missing accessibility information
<Pressable onPress={handlePress}>
<Icon as={MenuIcon} />
</Pressable>
// Good: Include accessibility props
<Pressable
onPress={handlePress}
accessibilityLabel="Open menu"
accessibilityRole="button"
>
<Icon as={MenuIcon} />
</Pressable>Do Not Ignore Platform Constraints
// Bad: Using web-only APIs on native
<Modal>
<ModalContent onClick={handleClick}> {/* onClick doesn't work on native */}
...
</ModalContent>
</Modal>
// Good: Use cross-platform events
<Modal>
<ModalContent>
<Pressable onPress={handlePress}>
...
</Pressable>
</ModalContent>
</Modal>Do Not Hardcode Colors
// Bad: Hardcoded colors
<Box className="bg-[#3B82F6]">
<Text className="text-[#FFFFFF]">Hello</Text>
</Box>
// Good: Use theme tokens
<Box className="bg-primary-500">
<Text className="text-typography-0">Hello</Text>
</Box>Related Skills
- gluestack-theming: Customizing themes and design tokens
- gluestack-accessibility: Ensuring accessible implementations