> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thehuxdesign.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Toggle
> Two-state toggle button for formatting controls and feature toggles
## Overview
`HuxToggle` is a two-state button component commonly used for formatting controls (like bold, italic) or feature toggles. It supports both icon-only and icon-with-text configurations, with multiple variants and sizes.
## Basic Usage
```dart theme={null}
HuxToggle(
value: isBold,
onChanged: (value) => setState(() => isBold = value),
icon: FeatherIcons.bold,
label: 'Bold', // Optional visual label
semanticLabel: 'Bold', // Optional when label is provided
)
```
## Icon-Only Toggle
```dart theme={null}
HuxToggle(
value: isEditing,
onChanged: (value) => setState(() => isEditing = value),
icon: FeatherIcons.edit2,
semanticLabel: 'Edit', // Required when label is null
)
```
## Variants
HuxToggle supports four visual variants through the `HuxButtonVariant` enum:
### Primary Toggle
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
variant: HuxButtonVariant.primary, // Default
)
```
### Secondary Toggle
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
variant: HuxButtonVariant.secondary,
)
```
### Outline Toggle
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
variant: HuxButtonVariant.outline,
)
```
### Ghost Toggle
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
variant: HuxButtonVariant.ghost,
)
```
## Sizes
Control toggle dimensions with three size options:
### Small Toggle
Compact size for tight spaces (32px height).
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
size: HuxToggleSize.small,
)
```
### Medium Toggle (Default)
Default size for most use cases (40px height).
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
size: HuxToggleSize.medium, // Default
)
```
### Large Toggle
Prominent size for important actions (48px height).
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
size: HuxToggleSize.large,
)
```
## States
### Disabled State
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: null, // Disable the toggle
icon: FeatherIcons.edit2,
isDisabled: true,
)
```
### Custom Primary Color
```dart theme={null}
HuxToggle(
value: isActive,
onChanged: (value) => setState(() => isActive = value),
icon: FeatherIcons.edit2,
primaryColor: Colors.deepPurple,
)
```
## API Reference
### HuxToggle Properties
| Property | Type | Default | Description |
| --------------- | --------------------- | ------------ | ----------------------------------------------------- |
| `value` | `bool` | **required** | The current toggle state (on/off) |
| `onChanged` | `ValueChanged?` | `null` | Callback triggered when toggle state changes |
| `icon` | `IconData` | **required** | The icon to display in the toggle |
| `label` | `String?` | `null` | Optional text label to display next to the icon |
| `semanticLabel` | `String?` | `null` | Accessibility label used when `label` is not provided |
| `size` | `HuxToggleSize` | `medium` | Size variant of the toggle |
| `variant` | `HuxButtonVariant` | `primary` | Visual variant of the toggle |
| `isDisabled` | `bool` | `false` | Whether the toggle is disabled |
| `primaryColor` | `Color?` | `null` | Optional custom primary color |
> If `label` is omitted (icon-only toggle), provide `semanticLabel` for accessibility.
### HuxToggleSize Enum
* `HuxToggleSize.small` - 32px height, compact padding
* `HuxToggleSize.medium` - 40px height, standard padding
* `HuxToggleSize.large` - 48px height, generous padding
## Accessibility
HuxToggle includes several accessibility features:
### Automatic Contrast
Text and icon colors are automatically calculated to ensure WCAG AA compliance (4.5:1 contrast ratio) against any background color.
### Semantic Roles
Toggles include proper semantic roles for screen readers and announce `label` or `semanticLabel`.
### Focus States
Keyboard navigation support with visible focus indicators.
### Disabled States
Proper disabled state handling for assistive technologies.
## Best Practices
* Use **Primary** for important toggles that need emphasis
* Use **Secondary** for standard toggles in content areas
* Use **Outline** for toggles that need visual separation
* Use **Ghost** for subtle toggles in toolbars
* Use **Large** for important feature toggles
* Use **Medium** for most standard interactions
* Use **Small** for compact toolbars or formatting controls
* Choose clear, meaningful icons that represent the action
* Use standard icons (bold, italic) for formatting controls
* Add labels for actions that aren't immediately clear
* For icon-only toggles, always provide `semanticLabel`
* Let toggles adapt to your app's theme
* Use `primaryColor` only for specific emphasis
* Maintain consistent styling within toggle groups
## Examples
See toggles in action within forms
Learn how to build a formatting toolbar
Apply custom colors and themes
Ensure your toggles are accessible