Skip to content

Components API Reference

This page contains the API reference for component classes and form components that are bundled with Starlette-Templates. All components are built using Pydantic models for type safety and validation.

The base class for all components is ComponentModel. All components extend this class and define their own properties and templates. Components must specify a template property that points to the Jinja2 template used for rendering. The template path is relative to the template loaders configured in the Jinja environment in JinjaMiddleware. The Jinja2 template can access all properties defined on the component model.

ComponentModel

Base class for renderable UI components. Components should inherit from this class.

Components are rendered using Jinja2 templates, which can be organized and loaded via the application's Jinja2 environment template loaders configured in JinjaMiddleware.

class HeaderComponent(ComponentModel):
    template: str = "components/header.html"
    title: str
    subtitle: str

header = HeaderComponent(title="Welcome", subtitle="Enjoy your stay")
rendered_html = await header.render(request)

The context method can be overridden to provide custom context data for the Jinja templates.

class UserCardComponent(ComponentModel):
    template: str = "components/user_card.html"
    user_id: int

    def context(self) -> dict[str, t.Any]:
        user = get_user_from_db(self.user_id)
        return {"user": user}

user_card = UserCardComponent(user_id=42)
rendered_html = await user_card.render(request)

Attributes:

  • id (str) –

    Unique identifier for this component. Auto-generated by default.

  • template (str) –

    Path to the Jinja2 template used to render this component. Required.

Methods:

  • prepare_field_params –

    Transform form field params before component instantiation.

  • context –

    Context variables to set in parent template when this component is used.

  • render –

    Render this component to HTML.

model_config class-attribute instance-attribute 

model_config = ConfigDict(
    arbitrary_types_allowed=True, extra="allow"
)

id class-attribute instance-attribute 

id: str = Field(default_factory=generate_component_id)

Unique identifier for this component. Auto-generated by default.

template instance-attribute 

template: str

Path to the Jinja2 template used to render this component.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Transform form field params before component instantiation.

Override in subclasses that need special handling when used with FormModel. For example, Select components need to convert choices to SelectOption objects, and Checkbox components need to set checked state from the field value.

By default, this method sets the 'value' param to the field value.

Parameters:

  • params (dict[str, Any]) –

    Parameters from the form field's json_schema_extra

  • field_value (Any) –

    The current value of the form field

Returns:

  • dict[str, Any] –

    Modified params dict ready for component instantiation

context 

context(
    jinja_context: dict[str, Any], request: Request
) -> dict[str, Any]

Context variables to set in parent template when this component is used.

Override this method to set context variables that should be available to the parent template. For example, components can set library inclusion flags like include_datatables or any other context variables.

Parameters:

  • jinja_context (dict[str, Any]) –

    The current Jinja2 rendering context

  • request (Request) –

    The Starlette Request object

Returns:

  • dict[str, Any] –

    Dictionary of context variables to merge into parent template context

render async 

render(request: Request, **kwargs) -> Markup

Render this component to HTML.

Form Components

These components are designed to work with the FormModel for building Pydantic-based forms with validation and rendering.

Input

Bootstrap form input component.

Methods:

Attributes:

  • template (str) –

    Bootstrap input form control component.

  • name (str) –

    Input name attribute.

  • label (str | None) –

    Input label.

  • type (str) –

    Input type, e.g., text, email, password, number, tel, url, etc.

  • value (str | None) –

    Input value.

  • placeholder (str | None) –

    Placeholder text.

  • help_text (str | None) –

    Help text below input.

  • required (bool) –

    Whether the input is required.

  • disabled (bool) –

    Whether the input is disabled.

  • readonly (bool) –

    Whether the input is readonly.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

  • prepend (str | None) –

    Prepend text/icon to input.

  • append (str | None) –

    Append text/icon to input.

  • size (str | None) –

    Input size: sm, lg.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/input.html", frozen=True
)

Bootstrap input form control component.

name class-attribute instance-attribute 

name: str = Field(..., description='Input name attribute')

Input name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Input label"
)

Input label.

type class-attribute instance-attribute 

type: str = Field(
    default="text",
    description="Input type: text, email, password, number, tel, url, etc.",
)

Input type, e.g., text, email, password, number, tel, url, etc.

value class-attribute instance-attribute 

value: str | None = Field(
    default=None, description="Input value"
)

Input value.

placeholder class-attribute instance-attribute 

placeholder: str | None = Field(
    default=None, description="Placeholder text"
)

Placeholder text.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below input"
)

Help text below input.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the input is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled input"
)

Whether the input is disabled.

readonly class-attribute instance-attribute 

readonly: bool = Field(
    default=False, description="Readonly input"
)

Whether the input is readonly.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepend class-attribute instance-attribute 

prepend: str | None = Field(
    default=None, description="Prepend text/icon to input"
)

Prepend text/icon to input.

append class-attribute instance-attribute 

append: str | None = Field(
    default=None, description="Append text/icon to input"
)

Append text/icon to input.

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Input size: sm, lg"
)

Input size: sm, lg.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Convert field value to string for input element.

Textarea

Bootstrap textarea component.

Methods:

Attributes:

  • template (str) –

    Bootstrap textarea component template.

  • name (str) –

    Textarea name attribute.

  • label (str | None) –

    Textarea label.

  • value (str | None) –

    Textarea value.

  • placeholder (str | None) –

    Placeholder text.

  • help_text (str | None) –

    Help text below textarea.

  • rows (int) –

    Number of rows.

  • required (bool) –

    Whether the textarea is required.

  • disabled (bool) –

    Whether the textarea is disabled.

  • readonly (bool) –

    Whether the textarea is readonly.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/textarea.html", frozen=True
)

Bootstrap textarea component template.

name class-attribute instance-attribute 

name: str = Field(
    ..., description="Textarea name attribute"
)

Textarea name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Textarea label"
)

Textarea label.

value class-attribute instance-attribute 

value: str | None = Field(
    default=None, description="Textarea value"
)

Textarea value.

placeholder class-attribute instance-attribute 

placeholder: str | None = Field(
    default=None, description="Placeholder text"
)

Placeholder text.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below textarea"
)

Help text below textarea.

rows class-attribute instance-attribute 

rows: int = Field(default=3, description='Number of rows')

Number of rows.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the textarea is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled textarea"
)

Whether the textarea is disabled.

readonly class-attribute instance-attribute 

readonly: bool = Field(
    default=False, description="Readonly textarea"
)

Whether the textarea is readonly.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Convert field value to string for textarea element.

Select

Bootstrap select dropdown component.

Methods:

