Reflex Basics
This page gives an introduction to the most common concepts that you will use to build Reflex apps.
You will learn how to:
- Create and nest components
- Customize and style components
- Distinguish between compile-time and runtime
- Display data that changes over time
- Respond to events and update the screen
- Render conditions and lists
- Create pages and navigate between them
Install reflex
using pip.
Import the reflex
library to get started.
Creating and nesting components
Components are the building blocks for your app's user interface (UI). They are the visual elements that make up your app, like buttons, text, and images. Reflex has a wide selection of built-in components to get you started quickly.
Components are created using functions that return a component object.
Components can be nested inside each other to create complex UIs.
To nest components as children, pass them as positional arguments to the parent component. In the example below, the rx.text
and my_button
components are children of the rx.box
component.
This is a page
You can also use any base HTML element through the rx.el
namespace.
Use base html!
If you need a component not provided by Reflex, you can check the 3rd party ecosystem or wrap your own React component.
Customizing and styling components
Components can be customized using props, which are passed in as keyword arguments to the component function.
Each component has props that are specific to that component. Check the docs for the component you are using to see what props are available.
In addition to component-specific props, components can also be styled using CSS properties passed as props.
See the styling guide for more information on how to style components
In summary, components are made up of children and props.
Children
* Text or other Reflex components nested inside a component. * Passed as **positional arguments**.Props
* Attributes that affect the behavior and appearance of a component. * Passed as **keyword arguments**.Children
* Text or other Reflex components nested inside a component. * Passed as **positional arguments**.Props
* Attributes that affect the behavior and appearance of a component. * Passed as **keyword arguments**.Displaying data that changes over time
Apps need to store and display data that changes over time. Reflex handles this through State, which is a Python class that stores variables that can change when the app is running, as well as the functions that can change those variables.
To define a state class, subclass rx.State
and define fields that store the state of your app. The state variables (vars) should have a type annotation, and can be initialized with a default value.
Referencing state vars in components
To reference a state var in a component, you can pass it as a child or prop. The component will automatically update when the state changes.
Vars are referenced through class attributes on your state class. For example, to reference the count
var in a component, use MyState.count
.
Count:
0
Vars can be referenced in multiple components, and will automatically update when the state changes.
Responding to events and updating the screen
So far, we've defined state vars but we haven't shown how to change them. All state changes are handled through functions in the state class, called event handlers.
Components have special props called event triggers, such as on_click
, called event triggers, that can be used to make components interactive. Event triggers connect components to event handlers, which update the state.
0
When an event trigger is activated, the event handler is called, which updates the state. The UI is automatically re-rendered to reflect the new state.
Event handlers with arguments
Event handlers can also take in arguments. For example, the increment
event handler can take an argument to increment the count by a specific amount.
0
The on_click
event trigger doesn't pass any arguments here, but some event triggers do. For example, the on_blur
event trigger passes the text of an input as an argument to the event handler.
Compile-time vs. runtime (IMPORTANT)
Before we dive deeper into state, it's important to understand the difference between compile-time and runtime in Reflex.
When you run your app, the frontend gets compiled to Javascript code that runs in the browser (compile-time). The backend stays in Python and runs on the server during the lifetime of the app (runtime).
When can you not use pure Python?
We cannot compile arbitrary Python code, only the components that you define. What this means importantly is that you cannot use arbitrary Python operations and functions on state vars in components.
However, since any event handlers in your state are on the backend, you can use any Python code or library within your state.
Examples that work
Within an event handler, use any Python code or library.
even
Use any Python function within components, as long as it is defined at compile time (i.e. does not reference any state var)
Examples that don't work
You cannot do an if
statement on vars in components, since the value is not known at compile time.
You cannot do a for
loop over a list of vars.
You cannot do arbitrary Python operations on state vars in components.
In the next sections, we will show how to handle these cases.
Conditional rendering
As mentioned above, you cannot use Python if/else
statements with state vars in components. Instead, use the rx.cond
function to conditionally render components.
Not Logged In
Rendering lists
To iterate over a var that is a list, use the rx.foreach
function to render a list of components.
Pass the list var and a function that returns a component as arguments to rx.foreach
.
The function that renders each item takes in a Var
, since this will get compiled up front.
Var Operations
You can't use arbitrary Python operations on state vars in components, but Reflex has var operations that you can use to manipulate state vars.
For example, to check if a var is even, you can use the %
and ==
var operations.
Count:
Even
App and Pages
Reflex apps are created by instantiating the rx.App
class. Pages are linked to specific URL routes, and are created by defining a function that returns a component.
Next Steps
Keep exploring the docs to start building your own Reflex app.