solara-hooks

Hook Selection Guide

| Need | Hook | |---|---| | Local component state | use_state | | Accept reactive OR plain value as prop | use_reactive | | Side effects (event handlers, subscriptions, fetches) | use_effect | | Cache expensive computation within a component | use_memo | | Access previous render's value | use_previous | | Local state that tracks external changes | use_state_or_update | | Capture component exceptions | use_exception |

For global/shared state, use solara.reactive() at module level (not a hook).

use_state

Returns (value, setter). The setter accepts a direct value or a lambda for updates based on previous value:

@solara.component
def Counter():
    count, set_count = solara.use_state(0)

    # Direct value
    solara.Button("Reset", on_click=lambda: set_count(0))

    # Lambda — avoids stale closures
    solara.Button(f"Count: {count}", on_click=lambda: set_count(lambda prev: prev + 1))

Optional key parameter names the state for debugging. Optional eq controls equality comparison.

use_reactive

Returns a solara.Reactive[T]. If passed an existing Reactive[T], returns it directly — no new variable is created. This is the pattern for flexible component APIs:

@solara.component
def ColorPicker(value: Union[str, solara.Reactive[str]] = "red",
                on_value: Optional[Callable[[str], None]] = None):
    reactive_value = solara.use_reactive(value, on_value)
    solara.Select(label="Color", values=["red", "green", "blue"],
                  value=reactive_value)

Callers can pass either ColorPicker("blue") or ColorPicker(my_reactive_var).

use_effect

Runs after render. Returns an optional cleanup function. dependencies controls re-execution:

@solara.component
def LiveData(url: str):
    data, set_data = solara.use_state(None)

    def fetch():
        result = requests.get(url)
        set_data(result.json())
        def cleanup():
            pass  # cancel subscriptions, close connections
        return cleanup

    solara.use_effect(fetch, dependencies=[url])
    # dependencies=[url] — re-run when url changes
    # dependencies=[]    — run once only
    # dependencies=None  — auto-detect (default)

use_memo

Caches a single return value per component instance. Re-computes only when dependencies change:

@solara.component
def ExpensiveView(data: list):
    # Only recomputes when data changes
    stats = solara.use_memo(lambda: compute_stats(data), dependencies=[data])
    solara.Text(f"Mean: {stats['mean']}")

• dependencies=[] — compute once, never recompute.
• dependencies=None — auto-detect from nonlocal variables.
• Not the same as @solara.memoize (see solara-caching skill).

use_previous

Returns the value from the previous render. Useful for animations, transitions, or diffing:

@solara.component
def DeltaDisplay(value: int):
    previous = solara.use_previous(value)
    if previous is not None:
        delta = value - previous
        solara.Text(f"Change: {delta:+d}")

use_state_or_update

Like use_state but re-syncs when the initial value changes from outside:

@solara.component
def EditableField(initial: str):
    # Resets when parent changes `initial`
    text, set_text = solara.use_state_or_update(initial)
    solara.InputText("Edit", value=text, on_value=set_text)

use_exception

Captures exceptions for error boundary patterns. Check exception to render error UI instead of crashing.

Rules of Hooks

These rules are strict — violating them causes silent, hard-to-debug issues:

1. Top level only — never inside if, for, try, or with blocks.
2. Same order every render — hooks must execute in identical order.
3. Only in @solara.component — hooks do not work in regular functions.

# BAD — conditional hook changes call order
@solara.component
def Bad(show: bool):
    if show:
        name, set_name = solara.use_state("")  # skipped when show=False!
    count, set_count = solara.use_state(0)

# GOOD — all hooks at top, conditional rendering below
@solara.component
def Good(show: bool):
    name, set_name = solara.use_state("")
    count, set_count = solara.use_state(0)
    if show:
        solara.InputText("Name", value=name, on_value=set_name)

When to Use

Load this skill when working with Solara hooks or state management patterns.