Attributes:

  • template (str) –

    Bootstrap select dropdown component template.

  • name (str) –

    Select name attribute.

  • label (str | None) –

    Select label.

  • options (list[SelectOption]) –

    Select options.

  • help_text (str | None) –

    Help text below select.

  • required (bool) –

    Whether the select is required.

  • disabled (bool) –

    Whether the select is disabled.

  • multiple (bool) –

    Allow multiple selections.

  • size (str | None) –

    Select size: sm, lg.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/select.html", frozen=True
)

Bootstrap select dropdown component template.

name class-attribute instance-attribute 

name: str = Field(..., description='Select name attribute')

Select name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Select label"
)

Select label.

options class-attribute instance-attribute 

options: list[SelectOption] = Field(
    default_factory=list, description="Select options"
)

Select options.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below select"
)

Help text below select.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the select is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled select"
)

Whether the select is disabled.

multiple class-attribute instance-attribute 

multiple: bool = Field(
    default=False, description="Allow multiple selections"
)

Allow multiple selections.

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Select size: sm, lg"
)

Select size: sm, lg.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Convert choices to SelectOption objects with proper selected state.

Checkbox

Bootstrap checkbox component.

Methods:

Attributes:

  • template (str) –

    Bootstrap checkbox component template.

  • name (str) –

    Checkbox name attribute.

  • label (str) –

    Checkbox label.

  • value (str) –

    Checkbox value.

  • checked (bool) –

    Checked state.

  • disabled (bool) –

    Whether the checkbox is disabled.

  • inline (bool) –

    Display inline.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/checkbox.html", frozen=True
)

Bootstrap checkbox component template.

name class-attribute instance-attribute 

name: str = Field(
    ..., description="Checkbox name attribute"
)

Checkbox name attribute.

label class-attribute instance-attribute 

label: str = Field(..., description='Checkbox label')

Checkbox label.

value class-attribute instance-attribute 

value: str = Field(
    default="1", description="Checkbox value"
)

Checkbox value.

checked class-attribute instance-attribute 

checked: bool = Field(
    default=False, description="Checked state"
)

Checked state.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled checkbox"
)

Whether the checkbox is disabled.

inline class-attribute instance-attribute 

inline: bool = Field(
    default=False, description="Display inline"
)

Display inline.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Set checked state from field value instead of using value.

Radio

Bootstrap radio button component.

Attributes:

  • template (str) –

    Bootstrap radio button component template.

  • name (str) –

    Radio name attribute (same for group).

  • label (str) –

    Radio label.

  • value (str) –

    Radio value.

  • checked (bool) –

    Checked state.

  • disabled (bool) –

    Whether the radio is disabled.

  • inline (bool) –

    Display inline.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/radio.html", frozen=True
)

Bootstrap radio button component template.

name class-attribute instance-attribute 

name: str = Field(
    ..., description="Radio name attribute (same for group)"
)

Radio name attribute (same for group).

label class-attribute instance-attribute 

label: str = Field(..., description='Radio label')

Radio label.

value class-attribute instance-attribute 

value: str = Field(..., description='Radio value')

Radio value.

checked class-attribute instance-attribute 

checked: bool = Field(
    default=False, description="Checked state"
)

Checked state.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled radio"
)

Whether the radio is disabled.

inline class-attribute instance-attribute 

inline: bool = Field(
    default=False, description="Display inline"
)

Display inline.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

Switch

Bootstrap switch component (styled checkbox).

Attributes:

  • template (str) –

    Bootstrap switch component template.

  • name (str) –

    Switch name attribute.

  • label (str) –

    Switch label.

  • value (str) –

    Switch value.

  • checked (bool) –

    Checked state.

  • disabled (bool) –

    Whether the switch is disabled.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/switch.html", frozen=True
)

Bootstrap switch component template.

name class-attribute instance-attribute 

name: str = Field(..., description='Switch name attribute')

Switch name attribute.

label class-attribute instance-attribute 

label: str = Field(..., description='Switch label')

Switch label.

value class-attribute instance-attribute 

value: str = Field(default='1', description='Switch value')

Switch value.

checked class-attribute instance-attribute 

checked: bool = Field(
    default=False, description="Checked state"
)

Checked state.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled switch"
)

Whether the switch is disabled.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

FileInput

Bootstrap file input component.

Attributes:

  • template (str) –

    Bootstrap file input component template.

  • name (str) –

    File input name attribute.

  • label (str | None) –

    File input label.

  • help_text (str | None) –

    Help text below input.

  • required (bool) –

    Whether the file input is required.

  • disabled (bool) –

    Whether the file input is disabled.

  • multiple (bool) –

    Allow multiple files.

  • accept (str | None) –

    Accepted file types (e.g., 'image/*').

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/file_input.html", frozen=True
)

Bootstrap file input component template.

name class-attribute instance-attribute 

name: str = Field(
    ..., description="File input name attribute"
)

File input name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="File input label"
)

File input label.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below input"
)

Help text below input.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the file input is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled input"
)

Whether the file input is disabled.

multiple class-attribute instance-attribute 

multiple: bool = Field(
    default=False, description="Allow multiple files"
)

Allow multiple files.

accept class-attribute instance-attribute 

accept: str | None = Field(
    default=None,
    description="Accepted file types (e.g., 'image/*')",
)

Accepted file types (e.g., 'image/*').

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

Range

Bootstrap range slider component.

Attributes:

  • template (str) –

    Bootstrap range slider component template.

  • name (str) –

    Range name attribute.

  • label (str | None) –

    Range label.

  • min (float) –

    Minimum value.

  • max (float) –

    Maximum value.

  • step (float) –

    Step increment.

  • value (float) –

    Current value.

  • disabled (bool) –

    Whether the range is disabled.

  • help_text (str | None) –

    Help text below range.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/range.html", frozen=True
)

Bootstrap range slider component template.

name class-attribute instance-attribute 

name: str = Field(..., description='Range name attribute')

Range name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Range label"
)

Range label.

min class-attribute instance-attribute 

min: float = Field(default=0, description='Minimum value')

Minimum value.

max class-attribute instance-attribute 

max: float = Field(default=100, description="Maximum value")

Maximum value.

step class-attribute instance-attribute 

step: float = Field(default=1, description="Step increment")

Step increment.

value class-attribute instance-attribute 

value: float = Field(
    default=50, description="Current value"
)

Current value.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled range"
)

Whether the range is disabled.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below range"
)

Help text below range.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

ChoicesSelect

Choices.js enhanced select component.

Methods:

