Forms

Segmented control

A row of mutually exclusive options drawn as one control, on native radios in a <fieldset>.

JxSegmentedControl import 'package:jx_cli/ui.dart' New in 0.0.3

Preview

Period

When to use it

  • Switching the period of a chart (Day / Week / Month).
  • A view mode (List / Grid).
  • Two to five short options.

States

View
Legend hidden
Period
Disabled

Minimal example

Dart
JxSegmentedControl(
  name: 'period',
  legend: 'Period',
  value: 'week',
  options: [(value: 'day', label: 'Day'), (value: 'week', label: 'Week')],
)

Complete example

A full Jaspr component you can paste into a project.

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

@client
class ChartPeriod extends StatefulComponent {
  const ChartPeriod({super.key});

  @override
  State<ChartPeriod> createState() => _ChartPeriodState();
}

class _ChartPeriodState extends State<ChartPeriod> {
  String period = 'week';

  @override
  Component build(BuildContext context) {
    return JxSegmentedControl(
      name: 'period',
      legend: 'Chart period',
      hideLegend: true,
      value: period,
      onChange: (value) => setState(() => period = value),
      options: const [
        (value: 'day', label: 'Day'),
        (value: 'week', label: 'Week'),
        (value: 'month', label: 'Month'),
      ],
    );
  }
}

Properties

Property Type Default Description
name String required Shared name of the radios; also prefixes their ids.
legend String required Name of the group.
options List<JxOption> required (value:, label:) records.
value String? null Selected value.
hideLegend bool false Keeps the legend for screen readers only.
disabled bool false Disables the whole group.
classes String? null Extra JX classes, appended after the component classes.

Events

Callback Type Fires when
onChange ValueChanged<String>? Another option is selected.

Customizing

  • Pass classes to add or override utilities: they come last, so classes: 'w:full' wins over the default width.
  • The selected segment is white on the gray track, with the shared focus ring.

Responsive

  • Keeps its natural width; use short labels so it fits on phones.

Accessibility

  • Native radios in a <fieldset> with a <legend>: arrow keys move the selection, Tab leaves the group.
  • The radios are visually hidden, not removed; the focus ring is drawn on the visible segment.

Limitations

  • Not for more than about five options: use a select instead.
  • No icons-only mode.