@lattice-ui/toggle-group Part of the stable direction toward v1.0.
What It Is For
Use ToggleGroup for pill bars, formatting controls, and compact segmented selectors where buttons should show pressed state.
It bridges the gap between a lone Switch and a full RadioGroup, with both single and multiple selection modes.
import { ToggleGroup } from "@lattice-ui/toggle-group";
import React from "@rbxts/react";
export function ToggleGroupExample() {
const [value, setValue] = React.useState<string | undefined>("alpha");
return (
<frame BackgroundTransparency={1} Size={UDim2.fromOffset(420, 160)}>
<ToggleGroup.Root onValueChange={setValue} type="single" value={value}>
<frame BackgroundTransparency={1} Size={UDim2.fromOffset(360, 40)}>
<uilistlayout
FillDirection={Enum.FillDirection.Horizontal}
Padding={new UDim(0, 8)}
/>
{(["alpha", "beta", "gamma"] as const).map((itemValue) => (
<ToggleGroup.Item asChild key={itemValue} value={itemValue}>
<textbutton
AutoButtonColor={false}
BackgroundColor3={
value === itemValue
? Color3.fromRGB(53, 104, 196)
: Color3.fromRGB(34, 41, 54)
}
BorderSizePixel={0}
Size={UDim2.fromOffset(110, 36)}
Text={itemValue}
TextColor3={Color3.fromRGB(236, 240, 248)}
TextSize={14}
>
<uicorner CornerRadius={new UDim(0, 8)} />
</textbutton>
</ToggleGroup.Item>
))}
</frame>
</ToggleGroup.Root>
</frame>
);
} Live demo is experimental and may contain bugs.
Install
Global CLI command: lattice add toggle-group
Monorepo local script
Use your package manager wrapper when running the local lattice command.
pnpm lattice add toggle-groupPublic Exports
-
ToggleGroup -
ToggleGroup.Root -
ToggleGroup.Item
State Model
ToggleGroup.Rootswitches betweensingleandmultipleselection models through the requiredtypeprop.- The value shape follows that selection model: a string or undefined for
single, an array formultiple. - Pressed state is computed centrally, and both group-level and item-level disabled flags participate in interaction rules.
Key API
ToggleGroup.Root
Use type, value, defaultValue, and onValueChange to define whether the group behaves like a segmented selector or a pressed-state toolbar.
ToggleGroup.Item
Each item needs a stable value; disabled removes it from toggling without changing the rest of the group.
Composition Patterns
Single-choice segmented controls
Use type="single" when the control should feel like a compact alternative to radio buttons.
Pressed formatting toolbars
Use type="multiple" when several pressed states may be active at once, such as bold/italic/underline controls.
Cautions / Limits
- The controlled value shape changes with
type, so avoid sharing one state variable between single and multiple groups without normalizing it first. - Use
RadioGroupwhen the options should stay visible but read more like a classic form control than a pressed button bar.