Empty State

The EmptyState component provides a visual placeholder for when data is missing or a user hasn't completed an action yet. It usually contains an icon, a title, a description, and a call-to-action button.

Quick Start

Live Preview

No items found

You haven't added any items to your collection yet.

EmptyState(
    title="No items found",
    description="You haven't added any items to your collection yet.",
    icon="search",
    action=Button("Add First Item", variant="primary")
)

Visual Examples & Use Cases

1. Dashboard Placeholders

Use inside cards or grids to signify empty data sets.

Code & Output

```python from faststrap import Card

Live Preview (Card Placeholder)

No Activity

Log some activity to see it here.

Card(
    EmptyState(
        title="No Activity",
        description="Log some activity to see it here.",
        icon="activity"
    )
)

```

Parameter Reference

FastStrap Param	Type	Description
`title`	`str`	Main bold heading.
`description`	`str`	Explanatory message.
`icon`	`str`	Bootstrap icon name.
`action`	`Any`	Call to action (usually a Button or Link).
`variant`	`str`	Color variant for the icon and title.

`faststrap.components.display.empty_state.EmptyState(icon=None, title='No data available', description=None, action=None, centered=True, icon_cls='display-4 text-muted mb-3', title_cls='mb-2', description_cls='text-muted mb-4', **kwargs)`

Bootstrap Empty State component.

Placeholder for empty data states.

Parameters:

Name	Type	Description	Default
`icon`	`Any \| None`	Icon component or img to display	`None`
`title`	`str`	Main heading	`'No data available'`
`description`	`str \| None`	Subtitle/explanation	`None`
`action`	`Any \| None`	Button or link to perform an action	`None`
`centered`	`bool`	Center align content (default: True)	`True`
`icon_cls`	`str`	Classes for the icon wrapper	`'display-4 text-muted mb-3'`
`title_cls`	`str`	Classes for title	`'mb-2'`
`description_cls`	`str`	Classes for description	`'text-muted mb-4'`
`**kwargs`	`Any`	Additional HTML attributes	`{}`

Returns:

Type	Description
`Div`	FastHTML Div element

Example

EmptyState( ... Icon("inbox", cls="display-1"), ... title="No messages", ... description="Your inbox is empty.", ... action=Button("Refresh") ... )

Source code in src/faststrap/components/display/empty_state.py

@register(category="display")
@stable
def EmptyState(
    icon: Any | None = None,
    title: str = "No data available",
    description: str | None = None,
    action: Any | None = None,
    centered: bool = True,
    icon_cls: str = "display-4 text-muted mb-3",
    title_cls: str = "mb-2",
    description_cls: str = "text-muted mb-4",
    **kwargs: Any,
) -> Div:
    """Bootstrap Empty State component.

    Placeholder for empty data states.

    Args:
        icon: Icon component or img to display
        title: Main heading
        description: Subtitle/explanation
        action: Button or link to perform an action
        centered: Center align content (default: True)
        icon_cls: Classes for the icon wrapper
        title_cls: Classes for title
        description_cls: Classes for description
        **kwargs: Additional HTML attributes

    Returns:
        FastHTML Div element

    Example:
        >>> EmptyState(
        ...     Icon("inbox", cls="display-1"),
        ...     title="No messages",
        ...     description="Your inbox is empty.",
        ...     action=Button("Refresh")
        ... )
    """
    user_cls = kwargs.pop("cls", "")

    classes = ["py-5"]
    if centered:
        classes.append("text-center")

    wrapper_cls = merge_classes(" ".join(classes), user_cls)

    attrs: dict[str, Any] = {"cls": wrapper_cls}
    attrs.update(convert_attrs(kwargs))

    content = []

    if icon:
        content.append(Div(icon, cls=icon_cls))

    content.append(H4(title, cls=title_cls))

    if description:
        content.append(P(description, cls=description_cls))

    if action:
        content.append(Div(action))

    return Div(*content, **attrs)