Attributes:

  • id (str) –

    Element ID for the select.

  • template (str) –

    Choices.js select component template.

  • name (str) –

    Select name attribute.

  • label (str | None) –

    Select label.

  • options (list[ChoiceOption | ChoiceGroup]) –

    Select options or option groups.

  • placeholder (str) –

    Placeholder text.

  • search_enabled (bool) –

    Enable search functionality.

  • search_placeholder (str) –

    Search placeholder.

  • multiple (bool) –

    Allow multiple selections.

  • remove_button (bool) –

    Show remove button for selected items.

  • max_item_count (int | None) –

    Max items that can be selected (for multiple).

  • help_text (str | None) –

    Help text below select.

  • required (bool) –

    Whether the select is required.

  • disabled (bool) –

    Whether the select is disabled.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

id instance-attribute 

id: str

Element ID for the select.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/choices_select.html", frozen=True
)

Choices.js select component template.

name class-attribute instance-attribute 

name: str = Field(..., description='Select name attribute')

Select name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Select label"
)

Select label.

options class-attribute instance-attribute 

options: list[ChoiceOption | ChoiceGroup] = Field(
    default_factory=list
)

Select options or option groups.

placeholder class-attribute instance-attribute 

placeholder: str = Field(
    default="Select an option",
    description="Placeholder text",
)

Placeholder text.

search_enabled class-attribute instance-attribute 

search_enabled: bool = Field(
    default=True, description="Enable search functionality"
)

Enable search functionality.

search_placeholder class-attribute instance-attribute 

search_placeholder: str = Field(
    default="Type to search",
    description="Search placeholder",
)

Search placeholder.

multiple class-attribute instance-attribute 

multiple: bool = Field(
    default=False, description="Allow multiple selections"
)

Allow multiple selections.

remove_button class-attribute instance-attribute 

remove_button: bool = Field(
    default=True,
    description="Show remove button for selected items",
)

Show remove button for selected items.

max_item_count class-attribute instance-attribute 

max_item_count: int | None = Field(
    default=None,
    description="Max items that can be selected (for multiple)",
)

Max items that can be selected (for multiple).

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below select"
)

Help text below select.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the select is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled select"
)

Whether the select is disabled.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Convert choices to ChoiceOption objects with proper selected state.

DatePicker

Flatpickr date picker component.

Methods:

Attributes:

  • id (str) –

    Element ID for the date picker.

  • template (str) –

    Flatpickr date picker component template.

  • name (str) –

    Input name attribute.

  • label (str | None) –

    Input label.

  • value (str | None) –

    Initial date value (YYYY-MM-DD).

  • placeholder (str | None) –

    Placeholder text.

  • mode (str) –

    Selection mode: single, multiple, range.

  • enable_time (bool) –

    Enable time picker.

  • time_24hr (bool) –

    Use 24-hour time format.

  • date_format (str) –

    Date format string.

  • min_date (str | None) –

    Minimum selectable date.

  • max_date (str | None) –

    Maximum selectable date.

  • disable_dates (list[str]) –

    Dates to disable.

  • inline (bool) –

    Display calendar inline.

  • help_text (str | None) –

    Help text below input.

  • required (bool) –

    Whether the date picker is required.

  • disabled (bool) –

    Whether the date picker is disabled.

  • validation_state (str | None) –

    Validation state: valid, invalid.

  • validation_message (str | None) –

    Validation feedback message.

id instance-attribute 

id: str

Element ID for the date picker.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/datepicker.html", frozen=True
)

Flatpickr date picker component template.

name class-attribute instance-attribute 

name: str = Field(..., description='Input name attribute')

Input name attribute.

label class-attribute instance-attribute 

label: str | None = Field(
    default=None, description="Input label"
)

Input label.

value class-attribute instance-attribute 

value: str | None = Field(
    default=None,
    description="Initial date value (YYYY-MM-DD)",
)

Initial date value (YYYY-MM-DD).

placeholder class-attribute instance-attribute 

placeholder: str | None = Field(
    default="Select date", description="Placeholder text"
)

Placeholder text.

mode class-attribute instance-attribute 

mode: str = Field(
    default="single",
    description="Selection mode: single, multiple, range",
)

Selection mode: single, multiple, range.

enable_time class-attribute instance-attribute 

enable_time: bool = Field(
    default=False, description="Enable time picker"
)

Enable time picker.

time_24hr class-attribute instance-attribute 

time_24hr: bool = Field(
    default=True, description="Use 24-hour time format"
)

Use 24-hour time format.

date_format class-attribute instance-attribute 

date_format: str = Field(
    default="Y-m-d", description="Date format string"
)

Date format string.

min_date class-attribute instance-attribute 

min_date: str | None = Field(
    default=None, description="Minimum selectable date"
)

Minimum selectable date.

max_date class-attribute instance-attribute 

max_date: str | None = Field(
    default=None, description="Maximum selectable date"
)

Maximum selectable date.

disable_dates class-attribute instance-attribute 

disable_dates: list[str] = Field(
    default_factory=list, description="Dates to disable"
)

Dates to disable.

inline class-attribute instance-attribute 

inline: bool = Field(
    default=False, description="Display calendar inline"
)

Display calendar inline.

help_text class-attribute instance-attribute 

help_text: str | None = Field(
    default=None, description="Help text below input"
)

Help text below input.

required class-attribute instance-attribute 

required: bool = Field(
    default=False, description="Required field"
)

Whether the date picker is required.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled input"
)

Whether the date picker is disabled.

validation_state class-attribute instance-attribute 

validation_state: str | None = Field(
    default=None,
    description="Validation state: valid, invalid",
)

Validation state: valid, invalid.

validation_message class-attribute instance-attribute 

validation_message: str | None = Field(
    default=None, description="Validation feedback message"
)

Validation feedback message.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Convert date/datetime values to ISO string format.

SubmitButton

Bootstrap submit button component for forms.

Methods:

Attributes:

  • template (str) –

    Bootstrap submit button component template.

  • text (str) –

    Button text.

  • button_type (str) –

    Button type: submit, button, reset.

  • name (str | None) –

    Button name attribute.

  • classes (list[str]) –

    CSS classes.

  • disabled (bool) –

    Whether the button is disabled.

  • form (str | None) –

    Form element the button is associated with.

  • formaction (str | None) –

    URL where form data is sent.

  • formenctype (str | None) –

    How form data is encoded.

  • formmethod (str | None) –

    HTTP method when button is clicked.

  • formnovalidate (bool) –

    Whether to bypass form validation.

  • formtarget (str | None) –

    Where to display response.

template class-attribute instance-attribute 

template: str = Field(
    "components/forms/submit_button.html", frozen=True
)

