Checkbox

A checkbox flips a single option between checked and unchecked, and can also show an indeterminate state. Pass the current value and rebuild in onChanged. Colors, type, and spacing come from the theme. A null onChanged disables it.

import 'package:fossui/fossui.dart';

FossCheckbox(
  value: accepted,
  label: 'Accept terms and conditions',
  onChanged: (checked) => setState(() => accepted = checked),
);

States

value is tristate: true is checked, false is unchecked, and null is indeterminate, which paints a minus glyph. A tap always reports a definite state, so unchecked and indeterminate go to true and checked goes to false. The checkbox never produces null on its own; set value to null yourself to drive the indeterminate state.

FossCheckbox(
  value: null,
  label: 'Some selected',
  onChanged: (checked) => setState(() => all = checked),
);

Label and description

label renders beside the box and description adds a secondary line below it. Both are optional; a bare box with no text is valid.

FossCheckbox(
  value: subscribed,
  label: 'Email notifications',
  description: 'Get a message when someone mentions you.',
  onChanged: (checked) => setState(() => subscribed = checked),
);

Error

A non-null errorText marks the checkbox invalid, recolors the box, and shows a caption below it.

FossCheckbox(
  value: accepted,
  label: 'Accept terms',
  errorText: accepted ? null : 'You must accept to continue',
  onChanged: (checked) => setState(() => accepted = checked),
);

Disabled

Pass a null onChanged, or set enabled: false, to disable the checkbox. It dims to a muted opacity and stops responding to input.

const FossCheckbox(
  value: true,
  label: 'Locked',
  onChanged: null,
);

Groups

For a set of related options, FossCheckboxGroup holds the checked values and one onChanged, and shares them with its FossCheckboxItem children. A tap adds or removes that item's value and reports a new set, never mutating the one you passed.

FossCheckboxGroup<String>(
  label: 'Frameworks',
  values: selected,
  onChanged: (next) => setState(() => selected = next),
  children: const [
    FossCheckboxItem(value: 'next', label: 'Next.js'),
    FossCheckboxItem(value: 'vite', label: 'Vite'),
  ],
);

Set variant: FossCheckboxGroupVariant.card to wrap each option in a full-width, selectable bordered card that tints when checked or hovered.

FossCheckboxGroup<String>(
  values: selected,
  variant: FossCheckboxGroupVariant.card,
  onChanged: (next) => setState(() => selected = next),
  children: const [
    FossCheckboxItem(
      value: 'next',
      label: 'Next.js',
      description: 'React framework',
    ),
    FossCheckboxItem(value: 'vite', label: 'Vite'),
  ],
);

API

FossCheckbox

Prop	Type	Default	Description
`value`	`bool?`	`false`	Checked state: `true`, `false`, or `null` for indeterminate.
`onChanged`	`ValueChanged<bool>?`	`null`	Called with the new definite state on a tap. Null disables it.
`label`	`String?`	`null`	Title beside the box.
`description`	`String?`	`null`	Secondary line below the label.
`errorText`	`String?`	`null`	Error caption below the control. A non-null value marks it invalid.
`enabled`	`bool`	`true`	Whether it accepts input. Disabled when false or `onChanged` is null.
`style`	`FossCheckboxStyle?`	`null`	Per-instance overrides on the theme.

FossCheckboxGroup

Prop	Type	Default	Description
`children`	`List<Widget>`	required	The `FossCheckboxItem` options, each of value type `T`.
`values`	`Set<T>`	`{}`	The set of checked values.
`onChanged`	`ValueChanged<Set<T>>?`	`null`	Called with the new set when an option is toggled. Null disables the group.
`label`	`String?`	`null`	Label rendered above the options.
`errorText`	`String?`	`null`	Error caption below the options. A non-null value marks the group invalid.
`variant`	`FossCheckboxGroupVariant`	`plain`	The visual treatment.
`enabled`	`bool`	`true`	Whether the group accepts input.

FossCheckboxItem

Prop	Type	Default	Description
`value`	`T`	required	The value this option contributes to the group, compared by `==`.
`label`	`String?`	`null`	Title beside the box.
`description`	`String?`	`null`	Secondary line below the label.
`enabled`	`bool`	`true`	Whether it accepts input. Disabled when false or the group is disabled.
`style`	`FossCheckboxStyle?`	`null`	Per-instance overrides on the theme.

FossCheckboxGroupVariant

plain, card.

Live demo

Open the interactive gallery to try every variant, size, and state with live knobs.

On this page