@lattice-ui/checkbox Part of the stable direction toward v1.0.
What It Is For
Use Checkbox for boolean or tri-state choices where the control itself is the interaction target.
It is useful when you need indeterminate state and want to keep the visual host fully custom.
import { Checkbox, type CheckedState } from "@lattice-ui/checkbox";
import React from "@rbxts/react";
function toIndicator(value: CheckedState) {
if (value === "indeterminate") {
return "-";
}
return value ? "x" : "";
}
export function CheckboxExample() {
const [checked, setChecked] = React.useState<CheckedState>("indeterminate");
return (
<frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 180)}>
<Checkbox.Root asChild checked={checked} onCheckedChange={setChecked}>
<textbutton
AutoButtonColor={false}
BackgroundColor3={Color3.fromRGB(34, 41, 54)}
BorderSizePixel={0}
Size={UDim2.fromOffset(320, 44)}
Text=""
>
<uicorner CornerRadius={new UDim(0, 8)} />
<frame
BackgroundColor3={Color3.fromRGB(22, 28, 39)}
BorderSizePixel={0}
Position={UDim2.fromOffset(10, 10)}
Size={UDim2.fromOffset(24, 24)}
>
<uicorner CornerRadius={new UDim(0, 6)} />
<Checkbox.Indicator asChild forceMount>
<textlabel
BackgroundTransparency={1}
Size={UDim2.fromScale(1, 1)}
Text={toIndicator(checked)}
TextColor3={Color3.fromRGB(236, 240, 248)}
TextSize={16}
/>
</Checkbox.Indicator>
</frame>
<textlabel
BackgroundTransparency={1}
Position={UDim2.fromOffset(48, 0)}
Size={UDim2.fromOffset(250, 44)}
Text={`Checkbox state: ${tostring(checked)}`}
TextColor3={Color3.fromRGB(236, 240, 248)}
TextSize={14}
TextXAlignment={Enum.TextXAlignment.Left}
/>
</textbutton>
</Checkbox.Root>
<textbutton
AutoButtonColor={false}
BackgroundColor3={Color3.fromRGB(60, 76, 104)}
BorderSizePixel={0}
Position={UDim2.fromOffset(0, 62)}
Size={UDim2.fromOffset(210, 34)}
Text="Reset to indeterminate"
TextColor3={Color3.fromRGB(236, 240, 248)}
TextSize={14}
Event={{ Activated: () => setChecked("indeterminate") }}
>
<uicorner CornerRadius={new UDim(0, 8)} />
</textbutton>
</frame>
);
}Live demo is experimental and may contain bugs.
Install
Global CLI command: lattice add checkbox
Monorepo local script
Use your package manager wrapper when running the local lattice command.
pnpm lattice add checkboxPublic Exports
-
Checkbox -
Checkbox.Root -
Checkbox.Indicator -
CheckboxIndicator -
CheckboxRoot
State Model
checkedsupportstrue,false, and"indeterminate".Checkbox.Rootsupports both controlled and uncontrolled state viacheckedordefaultChecked.Checkbox.Indicatorreflects the current checked state and can remain mounted withforceMount.
Key API
Checkbox.Root
Use checked, defaultChecked, onCheckedChange, disabled, and required to integrate with your own form model.
Checkbox.Root asChild
Set asChild when you want the click behavior attached to an existing button-like element instead of the default host.
Checkbox.Indicator
Mount visual marks, fills, or icons inside the checkbox without rebuilding checked-state plumbing.
Composition Patterns
Checklist rows
Wrap the interactive host with Checkbox.Root asChild and render the label beside it so the state lives in one place.
Partial selection
Use "indeterminate" for parent-group selection UIs where some but not all descendants are active.
Cautions / Limits
- The default toggle cycle is
indeterminate -> true -> false; account for that if you map the value into external state. - Use
Switchinstead ofCheckboxwhen the UI should communicate an immediate on/off setting rather than selection membership.
Decision Guides
- Choosing between controls
Compare Switch vs Checkbox and see when indeterminate state matters.
- Overlay and state pitfalls
Review controlled/uncontrolled transitions and disabled item behavior before wiring forms.