SearchBar

@experimental

Polished global search input with optional HTMX integration.

---

Quick Start

from faststrap import SearchBar

SearchBar("Search users...")

---

Features

• Polished search input with optional icon prefix
• HTMX-powered live search with debouncing
• Works with any server-side search endpoint
• Accessible with proper ARIA attributes

---

Parameters

Parameter	Type	Default	Description
placeholder	str	"Search..."	Input placeholder text.
endpoint	str \| None	None	HTMX endpoint for search results.
target	str \| None	None	HTMX target selector for results.
swap	str	"innerHTML"	HTMX swap strategy.
name	str	"q"	Query parameter name.
method	str	"get"	HTTP method for search requests.
autocomplete	str	"off"	Input autocomplete attribute.
**kwargs	Any		Extra wrapper attributes.

---

Usage Examples

Basic Search Input

SearchBar("Search users...")

Live Search with HTMX

SearchBar(
    "Search users...",
    endpoint="/api/users/search",
    target="#search-results",
)

Custom Parameter Name

SearchBar("Search...", name="query", endpoint="/api/search")

---

Notes

• Pure HTML/CSS with optional HTMX enhancement.
• When endpoint is provided, the input submits automatically on input changes with 300ms debounce.
• Marked @experimental.

---

API Reference

faststrap.components.navigation.search_bar.SearchBar(placeholder='Search...', *, endpoint=None, target=None, swap='innerHTML', name='q', method='get', autocomplete='off', **kwargs)

Polished global search input with optional HTMX integration.

Renders a search form with an icon-prefixed input. When endpoint is provided, the form submits via HTMX and swaps results into target.

Parameters:

Name	Type	Description	Default
placeholder	str	Input placeholder text.	'Search...'
endpoint	str | None	HTMX endpoint to query for search results.	None
target	str | None	HTMX target selector for results.	None
swap	str	HTMX swap strategy.	'innerHTML'
name	str	Query parameter name for the search term.	'q'
method	str	HTTP method for the search request.	'get'
autocomplete	str	Input autocomplete attribute.	'off'
**kwargs	Any	Additional HTML attributes for the wrapper.	{}

Returns:

Type	Description
Div	FastHTML Div element containing the search form.

Source code in src/faststrap/components/navigation/search_bar.py

@register(category="navigation")
@experimental
def SearchBar(
    placeholder: str = "Search...",
    *,
    endpoint: str | None = None,
    target: str | None = None,
    swap: str = "innerHTML",
    name: str = "q",
    method: str = "get",
    autocomplete: str = "off",
    **kwargs: Any,
) -> Div:
    """Polished global search input with optional HTMX integration.

    Renders a search form with an icon-prefixed input. When ``endpoint``
    is provided, the form submits via HTMX and swaps results into
    ``target``.

    Args:
        placeholder: Input placeholder text.
        endpoint: HTMX endpoint to query for search results.
        target: HTMX target selector for results.
        swap: HTMX swap strategy.
        name: Query parameter name for the search term.
        method: HTTP method for the search request.
        autocomplete: Input autocomplete attribute.
        **kwargs: Additional HTML attributes for the wrapper.

    Returns:
        FastHTML ``Div`` element containing the search form.
    """
    user_cls = kwargs.pop("cls", "")

    input_attrs: dict[str, Any] = {
        "type": "search",
        "name": name,
        "placeholder": placeholder,
        "autocomplete": autocomplete,
        "cls": "form-control",
    }
    if endpoint:
        input_attrs["hx_get"] = endpoint
        input_attrs["hx_target"] = target or "#search-results"
        input_attrs["hx_swap"] = swap
        input_attrs["hx_trigger"] = "input changed delay:300ms"
        input_attrs["hx_include"] = f"[name='{name}']"

    form_kwargs: dict[str, Any] = {"cls": "faststrap-search-bar", "role": "search"}
    if endpoint:
        form_kwargs["hx_get"] = endpoint
        form_kwargs["hx_target"] = target or "#search-results"
        form_kwargs["hx_swap"] = swap

    form_cls = merge_classes("faststrap-search-bar", user_cls)
    form_attrs: dict[str, Any] = {
        "cls": form_cls,
        "role": "search",
    }
    if endpoint:
        form_attrs["hx_get"] = endpoint
        form_attrs["hx_target"] = target or "#search-results"
        form_attrs["hx_swap"] = swap
    form_attrs.update(convert_attrs(kwargs))

    return Div(
        Form(
            Input(**input_attrs),
            method=method,
            **(
                {"hx_get": endpoint, "hx_target": target or "#search-results", "hx_swap": swap}
                if endpoint
                else {}
            ),
        ),
        **form_attrs,
    )