Forms

Checkbox

A checkbox with its label and an optional description.

JxCheckbox import 'package:jx_cli/ui.dart' Available since 0.0.2

Preview

When to use it

  • Accepting terms.
  • Opting in to emails.
  • Choosing several options in a list.

States

Disabled
Required, with an error

Minimal example

Dart
JxCheckbox(id: 'terms', label: 'I accept the terms')

Complete example

A full Jaspr component you can paste into a project.

Dart
import 'package:jaspr/dom.dart';
import 'package:jaspr/jaspr.dart';
import 'package:jx_cli/ui.dart';

/// Notification preferences, one checkbox per channel.
class Channels extends StatefulComponent {
  const Channels({super.key});

  @override
  State<Channels> createState() => _ChannelsState();
}

class _ChannelsState extends State<Channels> {
  final selected = <String>{'email'};

  @override
  Component build(BuildContext context) {
    return fieldset(classes: 'flex fd:col gap:3 bw:0 p:0', [
      legend(classes: 'fw:semibold mb:2', [.text('Notify me by')]),
      for (final (value, label) in [('email', 'Email'), ('sms', 'SMS'), ('push', 'Push')])
        JxCheckbox(
          id: 'channel-$value',
          name: 'channels',
          value: value,
          label: label,
          checked: selected.contains(value),
          onChange: (on) => setState(() => on ? selected.add(value) : selected.remove(value)),
        ),
    ]);
  }
}

Properties

Property Type Default Description
id String required Links the label and the description.
label String required Clickable label.
description String? null Secondary text, linked with aria-describedby .
error String? null Error under the label: sets aria-invalid and is linked with aria-describedby .
required bool false Native required , with an asterisk after the label.
name String? null Form field name.
value String? null Value sent with the form.
checked bool false Checked state.
disabled bool false Disables the checkbox.
classes String? null Extra JX classes, appended after the component classes.

Events

Callback Type Fires when
onChange ValueChanged<bool>? The box is checked or unchecked.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • The check color follows accent:blue-700.

Accessibility

  • A native checkbox inside its <label>: the whole text is clickable and Space toggles it.
  • Group related checkboxes in a <fieldset> with a <legend>.

Limitations

  • No indeterminate (mixed) state.