Switch
Toggle a binary on/off setting with immediate effect.
Toggle a binary on/off setting with immediate effect.
Contract
| Axis | Contract |
|---|---|
| State | Pass checked to control the value, or leave it null and start from defaultChecked, which is false. onCheckedChange reports the next value in both cases. |
| Availability | readOnly refuses changes but keeps focus and keyboard reach. disabled refuses changes and marks the switch as unavailable for assistive technology. Both keep the current value visible. |
| Labeling | The switch renders no label of its own. Place visible text beside it and pass the same text to semanticLabel, otherwise the switch has no accessible name. Space toggles a focused editable switch on key release. |
| Validation | invalid only paints the danger border. There is no error text slot and no form field wrapper, so render the message and clear invalid yourself. |
Reach for a switch when flipping it applies the setting right away. Use a checkbox when the value is collected and submitted with the rest of a form: TRSwitch takes no name, value, or required, so a submitted value has to come from your own state. There is also no size variant.
Install
Add the package, then import its public library.
flutter pub add tinyrack_uiimport 'package:tinyrack_ui/tinyrack_ui.dart';Playground
Usage
import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';
class BackupSetting extends StatefulWidget {
const BackupSetting({super.key});
@override
State<BackupSetting> createState() => _BackupSettingState();
}
class _BackupSettingState extends State<BackupSetting> {
bool enabled = false;
@override
Widget build(BuildContext context) {
return Row(
mainAxisSize: MainAxisSize.min,
spacing: TRSpacing.small,
children: [
TRSwitch(
checked: enabled,
onCheckedChange: (next) => setState(() => enabled = next),
semanticLabel: 'Automatic backups',
),
const TRText('Automatic backups'),
],
);
}
}Examples
Controlled setting permalink
Hold the value in `checked` and update it from `onCheckedChange` when the setting drives other UI. Pair the switch with visible text and repeat that text in `semanticLabel`.
Editable, read only, and disabled permalink
`readOnly` keeps the switch focusable and keyboard-reachable while refusing changes. `disabled` refuses changes too and marks the switch as unavailable for assistive technology. Both leave the current value visible.
Required setting and recovery permalink
`invalid` only paints the danger border. Render the message yourself and clear both once the setting is turned on, because `TRSwitch` has no error text slot and no form validation.
API
State and availability
| Prop | Type / default | Purpose |
|---|---|---|
checked | bool? · null | Controls the value. While it is non-null the widget never changes state on its own. |
defaultChecked | bool · false | Sets the initial value of an uncontrolled switch. It is ignored once checked is provided. |
onCheckedChange | ValueChanged<bool>? · null | Reports the next value after a tap or Space. There is no way to veto the change. |
disabled | bool · false | Removes pointer and keyboard activation and marks the switch as disabled for assistive technology. |
readOnly | bool · false | Refuses changes while the switch stays focusable and reports its normal enabled state. |
invalid | bool · false | Paints the danger border. It does not change behavior or announce an error. |
Naming, focus, and composition
| Prop | Type / default | Purpose |
|---|---|---|
semanticLabel | String? · null | Names the switch for assistive technology. Without it the switch has no accessible name, because it renders no label of its own. |
focusNode | FocusNode? · null | Supplies your own focus node. Without it the switch creates and disposes an internal one. |
autofocus | bool · false | Requests focus when the switch is first inserted into the tree. |
thumbKey | Key? · null | Identifies the moving thumb so tests and tooling can measure its geometry. |