Field

Combine labels, controls, and help text to compose accessible form fields and grouped inputs.

Installation

Command to install the Field component.

buridan add field

uv run buridan add field

python -m buridan add field

Component Guide

Use the following to build the Field component.

from components.ui.field import field

field.root(
    field.content(
        field.label(),
        field.title(),
        field.description(),
    ),
    field.error(),
)

Source Code & Dependencies

For manual installation, copy each of the source codes below in their respective locations.

components/core/core.py

components/ui/separator.py

components/ui/field.py

Composition

field.root

A single control with label, helper text, and validation.

field.root
 |- field.label
 |- Input / Textarea / switch.root / select.root
 |- field.description
 \- field.error

field.group

Related fields in one group. Use field.separator between sections when needed.

field.group
 |- field.root
 |   |- field.label
 |   |- Input / Textarea / switch.root / select.root
 |   |- field.description
 |   \- field.error
 |- field.separator
 \- field.root
     |- field.label
     \- Input / Textarea / switch.root / select.root

field.set

Semantic grouping with a legend and description, usually containing a field.group.

field.set
 |- field.legend
 |- field.description
 \- field.group
     |- field.root
     |   |- field.label
     |   |- Input / Textarea / switch.root / select.root
     |   |- field.description
     |   \- field.error
     \- field.root
         |- field.label
         \- Input / Textarea / switch.root / select.root

field.root is the core wrapper for a single field.
field.content is a flex column that groups label and description. Not required if you have no description.
Wrap related fields with field.group, and use field.set with field.legend for semantic grouping.

Examples

General

Demonstrates field.root, field.group, field.set, field.label, field.description, and field.error composed together.

Props used: orientation on field.root; variant on field.legend; html_for on field.label; data_invalid on field.root.

import reflex as rx

from components.ui.button import button
from components.ui.checkbox import checkbox
from components.ui.field import field
from components.ui.input import input

# from components.ui.select import select
from components.ui.textarea import textarea

months = [
    {"label": "MM", "value": ""},
    {"label": "01", "value": "01"},
    {"label": "02", "value": "02"},
    {"label": "03", "value": "03"},
    {"label": "04", "value": "04"},
    {"label": "05", "value": "05"},
    {"label": "06", "value": "06"},
    {"label": "07", "value": "07"},
    {"label": "08", "value": "08"},
    {"label": "09", "value": "09"},
    {"label": "10", "value": "10"},
    {"label": "11", "value": "11"},
    {"label": "12", "value": "12"},
]

years = [
    {"label": "YYYY", "value": ""},
    {"label": "2024", "value": "2024"},
    {"label": "2025", "value": "2025"},
    {"label": "2026", "value": "2026"},
    {"label": "2027", "value": "2027"},
    {"label": "2028", "value": "2028"},
    {"label": "2029", "value": "2029"},
]


def field_demo() -> rx.Component:
    return rx.el.div(
        rx.el.form(
            field.group(
                field.set(
                    field.legend("Payment Method"),
                    field.description("All transactions are secure and encrypted"),
                    field.group(
                        field.root(
                            field.label("Name on Card", html_for="checkout-card-name"),
                            input(
                                id="checkout-card-name",
                                placeholder="Evil Rabbit",
                                required=True,
                            ),
                        ),
                        field.root(
                            field.label("Card Number", html_for="checkout-card-number"),
                            input(
                                id="checkout-card-number",
                                placeholder="1234 5678 9012 3456",
                                required=True,
                            ),
                            field.description("Enter your 16-digit card number"),
                        ),
                        rx.el.div(
                            field.root(
                                field.label("Month", html_for="checkout-exp-month"),
                                # select.root(
                                #     select.trigger(
                                #         select.value(),
                                #         select.icon(),
                                #         id="checkout-exp-month",
                                #     ),
                                #     select.portal(
                                #         select.positioner(
                                #             select.popup(
                                #                 select.group(
                                #                     *[
                                #                         select.item(
                                #                             select.item_text(
                                #                                 item["label"]
                                #                             ),
                                #                             select.item_indicator(),
                                #                             value=item["value"],
                                #                         )
                                #                         for item in months
                                #                     ]
                                #                 )
                                #             )
                                #         )
                                #     ),
                                #     items=months,
                                #     default_value="MM",
                                # ),
                            ),
                            field.root(
                                field.label("Year", html_for="checkout-exp-year"),
                                # select.root(
                                #     select.trigger(
                                #         select.value(),
                                #         select.icon(),
                                #         id="checkout-exp-year",
                                #     ),
                                #     select.portal(
                                #         select.positioner(
                                #             select.popup(
                                #                 select.group(
                                #                     *[
                                #                         select.item(
                                #                             select.item_text(
                                #                                 item["label"]
                                #                             ),
                                #                             select.item_indicator(),
                                #                             value=item["value"],
                                #                         )
                                #                         for item in years
                                #                     ]
                                #                 )
                                #             )
                                #         )
                                #     ),
                                #     items=years,
                                #     default_value="YYYY",
                                # ),
                            ),
                            field.root(
                                field.label("CVV", html_for="checkout-cvv"),
                                input(
                                    id="checkout-cvv",
                                    placeholder="123",
                                    required=True,
                                ),
                            ),
                            class_name="grid grid-cols-3 gap-4",
                        ),
                    ),
                ),
                field.separator(),
                field.set(
                    field.legend("Billing Address"),
                    field.description(
                        "The billing address associated with your payment method"
                    ),
                    field.group(
                        field.root(
                            checkbox.root(
                                checkbox.indicator(),
                                id="checkout-same-as-shipping",
                                default_checked=True,
                            ),
                            field.label(
                                "Same as shipping address",
                                html_for="checkout-same-as-shipping",
                                class_name="font-normal",
                            ),
                            orientation="horizontal",
                        )
                    ),
                ),
                field.set(
                    field.group(
                        field.root(
                            field.label("Comments", html_for="checkout-comments"),
                            textarea(
                                id="checkout-comments",
                                placeholder="Add any additional comments",
                                class_name="resize-none",
                            ),
                        )
                    )
                ),
                field.root(
                    button("Submit", type="submit"),
                    button("Cancel", variant="outline", type="button"),
                    orientation="horizontal",
                ),
            )
        ),
        class_name="w-full max-w-md my-10",
    )

