Toggle

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

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

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

HuxToggle(
  value: isActive,
  onChanged: (value) => setState(() => isActive = value),
  icon: FeatherIcons.edit2,
  variant: HuxButtonVariant.primary, // Default
)

Secondary Toggle

HuxToggle(
  value: isActive,
  onChanged: (value) => setState(() => isActive = value),
  icon: FeatherIcons.edit2,
  variant: HuxButtonVariant.secondary,
)

Outline Toggle

HuxToggle(
  value: isActive,
  onChanged: (value) => setState(() => isActive = value),
  icon: FeatherIcons.edit2,
  variant: HuxButtonVariant.outline,
)

Ghost Toggle

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).

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).

HuxToggle(
  value: isActive,
  onChanged: (value) => setState(() => isActive = value),
  icon: FeatherIcons.edit2,
  size: HuxToggleSize.medium, // Default
)

Large Toggle

Prominent size for important actions (48px height).

HuxToggle(
  value: isActive,
  onChanged: (value) => setState(() => isActive = value),
  icon: FeatherIcons.edit2,
  size: HuxToggleSize.large,
)

States

Disabled State

HuxToggle(
  value: isActive,
  onChanged: null, // Disable the toggle
  icon: FeatherIcons.edit2,
  isDisabled: true,
)

Custom Primary Color

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<bool>?`	`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

Choose the Right Variant

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

Size Appropriately

Use Large for important feature toggles
Use Medium for most standard interactions
Use Small for compact toolbars or formatting controls

Icon Selection

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

Theme Integration

Let toggles adapt to your app’s theme
Use primaryColor only for specific emphasis
Maintain consistent styling within toggle groups

Examples

Form Building

See toggles in action within forms

Text Editor

Learn how to build a formatting toolbar

Custom Theming

Apply custom colors and themes

Accessibility

Ensure your toggles are accessible

Getting Started

Components

Advanced

Overview

Basic Usage

Icon-Only Toggle

Variants

Primary Toggle

Secondary Toggle

Outline Toggle

Ghost Toggle

Sizes

Small Toggle

Medium Toggle (Default)

Large Toggle

States

Disabled State

Custom Primary Color

API Reference

HuxToggle Properties

HuxToggleSize Enum

Accessibility

Automatic Contrast

Semantic Roles

Focus States

Disabled States

Best Practices

Examples

Form Building

Text Editor

Custom Theming

Accessibility

​Overview

​Basic Usage

​Icon-Only Toggle

​Variants

​Primary Toggle

​Secondary Toggle

​Outline Toggle

​Ghost Toggle

​Sizes

​Small Toggle

​Medium Toggle (Default)

​Large Toggle

​States

​Disabled State

​Custom Primary Color

​API Reference

​HuxToggle Properties

​HuxToggleSize Enum

​Accessibility

​Automatic Contrast

​Semantic Roles

​Focus States

​Disabled States

​Best Practices

​Examples

Form Building

Text Editor

Custom Theming

Accessibility

Overview

Basic Usage

Icon-Only Toggle

Variants

Primary Toggle

Secondary Toggle

Outline Toggle

Ghost Toggle

Sizes

Small Toggle

Medium Toggle (Default)

Large Toggle

States

Disabled State

Custom Primary Color

API Reference

HuxToggle Properties

HuxToggleSize Enum

Accessibility

Automatic Contrast

Semantic Roles

Focus States

Disabled States

Best Practices

Examples