Bootstrap submit button component template.

text class-attribute instance-attribute 

text: str = Field(
    default="Submit", description="Button text"
)

Button text.

button_type class-attribute instance-attribute 

button_type: str = Field(
    default="submit",
    description="Button type: submit, button, reset",
)

Button type: submit, button, reset.

name class-attribute instance-attribute 

name: str | None = Field(
    default=None, description="Button name attribute"
)

Button name attribute.

classes class-attribute instance-attribute 

classes: list[str] = Field(
    default_factory=lambda: ["btn", "btn-primary"],
    description="CSS classes",
)

CSS classes.

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled button"
)

Whether the button is disabled.

form class-attribute instance-attribute 

form: str | None = Field(
    default=None,
    description="Form element the button is associated with",
)

Form element the button is associated with.

formaction class-attribute instance-attribute 

formaction: str | None = Field(
    default=None, description="URL where form data is sent"
)

URL where form data is sent.

formenctype class-attribute instance-attribute 

formenctype: str | None = Field(
    default=None, description="How form data is encoded"
)

How form data is encoded.

formmethod class-attribute instance-attribute 

formmethod: str | None = Field(
    default=None,
    description="HTTP method when button is clicked",
)

HTTP method when button is clicked.

formnovalidate class-attribute instance-attribute 

formnovalidate: bool = Field(
    default=False,
    description="Whether to bypass form validation",
)

Whether to bypass form validation.

formtarget class-attribute instance-attribute 

formtarget: str | None = Field(
    default=None, description="Where to display response"
)

Where to display response.

prepare_field_params classmethod 

prepare_field_params(
    params: dict[str, Any], field_value: Any
) -> dict[str, Any]

Submit buttons don't use field values.

Bootstrap Components

Bootstrap components are UI elements styled with Bootstrap 5.3. These components cover layout, navigation, feedback, and interactivity.

For a comprehensive guide with examples and links to Bootstrap documentation, see the Bootstrap Components Guide.

Container

Bootstrap container component.

Example 
container = Container(content="<h1>Trail Map</h1>")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/container.html", frozen=True
)

fluid class-attribute instance-attribute 

fluid: bool = Field(
    default=False,
    description="Use container-fluid instead of container",
)

content class-attribute instance-attribute 

content: Content = Field(
    default="",
    description="HTML string, component, or list of components",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

Row

Bootstrap row component for grid layout.

Example 
row = Row(content=[
    Col(md=6, content="Tent"),
    Col(md=6, content="Sleeping Bag")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/row.html", frozen=True
)

content class-attribute instance-attribute 

content: Content = Field(
    default="",
    description="HTML string, component, or list of components",
)

gap class-attribute instance-attribute 

gap: int | None = Field(
    default=None,
    ge=0,
    le=5,
    description="Gap between children (Bootstrap spacing 0-5)",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

Col

Bootstrap column component for grid layout.

Example 
col = Col(md=6, content="Backpack")

Attributes:

  • template (str) –
  • content (Content) –
  • xs (int | None) –
  • sm (int | None) –
  • md (int | None) –
  • lg (int | None) –
  • xl (int | None) –
  • xxl (int | None) –
  • classes (str) –

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/col.html", frozen=True
)

content class-attribute instance-attribute 

content: Content = Field(
    default="",
    description="HTML string, component, or list of components",
)

xs class-attribute instance-attribute 

xs: int | None = Field(
    default=None,
    description="Column width on extra small screens",
)

sm class-attribute instance-attribute 

sm: int | None = Field(
    default=None,
    description="Column width on small screens",
)

md class-attribute instance-attribute 

md: int | None = Field(
    default=None,
    description="Column width on medium screens",
)

lg class-attribute instance-attribute 

lg: int | None = Field(
    default=None,
    description="Column width on large screens",
)

xl class-attribute instance-attribute 

xl: int | None = Field(
    default=None,
    description="Column width on extra large screens",
)

xxl class-attribute instance-attribute 

xxl: int | None = Field(
    default=None,
    description="Column width on extra extra large screens",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

Grid

CSS Grid component for simplified grid layouts.

Example 
grid = Grid(cols=3, content="<div>Tent</div><div>Stove</div><div>Lamp</div>")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/grid.html", frozen=True
)

cols class-attribute instance-attribute 

cols: int = Field(
    default=12,
    ge=1,
    le=12,
    description="Number of columns in the grid (1-12)",
)

gap class-attribute instance-attribute 

gap: int = Field(
    default=3,
    ge=0,
    le=5,
    description="Gap between grid items (0-5)",
)

content class-attribute instance-attribute 

content: Content = Field(
    default="",
    description="HTML content or component inside grid",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

Card

Bootstrap card component.

Example 
card = Card(title="Mountain Trail", content="5.2 miles, moderate")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/card.html", frozen=True
)

title class-attribute instance-attribute 

title: str | None = Field(
    default=None, description="Card header title"
)

content class-attribute instance-attribute 

content: Content = Field(
    default="",
    description="Card body content (HTML or component)",
)

footer class-attribute instance-attribute 

footer: Content | None = Field(
    default=None,
    description="Card footer content (HTML or component)",
)

header_classes class-attribute instance-attribute 

header_classes: str = Field(
    default="",
    description="Additional classes for card header",
)

body_classes class-attribute instance-attribute 

body_classes: str = Field(
    default="",
    description="Additional classes for card body",
)

footer_classes class-attribute instance-attribute 

footer_classes: str = Field(
    default="",
    description="Additional classes for card footer",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="",
    description="Additional classes for card wrapper",
)

Navbar

Bootstrap navbar component.

Example 
navbar = Navbar(
    brand="Trail Guide",
    links=[
        NavLink(label="Trails", href="/", active=True),
        NavDropdown(label="Gear", items=[
            NavLink(label="Tents", href="/tents"),
            NavLink(label="Backpacks", href="/packs")
        ]),
        NavLink(label="Camps", href="/camps")
    ]
)

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/navbar.html", frozen=True
)

brand class-attribute instance-attribute 

brand: str | None = Field(
    default=None, description="Brand text"
)

brand_href class-attribute instance-attribute 

brand_href: str = Field(
    default="/", description="Brand link URL"
)

brand_icon class-attribute instance-attribute 

brand_icon: str | None = Field(
    default=None, description="Brand icon class"
)

links: list[NavLink | NavDropdown] = Field(
    default_factory=list
)

theme class-attribute instance-attribute 

theme: str = Field(
    default="light", description="Navbar theme: light, dark"
)

bg_color class-attribute instance-attribute 

bg_color: str = Field(
    default="light",
    description="Background color class: primary, secondary, light, dark, etc.",
)

expand class-attribute instance-attribute 

expand: str = Field(
    default="lg",
    description="Breakpoint to expand navbar: sm, md, lg, xl, xxl",
)

fixed class-attribute instance-attribute 

fixed: str | None = Field(
    default=None, description="Fixed position: top, bottom"
)

sticky class-attribute instance-attribute 

sticky: bool = Field(
    default=False, description="Sticky top navbar"
)

Sidebar

Bootstrap offcanvas sidebar component.

Example 
sidebar = Sidebar(
    title="Trails",
    links=[
        NavLink(label="Hiking", href="/hike"),
        NavLink(label="Camping", href="/camp")
    ]
)

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/sidebar.html", frozen=True
)

