Quickstart Guide
Learn how to use Reflex UI components by building a simple interactive application. This guide assumes you’ve already installed Reflex UI.
Your First Component
Let’s start with a simple button that displays a toast notification when clicked.
Import Reflex and Reflex UI
Create a new Python file (e.g., app.py) and import the necessary modules:import reflex as rx
import reflex_ui as ui
Create a basic button
Use the ui.button() component to create a styled button:def index():
return ui.button(
"Click me",
on_click=rx.toast.success("You clicked the button!"),
)
app = rx.App(stylesheets=["css/globals.css"])
app.add_page(index)
reflex run and click the button to see a success toast! Add an icon to your button
Reflex UI includes HugeIcons. Add an icon to make your button more engaging:def index():
return ui.button(
ui.icon("SmileIcon"),
"Click me",
on_click=rx.toast.success("You are cool!", position="top-center"),
)
Browse available icons at HugeIcons. Use the icon name as shown in the library. Building an Interactive Card
Now let’s build a more complex example using multiple components with state management.
Create a Counter Card
This example demonstrates a card with interactive controls:
import reflex as rx
import reflex_ui as ui
class CounterState(rx.State):
count: int = 0
def increment(self):
self.count += 1
def decrement(self):
self.count -= 1
def reset(self):
self.count = 0
def counter_card():
return ui.card(
title="Counter",
description="A simple counter with increment and decrement buttons",
content=rx.el.div(
rx.el.p(
f"Current count: {CounterState.count}",
class_name="text-2xl font-bold text-center",
),
class_name="py-4",
),
footer=rx.el.div(
ui.button(
ui.icon("MinusIcon"),
"Decrement",
on_click=CounterState.decrement,
variant="outline",
),
ui.button(
"Reset",
on_click=CounterState.reset,
variant="secondary",
),
ui.button(
ui.icon("PlusIcon"),
"Increment",
on_click=CounterState.increment,
),
class_name="flex gap-2",
),
class_name="max-w-md",
)
Exploring Component Variants
Many Reflex UI components support multiple variants. Here’s an example with buttons:
def button_showcase():
return rx.el.div(
rx.el.h2("Button Variants", class_name="text-xl font-bold mb-4"),
rx.el.div(
ui.button("Primary", variant="primary"),
ui.button("Secondary", variant="secondary"),
ui.button("Outline", variant="outline"),
ui.button("Ghost", variant="ghost"),
ui.button("Destructive", variant="destructive"),
class_name="flex gap-2 flex-wrap",
),
rx.el.h2("Button Sizes", class_name="text-xl font-bold mb-4 mt-8"),
rx.el.div(
ui.button("Extra Small", size="xs"),
ui.button("Small", size="sm"),
ui.button("Medium", size="md"),
ui.button("Large", size="lg"),
ui.button("Extra Large", size="xl"),
class_name="flex gap-2 items-center flex-wrap",
),
class_name="p-8",
)
Real-World Example
Here’s a complete example from the Reflex UI demo that showcases multiple components working together:
import reflex as rx
import reflex_ui as ui
class State(rx.State):
seed: int = 0
@rx.event
def set_seed(self, seed: int):
self.seed = seed
def index():
return rx.el.div(
rx.el.div(
# Button with tooltip
ui.tooltip(
ui.button(
ui.icon("SmileIcon"),
"Click me",
on_click=rx.toast.success(
"You are cool :)",
position="top-center",
),
),
content="Seriously, click me",
),
# Checkbox
ui.checkbox(
label="Enable feature",
on_checked_change=lambda value: rx.toast.success(f"Checked: {value}"),
),
# Slider with state
ui.slider(
value=State.seed,
on_value_change=State.set_seed,
on_value_committed=lambda value: rx.toast.success(f"Final value: {value}"),
class_name="max-w-xs",
),
# Gradient profile avatar
ui.gradient_profile(
seed=State.seed,
class_name="size-10",
),
# Switch toggle
ui.switch(
on_checked_change=lambda value: rx.toast.success(f"Switch: {value}"),
),
# Select dropdown
ui.select(
items=[f"Option {i}" for i in range(1, 6)],
name="select",
placeholder="Choose an option",
on_value_change=lambda value: rx.toast.success(f"Selected: {value}"),
),
class_name="flex flex-col gap-y-6 justify-center items-center",
),
# Theme switcher in corner
ui.theme_switcher(class_name="absolute top-4 right-4"),
class_name="flex flex-row gap-16 justify-center items-center h-screen bg-secondary-1 relative font-sans",
)
app = rx.App(
stylesheets=["css/globals.css"],
)
app.add_page(index)
This example demonstrates:
- Tooltips for contextual help
- State management with reactive values
- Event handlers for user interactions
- Layout utilities using Tailwind classes
- Theme switching for light/dark mode
Component Composition
Reflex UI components are designed to be composed together. Here’s a card with a custom structure:
def custom_card():
return ui.card.root(
ui.card.header(
ui.card.title("Custom Card"),
ui.card.description("Built with composition"),
),
ui.card.content(
rx.el.p("This card uses the compositional API."),
ui.button("Action", class_name="mt-4"),
),
ui.card.footer(
rx.el.span("Footer content", class_name="text-sm text-secondary-11"),
),
)
Styling with Tailwind
All Reflex UI components accept the class_name prop for custom styling:
ui.button(
"Styled Button",
class_name="bg-gradient-to-r from-blue-500 to-purple-600 hover:from-blue-600 hover:to-purple-700",
)
You can override default styles or add custom Tailwind classes to any component.
Next Steps
Now that you’ve built your first components, explore more:
Component Library
Explore all available components and their props
Styling Guide
Learn about styling components with Tailwind
Theming
Customize colors and dark mode
State Management
Deep dive into Reflex state management
Common Patterns
Loading States
Show loading states in buttons:
class FormState(rx.State):
is_loading: bool = False
async def submit(self):
self.is_loading = True
# Simulate API call
await asyncio.sleep(2)
self.is_loading = False
ui.button(
"Submit",
on_click=FormState.submit,
loading=FormState.is_loading,
)
ui.input(
placeholder="Enter your email",
type="email",
class_name="w-full",
)
Conditional Rendering
Use Reflex’s cond for conditional UI:
rx.cond(
State.is_logged_in,
ui.button("Logout", on_click=State.logout),
ui.button("Login", on_click=State.login),
)