Toggle

Usage

• Use Toggle for settings that take effect immediately without form submission.
• Use Checkbox instead when the user is selecting options to submit as part of a form.
• Toggle and Checkbox are not interchangeable — Toggle is an on/off switch, Checkbox is a multi-select control.

Appearance

• Three sizes are available: size="md" (default), size="sm", and size="xs".
• Use "md" in most contexts including settings pages and form layouts.
• Use "sm" in tighter layouts such as table rows, inline controls, or condensed settings panels.
• Use "xs" in the most space-constrained contexts.

Behaviors

• Toggle supports base, hover, focus, and disabled states.
• Disable a Toggle with isDisabled.
• Mark a Toggle as invalid with isInvalid and provide an error message.
• Labels truncate with an ellipsis by default. Set withTruncatedLabel={false} to allow wrapping.

Content

• Frame labels positively so the enabled state matches the action described. Avoid negative phrasing that creates double-negatives when off.
• Use description to provide extra context when the label alone doesn't explain the Toggle's effect. Keep descriptions to a short phrase without end punctuation.
• Do not restate the label in the description — add new information.
• Frame error messages as actionable steps the user can take to resolve the issue.

Best Practices

• Default Toggles to the safest or most common state. Never enable destructive or data-sharing settings by default.

Implementation Notes

• Toggle is a controlled component. Pass isChecked and onChange to manage state.
• Provide a label or ariaLabel (or ariaLabelledby) — the component throws if none is present.
• onChange receives a ChangeEvent<HTMLInputElement> in React and a native Event in Ember.
• labelOn and labelOff props are deprecated — do not use.
• size values "medium" and "small" are deprecated aliases for "md" and "sm".
• React: pass content via the label prop (string or ReactNode). Ember: use the @label arg or yield content into the :label named block.
• Ember component name is <PlumaToggle>. Args use @ prefix (e.g., @isChecked, @onChange, @size).