Component Defaults

Component defaults let you set project-wide behavior once, then override it per component call when needed.

Startup-Only Configuration

Call set_component_defaults() during application startup before requests are being handled.

from fasthtml.common import FastHTML
from faststrap import Button, add_bootstrap, set_component_defaults

app = FastHTML()
add_bootstrap(app)

set_component_defaults("Button", variant="secondary", size="lg")

Faststrap protects this state with a lock, but defaults are still process-global. Treat them like app configuration, not per-request state.

Override Defaults Per Call

Explicit values win over global defaults.

Button("Uses project defaults")
Button("Small danger action", variant="danger", size="sm")

Clearing A Default With None

Faststrap uses the UNSET sentinel internally to mean "the caller did not pass this argument." That leaves None free to mean "clear the default for this one call."

from faststrap import Button, set_component_defaults

set_component_defaults("Button", size="lg")

Button("Large by default")
Button("Normal size here", size=None)

Using UNSET In Wrapper Components

If you write wrapper components, default your overridable parameters to UNSET. That preserves Faststrap's normal default-resolution behavior.

from typing import Any

from faststrap import Button, UNSET


def SaveButton(*children: Any, variant: str | None = UNSET, **kwargs: Any):
    return Button(*children, variant=variant, icon="check", **kwargs)

Value behavior:

Value	Meaning
Parameter omitted / UNSET	Use the global default, then the component fallback.
None	Explicitly clear the global default for this call.
Any concrete value	Use this value for this call.

Resetting Defaults

Use reset_component_defaults() in tests or setup scripts when you need to return to built-in defaults.

from faststrap import reset_component_defaults

reset_component_defaults("Button")
reset_component_defaults()

API Reference

faststrap.core.theme.UNSET = _UnsetDefault() module-attribute

faststrap.core.theme.set_component_defaults(component, **defaults)

Set default values for a component globally.

This updates process-global state shared by all requests. Configure defaults during application startup.

Parameters:

Name	Type	Description	Default
component	str	Component name (e.g., "Button")	required
**defaults	Any	Default values to set	{}

Examples:

>>> set_component_defaults("Button", variant="outline-primary", size="sm")
>>> # Now all Button() calls use these defaults unless overridden

Source code in src/faststrap/core/theme.py

def set_component_defaults(component: str, **defaults: Any) -> None:
    """Set default values for a component globally.

    This updates process-global state shared by all requests.
    Configure defaults during application startup.

    Args:
        component: Component name (e.g., "Button")
        **defaults: Default values to set

    Examples:
        >>> set_component_defaults("Button", variant="outline-primary", size="sm")
        >>> # Now all Button() calls use these defaults unless overridden
    """
    global _COMPONENT_DEFAULTS_WARNED

    with _COMPONENT_DEFAULTS_LOCK:
        if _COMPONENT_DEFAULTS_LOCKED and not _COMPONENT_DEFAULTS_WARNED:
            warnings.warn(
                "set_component_defaults() updates process-global state. "
                "Prefer calling it during application startup before handling requests.",
                RuntimeWarning,
                stacklevel=2,
            )
            _COMPONENT_DEFAULTS_WARNED = True

        if component not in _COMPONENT_DEFAULTS:
            _COMPONENT_DEFAULTS[component] = {}
        _COMPONENT_DEFAULTS[component].update(defaults)

faststrap.core.theme.get_component_defaults(component)

Get default values for a component.

Parameters:

Name	Type	Description	Default
component	str	Component name (e.g., "Button")	required

Returns:

Type	Description
dict[str, Any]	Dict of default values

Source code in src/faststrap/core/theme.py

def get_component_defaults(component: str) -> dict[str, Any]:
    """Get default values for a component.

    Args:
        component: Component name (e.g., "Button")

    Returns:
        Dict of default values
    """
    with _COMPONENT_DEFAULTS_LOCK:
        return _COMPONENT_DEFAULTS.get(component, {}).copy()

faststrap.core.theme.reset_component_defaults(component=None)

Reset component defaults to original values.

Parameters:

Name	Type	Description	Default
component	str | None	Component name to reset, or None to reset all	None

Source code in src/faststrap/core/theme.py

def reset_component_defaults(component: str | None = None) -> None:
    """Reset component defaults to original values.

    Args:
        component: Component name to reset, or None to reset all
    """
    global _COMPONENT_DEFAULTS, _COMPONENT_DEFAULTS_LOCKED, _COMPONENT_DEFAULTS_WARNED

    with _COMPONENT_DEFAULTS_LOCK:
        if component is None:
            # Reset all components to original defaults
            _COMPONENT_DEFAULTS = {k: v.copy() for k, v in _DEFAULT_COMPONENT_DEFAULTS.items()}
            _COMPONENT_DEFAULTS_LOCKED = False
            _COMPONENT_DEFAULTS_WARNED = False
            _BUILTIN_THEME_CACHE.clear()
        elif component in _DEFAULT_COMPONENT_DEFAULTS:
            # Reset specific component to original default
            _COMPONENT_DEFAULTS[component] = _DEFAULT_COMPONENT_DEFAULTS[component].copy()

faststrap.core.theme.resolve_defaults(component, **kwargs)

Resolve component attributes by merging defaults with user arguments.

Priority (highest to lowest): 1. Explicit user arguments (including None when passed intentionally) 2. Global component defaults (set via set_component_defaults)

Parameters:

Name	Type	Description	Default
component	str	Component name (e.g., "Button")	required
**kwargs	Any	Arguments passed by the user	{}

Returns:

Type	Description
dict[str, Any]	Dict of resolved attributes

Examples:

>>> set_component_defaults("Button", variant="secondary")
>>> resolve_defaults("Button", variant=UNSET, size="lg")
{"variant": "secondary", "size": "lg"}
>>> resolve_defaults("Button", variant=None)
{"variant": None, "size": None, "outline": False}

Source code in src/faststrap/core/theme.py

def resolve_defaults(component: str, **kwargs: Any) -> dict[str, Any]:
    """Resolve component attributes by merging defaults with user arguments.

    Priority (highest to lowest):
    1. Explicit user arguments (including None when passed intentionally)
    2. Global component defaults (set via set_component_defaults)

    Args:
        component: Component name (e.g., "Button")
        **kwargs: Arguments passed by the user

    Returns:
        Dict of resolved attributes

    Examples:
        >>> set_component_defaults("Button", variant="secondary")
        >>> resolve_defaults("Button", variant=UNSET, size="lg")
        {"variant": "secondary", "size": "lg"}
        >>> resolve_defaults("Button", variant=None)
        {"variant": None, "size": None, "outline": False}
    """
    global _COMPONENT_DEFAULTS_LOCKED

    with _COMPONENT_DEFAULTS_LOCK:
        _COMPONENT_DEFAULTS_LOCKED = True
        defaults = _COMPONENT_DEFAULTS.get(component, {}).copy()

    resolved = defaults.copy()

    for key, value in kwargs.items():
        if value is not UNSET:
            resolved[key] = value
    return resolved