title class-attribute instance-attribute 

title: str | None = Field(
    default=None, description="Sidebar title"
)

links: list[NavLink | NavDropdown] = Field(
    default_factory=list
)

placement class-attribute instance-attribute 

placement: str = Field(
    default="start",
    description="Sidebar placement: start, end, top, bottom",
)

backdrop class-attribute instance-attribute 

backdrop: bool = Field(
    default=True, description="Show backdrop overlay"
)

scroll class-attribute instance-attribute 

scroll: bool = Field(
    default=False,
    description="Allow body scrolling while offcanvas is open",
)

SidebarButton

Button component to toggle a Sidebar.

Example 
sidebar_button = SidebarButton(target_id="nav", text="Menu")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/sidebar_button.html", frozen=True
)

target_id class-attribute instance-attribute 

target_id: str = Field(
    ..., description="ID of the sidebar to toggle"
)

text class-attribute instance-attribute 

text: str = Field(default="Menu", description="Button text")

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary", description="Button variant"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default="bi-list", description="Button icon"
)

Breadcrumb

Bootstrap breadcrumb component.

Example 
breadcrumb = Breadcrumb(items=[
    BreadcrumbItem(label="Trails", href="/"),
    BreadcrumbItem(label="Mountain", active=True)
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/breadcrumb.html", frozen=True
)

items class-attribute instance-attribute 

items: list[BreadcrumbItem] = Field(default_factory=list)

SubNav

Dashboard sub-navigation component with links.

Example 
subnav = SubNav(links=[
    SubNavLink(label="Trails", href="/trails", active=True),
    SubNavLink(label="Gear", href="/gear")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/subnav.html", frozen=True
)

links: list[SubNavLink] = Field(
    default_factory=list, description="Navigation links"
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

dropdown_label class-attribute instance-attribute 

dropdown_label: str | None = Field(
    default=None,
    description="Custom label for mobile dropdown menu",
)

Badge

Bootstrap badge component.

Example 
badge = Badge(content="Easy", variant="success")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/badge.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(..., description='Badge text')

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary",
    description="Badge variant: primary, secondary, success, danger, warning, info, light, dark",
)

pill class-attribute instance-attribute 

pill: bool = Field(
    default=False, description="Pill-shaped badge"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None, description="Bootstrap icon class"
)

Button

Bootstrap button component.

Example 
button = Button(content="Start Hike", variant="primary")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/button.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(..., description='Button text')

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary", description="Button variant"
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Button size: sm, lg"
)

outline class-attribute instance-attribute 

outline: bool = Field(
    default=False, description="Outline button style"
)

disabled class-attribute instance-attribute 

disabled: bool = Field(
    default=False, description="Disabled button"
)

href class-attribute instance-attribute 

href: str | None = Field(
    default=None,
    description="Link URL (renders as <a> tag)",
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None, description="Bootstrap icon class"
)

icon_position class-attribute instance-attribute 

icon_position: str = Field(
    default="left", description="Icon position: left, right"
)

block class-attribute instance-attribute 

block: bool = Field(
    default=False, description="Block-level button"
)

Tag

Tag/chip component (badge variant).

Example 
tag = Tag(content="Mountain", variant="info")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/tag.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(..., description='Tag text')

variant class-attribute instance-attribute 

variant: str = Field(
    default="secondary", description="Tag variant"
)

removable class-attribute instance-attribute 

removable: bool = Field(
    default=False, description="Show remove button"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None, description="Bootstrap icon class"
)

ListGroup

Bootstrap list group component.

Example 
list_group = ListGroup(items=[
    ListGroupItem(text="Tent", active=True),
    ListGroupItem(text="Sleeping Bag"),
    ListGroupItem(text="Backpack")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/list_group.html", frozen=True
)

items class-attribute instance-attribute 

items: list[ListGroupItem] = Field(
    ..., description="List items"
)

flush class-attribute instance-attribute 

flush: bool = Field(
    default=False,
    description="Remove borders and rounded corners",
)

numbered class-attribute instance-attribute 

numbered: bool = Field(
    default=False, description="Numbered list"
)

horizontal class-attribute instance-attribute 

horizontal: str | None = Field(
    default=None,
    description="Horizontal at breakpoint: sm, md, lg, xl, xxl",
)

Carousel

Bootstrap carousel component.

Example 
carousel = Carousel(
    id="trails",
    items=[
        CarouselItem(image_url="/mountain.jpg", active=True),
        CarouselItem(image_url="/forest.jpg")
    ]
)

Attributes:

id instance-attribute 

id: str

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/carousel.html", frozen=True
)

items class-attribute instance-attribute 

items: list[CarouselItem] = Field(
    ..., description="Carousel slides"
)

controls class-attribute instance-attribute 

controls: bool = Field(
    default=True, description="Show prev/next controls"
)

indicators class-attribute instance-attribute 

indicators: bool = Field(
    default=True, description="Show slide indicators"
)

auto_play class-attribute instance-attribute 

auto_play: bool = Field(
    default=True, description="Auto-advance slides"
)

interval class-attribute instance-attribute 

interval: int = Field(
    default=5000,
    description="Auto-play interval in milliseconds",
)

fade class-attribute instance-attribute 

fade: bool = Field(
    default=False,
    description="Fade transition instead of slide",
)

PageHeader

Page header with title and optional subtitle.

Example 
page_header = PageHeader(title="Trail Guide", subtitle="Find your next adventure")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/page_header.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Page title (h1)')

subtitle class-attribute instance-attribute 

subtitle: str | None = Field(
    default=None,
    description="Subtitle text (lead paragraph)",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

FilterBar

Sticky horizontal filter bar showing selected filter values.

Example 
filter_bar = FilterBar(items=[
    FilterItem(label="Difficulty", value="Easy"),
    FilterItem(label="Distance", value="< 5 miles")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/filter_bar.html", frozen=True
)

items class-attribute instance-attribute 

items: list[FilterItem] = Field(
    default_factory=list,
    description="Filter items to display",
)

sticky class-attribute instance-attribute 

sticky: bool = Field(
    default=True,
    description="Make the bar sticky on scroll",
)

classes class-attribute instance-attribute 

classes: str = Field(
    default="", description="Additional CSS classes"
)

Alert

Bootstrap alert component.

Example 
alert = Alert(content="Trail closed for maintenance", variant="warning")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/alert.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Alert message content"
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="info",
    description="Alert variant: primary, secondary, success, danger, warning, info, light, dark",
)

dismissible class-attribute instance-attribute 

dismissible: bool = Field(
    default=False, description="Show close button"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None,
    description="Bootstrap icon class to display",
)

heading class-attribute instance-attribute 

heading: str | None = Field(
    default=None, description="Alert heading"
)

Toast

Bootstrap toast notification component.

Example 
toast = Toast(title="Weather Alert", content="Rain expected at 3pm", variant="info")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/toast.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Toast title')

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Toast message content"
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="info",
    description="Toast variant: primary, secondary, success, danger, warning, info, light, dark",
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None,
    description="Bootstrap icon class to display",
)

autohide class-attribute instance-attribute 

autohide: bool = Field(
    default=True, description="Auto hide the toast"
)

delay class-attribute instance-attribute 

delay: int = Field(
    default=5000,
    description="Auto hide delay in milliseconds",
)

position class-attribute instance-attribute 

position: str = Field(
    default="top-end",
    description="Toast position: top-start, top-center, top-end, middle-start, middle-center, middle-end, bottom-start, bottom-center, bottom-end",
)

show_time class-attribute instance-attribute 

show_time: bool = Field(
    default=True, description="Show timestamp"
)

Modal

Bootstrap modal dialog component.

Example 
modal = Modal(title="Trail Info", content="<p>Rocky terrain, bring boots</p>")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/modal.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Modal title')

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Modal body content (HTML)"
)

