Toggle

Guidelines
React API Reference
Blazor API Reference

Toggle buttons are interactive components that allow users to switch between two mutually exclusive states: on and off. They provide immediate visual feedback about their current state and are ideal for settings, preferences, or any binary choice where the user needs to understand the current state at a glance.

Guidance

Aspect	Best Practice
Usage	Use toggles for binary states like enabling/disabling features, showing/hiding content, or switching between two modes.
Content	Use clear labels, icons, or both to communicate the toggle’s purpose and current state.
Behavior	Provide immediate visual feedback when the state changes, with smooth transitions between states.
States	Ensure clear visual distinction between on/off states, with appropriate hover, focus, and disabled states.
Feedback	The toggle should clearly indicate its current state without requiring additional text or indicators.
Examples	Feature toggles, visibility controls, format options (bold, italic), or mode switches (light/dark theme).

Best Practices

Clear State Indication: Ensure the on and off states are visually distinct through color, iconography, or visual styling.
Consistent Behavior: Toggle state should change immediately upon interaction with clear visual feedback.
Appropriate Sizing: Use consistent sizing that provides adequate touch targets for all users.
Meaningful Labels: Provide descriptive labels or aria-labels that clearly communicate the toggle’s purpose.
Logical Grouping: When using multiple toggles, use the ToggleGroup component to group related toggles together with appropriate spacing.

Do’s and Don’ts

Do

Use toggles for binary states that take effect immediately.
Provide clear visual feedback for state changes.
Use consistent sizing and styling across your interface.
Include descriptive labels or aria-labels for accessibility.

Don't

Use toggles for actions that require confirmation or have consequences.
Make state changes too subtle or unclear.
Use toggles for mutually exclusive options with more than two states.
Rely solely on color to indicate state.

Additional Guidance

Accessibility: Toggles must be keyboard accessible, provide proper ARIA attributes, and clearly communicate their state to screen readers.
Psychological Impact:
- Immediate Feedback: Toggles provide instant gratification through immediate state changes, building user confidence.
- Control Perception: Users feel in control when they can easily switch between states with clear visual feedback.
- Cognitive Load: Well-designed toggles reduce cognitive load by clearly showing both the current state and the available alternative.

Import

import { Toggle } from '@strongtie/design-system/toggle';

Usage

<Toggle aria-label="Toggle bold">
  <MdFormatBold />
</Toggle>

Props

asChild

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

pressed

boolean

default:"undefined"

The controlled pressed state of the toggle.

defaultPressed

boolean

default:"undefined"

The default pressed state when the component is uncontrolled.

onPressedChange

(pressed: boolean) => void

default:"undefined"

Callback fired when the pressed state changes.

disabled

boolean

default:"undefined"

Whether the toggle is disabled.

variant

"default" | "outline"

default:"\"default\""

The visual variant of the toggle button.

size

"sm" | "default" | "lg"

default:"\"default\""

The size of the toggle button.

Styling Classes

The component applies the following CSS classes:

toggle - Base toggle class

Usage Examples

<Toggle>Toggle</Toggle>

For more examples, visit the Storybook.

The Blazor implementation provides a StudsToggle component that can be used individually or grouped together to create toggle group functionality.

Example

<StudsToggle @bind-Value="isBold" Text="Bold" Icon="format_bold" />

`<StudsToggle>` Parameters

Value

bool

default:"false"

The current toggle state (true for active, false for inactive).

ValueChanged

EventCallback<bool>

default:"null"

Callback fired when the toggle state changes.

Name

string

default:"null"

The name attribute for the underlying input element.

Disabled

bool

default:"false"

Whether the toggle button is disabled.

Text

string

default:"null"

The text content displayed on the toggle button.

Icon

string

default:"null"

The icon displayed when the toggle is inactive.

ToggleIcon

string

default:"null"

The icon displayed when the toggle is active. Falls back to Icon if not specified.

ButtonStyle

default:"ButtonStyle.Primary"

The button style when the toggle is inactive.

ToggleButtonStyle

ButtonStyle

default:"ButtonStyle.Primary"

The button style when the toggle is active.

Size

ButtonSize

default:"ButtonSize.Medium"

The size of the toggle button.

IsBusy

bool

default:"false"

Whether the toggle shows a loading/busy state.

BusyText

string

default:"null"

Text displayed when the toggle is in busy state.

Change

EventCallback<bool>

default:"null"

Additional callback fired when the toggle state changes.

Click

EventCallback<MouseEventArgs>

default:"null"

Callback fired when the toggle is clicked.

ValueExpression

Expression<Func<bool>>

default:"null"

Expression for model binding in forms.

InputAttributes

IReadOnlyDictionary<string, object>

default:"null"

Additional attributes for the underlying input element.

TabIndex

int

default:"0"

The tab index for keyboard navigation.

Placeholder

string

default:"null"

Placeholder text for the toggle (used in form scenarios).

Attributes

Dictionary<string, object>

Specifies additional custom attributes that will be rendered by the component.

MouseEnter

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse enters an item.

MouseLeave

EventCallback<ElementReference>

Gets or sets the callback that is invoked when the mouse leaves an item.

A callback that will be invoked when the user right-clicks the component. Commonly used to display a context menu.

Culture

CultureInfo

default:"CultureInfo.CurrentCulture"

Gets or sets the culture used to display localizable data (numbers, dates). Set by default to “CultureInfo.CurrentCulture”.

Style

string

Gets or sets the inline CSS style.

Visible

bool

default:"true"

Gets or sets a value indicating whether this “T:Studs.StudsComponent” is visible. Invisible components are not rendered.

Styling Classes

The component applies the following CSS classes:

toggle-button - Base toggle button class
-active - Applied when the toggle is active (Value = true)
-disabled - Applied when the toggle is disabled
-icon-only - Applied when only an icon is displayed (no text)

Usage Examples

<StudsToggle @bind-Value="isToggled"
             Text="Toggle"
             ButtonStyle="ButtonStyle.Ghost"
             ToggleButtonStyle="ButtonStyle.Secondary" />

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

Props

Styling Classes

Usage Examples

`<StudsToggle>` Parameters

Styling Classes

Usage Examples

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​Props

​Styling Classes

​Usage Examples

​<StudsToggle> Parameters

​Styling Classes

​Usage Examples

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

Props

Styling Classes

Usage Examples

`<StudsToggle>` Parameters

Styling Classes

Usage Examples