Responsive Layout

Vertical fields: Default orientation stacks label, control, and helper text—ideal for mobile-first layouts.
Horizontal fields: Set orientation="horizontal" on field.root to align the label and control side-by-side. Pair with field.content to keep descriptions aligned.
Responsive fields: Set orientation="responsive" for automatic column layouts inside container-aware parents.

Validation and Errors

Add data_invalid="true" to field.root to switch the entire block into an error state.
Add aria_invalid="true" on the input itself for assistive technologies.
Render field.error immediately after the control or inside field.content to keep error messages aligned with the field.

field.root(
    field.label("Email", html_for="email"),
    input(id="email", type="email", aria_invalid="true"),
    field.error("Enter a valid email address."),
    data_invalid="true",
)

API Reference

field.set

Container that renders a semantic fieldset with spacing presets.

Prop	Type	Default
`class_name`	`str`

field.set(
    field.legend("Delivery"),
    field.group(),
)

field.legend

Legend element for a field.set. Switch to the "label" variant to align with standard label sizing.

Prop	Type	Default
`variant`	`Literal["legend", "label"]`	`"legend"`
`class_name`	`str`

field.legend("Notification Preferences", variant="label")

The field.legend has two variants: legend and label. The label variant applies standard input label sizing and alignment, which is useful if you are stacking nested fieldsets.

field.group

Layout wrapper that stacks field.root components and enables container queries for responsive orientations.

Prop	Type	Default
`class_name`	`str`

field.group(
    field.root(),
    field.root(),
    class_name="@container/field-group flex flex-col gap-6",
)

field.root

The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing configurations.

| Prop | Type | Default | | -------------- | ----------- | ------------ | ------------- | ------------ | | orientation | "vertical" | "horizontal" | "responsive" | "vertical" | | class_name | str | | | data_invalid | str | |

field.root(
    field.label("Remember me", html_for="remember"),
    switch.root(id="remember"),
    orientation="horizontal",
)

field.content

Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no layout description block.

Prop	Type	Default
`class_name`	`str`

field.root(
    checkbox.root(id="notifications"),
    field.content(
        field.label("Notifications", html_for="notifications"),
        field.description("Email, SMS, and push options."),
    ),
)

field.label

Label styled for both direct inputs and nested field child items.

Prop	Type	Default
`html_for`	`str`
`class_name`	`str`

field.label("Email", html_for="email")

field.title

Renders a standalone title with matching label typography properties inside a field.content node block.

Prop	Type	Default
`class_name`	`str`

field.content(
    field.title("Enable Touch ID"),
    field.description("Unlock your device faster."),
)

field.description

Helper text slot that automatically line-balances lengthy strings cleanly when utilized inside horizontal configurations.

Prop	Type	Default
`class_name`	`str`

field.description("We never share your email with anyone.")

field.separator

Visual divider rule used to separate sections or categories inside a wrapping field.group component. Accepts optional inline children contents.

Prop	Type	Default
`class_name`	`str`

field.separator("Or continue with")

field.error

Accessible error notification typography container block configured automatically with standard application state layout variables (role="alert").

Prop	Type	Default
`class_name`	`str`

field.error("Invalid passcode combination provided.")