footer class-attribute instance-attribute 

footer: str | None = Field(
    default=None, description="Modal footer content (HTML)"
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Modal size: sm, lg, xl"
)

centered class-attribute instance-attribute 

centered: bool = Field(
    default=False, description="Vertically center modal"
)

scrollable class-attribute instance-attribute 

scrollable: bool = Field(
    default=False, description="Scrollable modal body"
)

backdrop class-attribute instance-attribute 

backdrop: bool | str = Field(
    default=True,
    description="Show backdrop: True, False, or 'static'",
)

keyboard class-attribute instance-attribute 

keyboard: bool = Field(
    default=True, description="Close modal on Escape key"
)

show_close_button class-attribute instance-attribute 

show_close_button: bool = Field(
    default=True, description="Show close button in header"
)

show_footer: bool = Field(
    default=True, description="Show modal footer"
)

Tooltip

Bootstrap tooltip component.

Example 
tooltip = Tooltip(content="Trail", tooltip_text="5.2 miles")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/tooltip.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Element content (text or HTML)"
)

tooltip_text class-attribute instance-attribute 

tooltip_text: str = Field(..., description='Tooltip text')

placement class-attribute instance-attribute 

placement: str = Field(
    default="top",
    description="Tooltip placement: top, bottom, left, right, auto",
)

trigger class-attribute instance-attribute 

trigger: str = Field(
    default="hover focus",
    description="Trigger events: hover, focus, click",
)

html class-attribute instance-attribute 

html: bool = Field(
    default=False, description="Allow HTML in tooltip"
)

Popover

Bootstrap popover component.

Example 
popover = Popover(content="Info", popover_title="Trail", popover_content="Moderate difficulty")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/popover.html", frozen=True
)

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Element content (text or HTML)"
)

popover_title class-attribute instance-attribute 

popover_title: str | None = Field(
    default=None, description="Popover title"
)

popover_content class-attribute instance-attribute 

popover_content: str = Field(
    ..., description="Popover content"
)

placement class-attribute instance-attribute 

placement: str = Field(
    default="top",
    description="Popover placement: top, bottom, left, right, auto",
)

trigger class-attribute instance-attribute 

trigger: str = Field(
    default="click",
    description="Trigger events: hover, focus, click",
)

html class-attribute instance-attribute 

html: bool = Field(
    default=False, description="Allow HTML in popover"
)

ProgressBar

Bootstrap progress bar component.

Example 
progress = ProgressBar(value=75, variant="success", show_label=True)

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/progress.html", frozen=True
)

value class-attribute instance-attribute 

value: float = Field(
    ..., description="Progress value (0-100)"
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary",
    description="Progress bar variant: primary, secondary, success, danger, warning, info",
)

striped class-attribute instance-attribute 

striped: bool = Field(
    default=False, description="Striped progress bar"
)

animated class-attribute instance-attribute 

animated: bool = Field(
    default=False, description="Animated stripes"
)

show_label class-attribute instance-attribute 

show_label: bool = Field(
    default=False, description="Show percentage label"
)

height class-attribute instance-attribute 

height: str | None = Field(
    default=None, description="Custom height (e.g., '20px')"
)

Spinner

Bootstrap spinner/loader component.

Example 
spinner = Spinner(label="Loading trails...")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/spinner.html", frozen=True
)

type class-attribute instance-attribute 

type: str = Field(
    default="border",
    description="Spinner type: border, grow",
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary",
    description="Spinner variant: primary, secondary, success, danger, warning, info, light, dark",
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Spinner size: sm"
)

label class-attribute instance-attribute 

label: str = Field(
    default="Loading...", description="Screen reader label"
)

Tabs

Bootstrap tabs component.

