Skip to main content
Reflex UI is a comprehensive library of reusable UI components built on top of Base UI and styled with Tailwind CSS. It provides a set of accessible, customizable components designed specifically for Reflex applications.

​
Component Architecture

Reflex UI components follow a hierarchical architecture with clear separation of concerns:

​
CoreComponent

All Reflex UI components inherit from CoreComponent, which provides the foundation for styling and customization:
reflex_ui/components/component.py
class CoreComponent(Component):
    """Core component for all components."""

    # Whether the component should be unstyled
    unstyled: Var[bool]

    @classmethod
    def set_class_name(
        cls, default_class_name: str | Var[str], props: dict[str, Any]
    ) -> None:
        """Set the class name in props, merging with the default if necessary."""
        if "render_" in props:
            return

        props_class_name = props.get("class_name", "")

        if props.pop("unstyled", False):
            props["class_name"] = props_class_name
            return

        props["class_name"] = cn(default_class_name, props_class_name)
Key features of CoreComponent:
  • Automatic style merging: Default styles are automatically merged with user-provided class_name props using the cn() utility
  • Unstyled mode: Set unstyled=True to remove all default styles and start from scratch
  • Consistent API: All components share the same styling approach

​
BaseUIComponent

Components that wrap Base UI primitives extend BaseUIComponent:
reflex_ui/components/base_ui.py
class BaseUIComponent(CoreComponent):
    """Base UI component."""

    lib_dependencies: list[str] = [f"{PACKAGE_NAME}@{PACKAGE_VERSION}"]
Base UI provides:
  • Accessibility: ARIA attributes and keyboard navigation built-in
  • Unstyled primitives: Complete control over styling
  • React components: Modern, maintained React component library

​
Component Structure

Reflex UI components typically follow these patterns:
Simple components like Button and Badge extend either CoreComponent or native HTML elements:
reflex_ui/components/base/button.py
class Button(BaseButton, CoreComponent):
    """A custom button component."""

    variant: Var[LiteralButtonVariant]
    size: Var[LiteralButtonSize]
    loading: Var[bool]
These components:
  • Define variant and size props for visual customization
  • Apply default styles based on the selected variant and size
  • Support the class_name prop for custom styling
Complex components like Checkbox and Card use a namespace pattern:
reflex_ui/components/base/checkbox.py
class CheckboxNamespace(ComponentNamespace):
    root = staticmethod(CheckboxRoot.create)
    indicator = staticmethod(CheckboxIndicator.create)
    high_level = staticmethod(HighLevelCheckbox.create)
    class_names = ClassNames
    __call__ = staticmethod(HighLevelCheckbox.create)

checkbox = CheckboxNamespace()
This pattern provides:
  • Low-level API: checkbox.root() and checkbox.indicator() for full control
  • High-level API: checkbox() for common use cases
  • Exposed class names: checkbox.class_names for style customization

​
Tailwind CSS Integration

Reflex UI is built with Tailwind CSS v4, leveraging:

​
Modern CSS Features

  • CSS Custom Properties: Theme colors are defined as CSS variables in :root
  • @theme directive: Tailwind theme is configured using CSS rather than JavaScript
  • light-dark() function: Automatic dark mode support using CSS color schemes

​
Semantic Color System

Colors follow a semantic naming system based on Radix Colors:
demo/assets/css/globals.css
:root {
  /* Primary - Main brand color */
  --primary-1: var(--violet-1);
  --primary-9: var(--violet-9);
  --primary-12: var(--violet-12);

  /* Secondary - Neutral gray scale */
  --secondary-1: var(--slate-1);
  --secondary-9: var(--slate-9);
  --secondary-12: var(--slate-12);

  /* Semantic colors */
  --destructive-9: var(--red-9);
  --success-9: var(--jade-9);
  --warning-9: var(--amber-9);
  --info-9: var(--blue-9);
}
Each color scale includes:
  • 1-12: Light to dark shades for backgrounds, borders, and text
  • a1-a12: Alpha variants for overlays and subtle effects

​
Design Principles

Accessibility First

Built on Base UI primitives with ARIA attributes, keyboard navigation, and screen reader support built-in.

Customizable

Every component supports class_name for custom styling, and most support unstyled mode for complete control.

Consistent API

All components follow the same patterns for variants, sizes, and styling, making them predictable and easy to learn.

Type Safe

Full TypeScript support with literal types for variants, ensuring compile-time validation.

​
Next Steps

Styling Components

Learn how to customize component styles using the class_name prop and cn() utility.

Theming

Discover how to implement themes and dark mode using CSS variables.

Build docs developers (and LLMs) love

Get started for freeTalk to us