gluestack-ui-v5:variants

Use tva from @gluestack-ui/utils/nativewind-utils to define base styles, variant dimensions, and defaultVariants, then apply the generated class function to your component. Wrap existing Gluestack components to extend them with new variant options while preserving the originals.

tva is Tailwind Variant Authority, a utility for creating type-safe, composable style variants. It accepts base classes, variant definitions, compoundVariants for specific combinations, and defaultVariants, returning a function that merges classes based on props.

Share the parent's variant state through React context, then use the parentVariants option in the child's tva definition. The child reads the context values and passes them as parentVariants to compute its styles.

No, variant styles must use only semantic tokens such as bg-primary/10, text-destructive, or bg-muted. Numbered colors, generic tokens like gray or neutral, and typography tokens are prohibited because they break automatic light and dark theme switching.

Check that your Tailwind configuration includes the tva patterns, verify the className merge order, and ensure no conflicting inline styles override the generated classes. Also confirm defaultVariants match your TypeScript variant types.

Create a variant when the same style combination repeats in multiple places, represents a project-specific design pattern, or depends on props. Use plain className for one-off styles or simple modifications of existing component props.