Example 
tabs = Tabs(tabs=[
    TabItem(id="gear", title="Gear", content="<p>Equipment list</p>", active=True),
    TabItem(id="trails", title="Trails", content="<p>Trail maps</p>")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/tabs.html", frozen=True
)

tabs class-attribute instance-attribute 

tabs: list[TabItem] = Field(..., description='Tab items')

variant class-attribute instance-attribute 

variant: str = Field(
    default="tabs", description="Tab style: tabs, pills"
)

justified class-attribute instance-attribute 

justified: bool = Field(
    default=False, description="Equal width tabs"
)

vertical class-attribute instance-attribute 

vertical: bool = Field(
    default=False, description="Vertical tabs"
)

Accordion

Bootstrap accordion component.

Example 
accordion = Accordion(items=[
    AccordionItem(title="Gear", content="<p>Tent, sleeping bag</p>", expanded=True),
    AccordionItem(title="Food", content="<p>Trail mix, water</p>")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/accordion.html", frozen=True
)

items class-attribute instance-attribute 

items: list[AccordionItem] = Field(
    ..., description="Accordion items"
)

always_open class-attribute instance-attribute 

always_open: bool = Field(
    default=False,
    description="Allow multiple items to be open",
)

flush class-attribute instance-attribute 

flush: bool = Field(
    default=False,
    description="Remove borders and rounded corners",
)

Pagination

Bootstrap pagination component.

Example 
pagination = Pagination(current_page=2, total_pages=5, base_url="/trails")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/pagination.html", frozen=True
)

current_page class-attribute instance-attribute 

current_page: int = Field(
    ..., description="Current page number (1-indexed)"
)

total_pages class-attribute instance-attribute 

total_pages: int = Field(
    ..., description="Total number of pages"
)

max_links: int = Field(
    default=5, description="Maximum page links to show"
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Pagination size: sm, lg"
)

show_first_last class-attribute instance-attribute 

show_first_last: bool = Field(
    default=True, description="Show first/last page links"
)

show_prev_next class-attribute instance-attribute 

show_prev_next: bool = Field(
    default=True, description="Show previous/next links"
)

base_url class-attribute instance-attribute 

base_url: str = Field(
    default="#", description="Base URL for page links"
)

param_name class-attribute instance-attribute 

param_name: str = Field(
    default="page",
    description="Query parameter name for page",
)

Dropdown

Bootstrap dropdown component.

Example 
dropdown = Dropdown(button_text="Trails", items=[
    DropdownItem(label="Mountain", href="/mountain"),
    DropdownItem(label="Forest", href="/forest")
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/dropdown.html", frozen=True
)

button_text class-attribute instance-attribute 

button_text: str = Field(
    ..., description="Dropdown button text"
)

items class-attribute instance-attribute 

items: list[DropdownItem] = Field(
    ..., description="Dropdown menu items"
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary", description="Button variant"
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Button size: sm, lg"
)

split class-attribute instance-attribute 

split: bool = Field(
    default=False, description="Split button dropdown"
)

direction class-attribute instance-attribute 

direction: str = Field(
    default="down",
    description="Dropdown direction: down, up, start, end",
)

alignment class-attribute instance-attribute 

alignment: str = Field(
    default="start",
    description="Menu alignment: start, end",
)

ButtonGroup

Bootstrap button group component.

Example 
button_group = ButtonGroup(data=[
    {"label": "Easy", "href": "#", "active": True},
    {"label": "Hard", "href": "#"}
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/button_group.html", frozen=True
)

data class-attribute instance-attribute 

data: list[dict[str, Any]] = Field(
    ...,
    description="Buttons as list of dictionaries with label, href, variant, active, disabled",
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Button group size: sm, lg"
)

vertical class-attribute instance-attribute 

vertical: bool = Field(
    default=False, description="Vertical button group"
)

toolbar class-attribute instance-attribute 

toolbar: bool = Field(
    default=False, description="Button toolbar"
)

Collapse

Bootstrap collapse component.

Example 
collapse = Collapse(button_text="Trail Details", content="<p>Rocky terrain</p>")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/collapse.html", frozen=True
)

button_text class-attribute instance-attribute 

button_text: str = Field(
    ..., description="Toggle button text"
)

content class-attribute instance-attribute 

content: str = Field(
    ..., description="Collapsible content (HTML)"
)

expanded class-attribute instance-attribute 

expanded: bool = Field(
    default=False, description="Initially expanded"
)

button_variant class-attribute instance-attribute 

button_variant: str = Field(
    default="primary", description="Button variant"
)

ActivityItem

Activity feed item.

Example 
activity = ActivityItem(title="Trail completed", timestamp="2 hours ago")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/activity_item.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Activity title')

description class-attribute instance-attribute 

description: str | None = Field(
    default=None, description="Activity description"
)

timestamp class-attribute instance-attribute 

timestamp: str = Field(
    ..., description="Activity timestamp"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None, description="Bootstrap icon class"
)

icon_variant class-attribute instance-attribute 

icon_variant: str = Field(
    default="primary",
    description="Icon background color variant",
)

user_name class-attribute instance-attribute 

user_name: str | None = Field(
    default=None, description="User name"
)

user_avatar class-attribute instance-attribute 

user_avatar: str | None = Field(
    default=None, description="User avatar URL"
)

Timeline

Timeline component for events.

Example 
timeline = Timeline(data=[
    {"title": "Started hike", "timestamp": "9am"},
    {"title": "Reached summit", "timestamp": "2pm"}
])

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/timeline.html", frozen=True
)

title class-attribute instance-attribute 

title: str | None = Field(
    default=None, description="Timeline title"
)

data class-attribute instance-attribute 

data: list[dict[str, Any]] = Field(
    ...,
    description="Timeline events as list of dictionaries with title, description, timestamp, icon, variant",
)

Table

Basic Bootstrap table component.

Example 
table = Table(data=[
    {"trail": "Eagle Peak", "miles": 5.2},
    {"trail": "Pine Ridge", "miles": 3.8}
])

Methods:

Attributes:

  • template (str) –

    Bootstrap table component.

  • columns (list[str] | None) –

    Table columns. Table will show only these columns in this order. If None, columns are inferred from data.

  • data (list[dict[str, Any]]) –

    Table data rows as a list of dictionaries.

  • column_labels (dict[str, str] | None) –

    Mapping of column names to nice display labels.

  • striped (bool) –

    Striped rows.

  • hover (bool) –

    Hoverable rows.

  • bordered (bool) –

    Bordered table.

  • borderless (bool) –

    Borderless table.

  • small (bool) –

    Compact table.

  • responsive (bool) –

    Responsive table wrapper.

  • variant (str | None) –

    Table color variant. Bootstrap variants: primary, secondary, success, danger, warning, info, light, dark.

template class-attribute instance-attribute 

template: str = 'components/bootstrap/table.html'

Bootstrap table component.

columns class-attribute instance-attribute 

columns: list[str] | None = Field(
    default=None,
    description="Column names (inferred from data if not provided)",
)

Table columns. Table will show only these columns in this order. If None, columns are inferred from data.

data class-attribute instance-attribute 

data: list[dict[str, Any]] = Field(
    ..., description="Table data as list of dictionaries"
)

Table data rows as a list of dictionaries.

column_labels class-attribute instance-attribute 

column_labels: dict[str, str] | None = Field(
    default=None,
    description="Mapping of column keys to display labels",
)

Mapping of column names to nice display labels.

striped class-attribute instance-attribute 

striped: bool = Field(
    default=False, description="Striped rows"
)

Striped rows.

hover class-attribute instance-attribute 

hover: bool = Field(
    default=False, description="Hoverable rows"
)

Hoverable rows.

bordered class-attribute instance-attribute 

bordered: bool = Field(
    default=False, description="Bordered table"
)

Bordered table.

borderless class-attribute instance-attribute 

borderless: bool = Field(
    default=False, description="Borderless table"
)

Borderless table.

small class-attribute instance-attribute 

small: bool = Field(
    default=False, description="Compact table"
)

Compact table.

responsive class-attribute instance-attribute 

responsive: bool = Field(
    default=True, description="Responsive table wrapper"
)

Responsive table wrapper.

variant class-attribute instance-attribute 

variant: str | None = Field(
    default=None, description="Table color variant"
)

Table color variant. Bootstrap variants: primary, secondary, success, danger, warning, info, light, dark.

model_post_init 

model_post_init(__context)

Infer columns from data if not provided.

Icon

Bootstrap icon component.

Example 
icon = Icon(name="bi-tree", color="green")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/icon.html", frozen=True
)

