Controlled & Uncontrolled
Let a component manage its own state, or control it with a signal.
Every stateful component, such as Switch (checked), Collapsible (open) or Tabs (value), supports both modes with the same three props:
| Prop | Mode | Example |
|---|---|---|
default<State> | Uncontrolled: the initial value | defaultChecked, defaultOpen, defaultValue |
bind:<state> | Controlled: a Signal that holds the value | bind:checked, bind:open, bind:value |
on<State>Change$ | A callback when the user changes the value | onCheckedChange$, onOpenChange$, onValueChange$ |
The exact props of each component are listed in its API reference.
Uncontrolled#
Pass default<State>, or nothing, and the component keeps the state itself:
<Switch.Root defaultChecked>
<Switch.Label>Notifications</Switch.Label>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
</Switch.Root>
Use on<State>Change$ to react to changes without owning the state:
<Switch.Root onCheckedChange$={(checked) => console.log(checked)}>
Controlled#
Pass a signal with bind:<state>. The component reads and writes it, so the signal and the component stay in sync in both directions. Change the signal yourself to change the component:
import { component$, useSignal } from '@builder.io/qwik';
import { Collapsible } from '@leve-ui/collapsible';
export default component$(() => {
const open = useSignal(false);
return (
<>
<button type="button" onClick$={() => (open.value = !open.value)}>
{open.value ? 'Close' : 'Open'} from outside
</button>
<Collapsible.Root bind:open={open}>
<Collapsible.Trigger>Controlled collapsible</Collapsible.Trigger>
<Collapsible.Content>
This collapsible state is controlled by an external signal.
</Collapsible.Content>
</Collapsible.Root>
</>
);
});
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Collapsible } from '@leve-ui/collapsible';
import { LuChevronDown } from '@qwikest/icons/lucide';
import styles from './controlled.css?inline';
export default component$(() => {
useStyles$(styles);
const open = useSignal(false);
return (
<div class="collapsible-controlled-wrapper">
<button
type="button"
class="collapsible-controlled-external-button"
onClick$={() => {
open.value = !open.value;
}}
>
{open.value ? 'Close' : 'Open'} from outside
</button>
<Collapsible.Root bind:open={open} class="collapsible-controlled-root">
<Collapsible.Trigger class="collapsible-controlled-trigger">
<span>Controlled collapsible</span>
<LuChevronDown class="collapsible-controlled-chevron" aria-hidden="true" />
</Collapsible.Trigger>
<Collapsible.Content class="collapsible-controlled-content">
This collapsible state is controlled by an external signal.
</Collapsible.Content>
</Collapsible.Root>
</div>
);
});.collapsible-controlled-wrapper {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.collapsible-controlled-external-button {
height: 32px;
padding: 0 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.collapsible-controlled-external-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.collapsible-controlled-external-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.collapsible-controlled-root {
display: flex;
flex-direction: column;
gap: 8px;
width: 320px;
}
.collapsible-controlled-trigger {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
padding: 10px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
text-align: left;
cursor: pointer;
}
.collapsible-controlled-trigger:hover:not(:disabled) {
background: light-dark(#f1f5f9, #ffffff14);
}
.collapsible-controlled-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.collapsible-controlled-trigger:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* Rotate the chevron while the collapsible is open */
.collapsible-controlled-chevron {
flex-shrink: 0;
width: 16px;
height: 16px;
color: light-dark(#475569, #c9ddf0);
transition: transform 200ms ease;
}
.collapsible-controlled-trigger[data-state="open"] .collapsible-controlled-chevron {
transform: rotate(180deg);
}
.collapsible-controlled-content {
padding: 10px 14px;
border-radius: 6px;
background: light-dark(#f1f5f9, #ffffff14);
font-size: 13px;
line-height: 1.6;
color: light-dark(#475569, #c9ddf0);
}When bind:<state> is given, default<State> is ignored and the signal's value is used as the initial value, also on the server.
When on<State>Change$ is called#
on<State>Change$ is called only when the component changes the value, for example when the user clicks the switch. It is not called:
- when you write to the bound signal yourself, and
- when the new value is the same as the current one.
So you can update the signal from on<State>Change$ or from anywhere else without causing a loop. To react to every change, including your own, track the signal instead, for example with useTask$.
Choosing a mode#
- Use uncontrolled when only the component needs the state, for example a disclosure that the user opens and closes.
- Use controlled when other parts of your page read or change the state, for example a button that opens the Collapsible, or a value you save and restore.
Do not switch a component between controlled and uncontrolled after it has rendered.