name class-attribute instance-attribute 

name: str = Field(
    ...,
    description="Bootstrap icon class name (e.g., 'bi-heart-fill')",
)

size class-attribute instance-attribute 

size: str | None = Field(
    default=None, description="Icon size: 1rem, 2rem, etc."
)

color class-attribute instance-attribute 

color: str | None = Field(
    default=None,
    description="Icon color (CSS color or Bootstrap text-* class)",
)

Avatar

User avatar component.

Example 
avatar = Avatar(initials="TG", variant="success")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/avatar.html", frozen=True
)

image_url class-attribute instance-attribute 

image_url: str | None = Field(
    default=None, description="Avatar image URL"
)

initials class-attribute instance-attribute 

initials: str | None = Field(
    default=None, description="User initials (if no image)"
)

alt class-attribute instance-attribute 

alt: str = Field(
    default="User avatar", description="Image alt text"
)

size class-attribute instance-attribute 

size: str = Field(
    default="md",
    description="Avatar size: xs, sm, md, lg, xl",
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="primary",
    description="Background color variant for initials",
)

rounded class-attribute instance-attribute 

rounded: bool = Field(
    default=True, description="Rounded (circle) avatar"
)

border class-attribute instance-attribute 

border: bool = Field(
    default=False, description="Show border"
)

status class-attribute instance-attribute 

status: str | None = Field(
    default=None,
    description="Status indicator: online, offline, away, busy",
)

Skeleton

Loading skeleton placeholder component.

Example 
skeleton = Skeleton(type="text", lines=3)

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/skeleton.html", frozen=True
)

type class-attribute instance-attribute 

type: str = Field(
    default="text",
    description="Skeleton type: text, circle, rectangle",
)

width class-attribute instance-attribute 

width: str | None = Field(
    default=None,
    description="Custom width (e.g., '100%', '200px')",
)

height class-attribute instance-attribute 

height: str | None = Field(
    default=None,
    description="Custom height (e.g., '20px', '100px')",
)

lines class-attribute instance-attribute 

lines: int = Field(
    default=1,
    description="Number of text lines (for type='text')",
)

animation class-attribute instance-attribute 

animation: str = Field(
    default="wave",
    description="Animation style: wave, pulse, none",
)

EmptyState

Empty state placeholder component.

Example 
empty_state = EmptyState(title="No trails found", action_text="Browse All")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/empty_state.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Empty state title')

description class-attribute instance-attribute 

description: str | None = Field(
    default=None, description="Empty state description"
)

icon class-attribute instance-attribute 

icon: str | None = Field(
    default=None, description="Bootstrap icon class"
)

icon_size class-attribute instance-attribute 

icon_size: str = Field(
    default="4rem", description="Icon size"
)

icon_variant class-attribute instance-attribute 

icon_variant: str = Field(
    default="secondary", description="Icon color variant"
)

action_text class-attribute instance-attribute 

action_text: str | None = Field(
    default=None, description="Action button text"
)

action_href class-attribute instance-attribute 

action_href: str | None = Field(
    default=None, description="Action button URL"
)

action_variant class-attribute instance-attribute 

action_variant: str = Field(
    default="primary", description="Action button variant"
)

Offcanvas

Bootstrap offcanvas component (generic version).

Example 
offcanvas = Offcanvas(title="Trail Map", body="<p>Map content</p>")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/offcanvas.html", frozen=True
)

title class-attribute instance-attribute 

title: str = Field(..., description='Offcanvas title')

body class-attribute instance-attribute 

body: str = Field(
    ..., description="Offcanvas body content (HTML)"
)

placement class-attribute instance-attribute 

placement: str = Field(
    default="end",
    description="Placement: start, end, top, bottom",
)

backdrop class-attribute instance-attribute 

backdrop: bool = Field(
    default=True, description="Show backdrop overlay"
)

scroll class-attribute instance-attribute 

scroll: bool = Field(
    default=False, description="Allow body scrolling"
)

show_close_button class-attribute instance-attribute 

show_close_button: bool = Field(
    default=True, description="Show close button"
)

Divider

Horizontal divider component.

Example 
divider = Divider(text="OR")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/divider.html", frozen=True
)

text class-attribute instance-attribute 

text: str | None = Field(
    default=None, description="Divider text label"
)

margin class-attribute instance-attribute 

margin: str = Field(
    default="my-3", description="Margin classes"
)

CopyButton

Copy to clipboard button component.

Example 
copy_button = CopyButton(text_to_copy="Trail coordinates: 47.6°N")

Attributes:

template class-attribute instance-attribute 

template: str = Field(
    "components/bootstrap/copy_button.html", frozen=True
)

text_to_copy class-attribute instance-attribute 

text_to_copy: str = Field(
    ..., description="Text to copy to clipboard"
)

button_text class-attribute instance-attribute 

button_text: str = Field(
    default="Copy", description="Button text"
)

success_text class-attribute instance-attribute 

success_text: str = Field(
    default="Copied!", description="Success message"
)

variant class-attribute instance-attribute 

variant: str = Field(
    default="outline-secondary",
    description="Button variant",
)

size class-attribute instance-attribute 

size: str | None = Field(
    default="sm", description="Button size"
)

icon class-attribute instance-attribute 

icon: str = Field(
    default="bi-clipboard", description="Button icon"
)

success_icon class-attribute instance-attribute 

success_icon: str = Field(
    default="bi-check2", description="Success icon"
)