SwitchField

Needs review
WCAG 2.2 evidence
RTL
Web · iOS · Android

A setting row with a label, optional helper text and a switch at the end, applied immediately. The whole row, description included, is one <label>, so a click or tap anywhere toggles it (WCAG 2.5.8); Tab focuses the native role="switch" input and Space toggles it (2.1.1). The label alone is the accessible name and the description is linked with aria-describedby (1.3.1, 4.1.2); on is shown by the thumb position (1.4.1); keyboard focus draws the ring on the track. On iOS and Android the track is the Switch Mobile one. Consumer duties: label wording (positive statements), and announcing effects that are not visible.

import { SwitchField } from "@nexera-ui/react";

Loading example…

5
examples: 29
props: 7
live controls: 3
platforms: 11
WCAG criteria: 3
blocks use it

Try every prop. Copy the code.

Change the props and the code updates. Check light and dark, LTR and RTL, and phone width.

Loading…

Generated code

import { SwitchField } from "@nexera-ui/react";

<SwitchField />

Examples 4

The same examples as Storybook, rendered live. Open Code to copy one.

Values and disabled

Figma Value=On and State=Disabled; hover and Tab to the rows for the derived hover and focus states.

Loading example…

app.tsx

import { SwitchField } from "@nexera-ui/react";

export function ValuesAndDisabled() {
  return (
    <div className="flex flex-col gap-4">
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        defaultSelected
      />
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        isDisabled
      />
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        isDisabled
        defaultSelected
      />
    </div>
  );
}

Platforms

On iOS and Android the track is the Figma Switch Mobile one (51 x 31 pt, 52 x 32 dp).

Loading example…

app.tsx

import { SwitchField } from "@nexera-ui/react";

export function Platforms() {
  return (
    <div className="flex flex-col gap-4">
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        platform="web"
        defaultSelected
      />
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        platform="ios"
        defaultSelected
      />
      <SwitchField
        label="Email me about leave requests"
        description="When someone on your team applies or cancels"
        platform="android"
        defaultSelected
      />
    </div>
  );
}

Long text

Labels and descriptions wrap; the track stays aligned with the first line.

Loading example…

app.tsx

import { SwitchField } from "@nexera-ui/react";

<SwitchField
  label="Email me about every leave request on my team, including half days"
  description="Approvals, cancellations and changes to public holidays in every office you manage"
/>;

Right to left

Right-to-left: the text aligns right and the track sits at the end (left).

Loading example…

app.tsx

import { SwitchField } from "@nexera-ui/react";

<SwitchField
  label="أرسل لي بريدًا عن طلبات الإجازة"
  description="عندما يقدّم أحد أعضاء فريقك طلبًا أو يلغيه"
  defaultSelected
/>;

Props 29

Press "Try it" on a card to load that prop into the playground.

descriptionNexera

ReactNode

Helper text under the label. Linked with aria-describedby. Plain text: it sits inside the clickable row, so it must not contain links or buttons. Shown when provided.

errorMessageNexera

ReactNode | ((validation: ValidationResult) => ReactNode)

Error under the row, with an icon. Shown while the field is invalid (isInvalid, validate, or native isRequired validation on submit); defaults to the validation message.

platformNexera

"web" | "ios" | "android"

Platform look of the track. Defaults to the NexeraProvider platform.

classNameNexera

string

Extra classes for the root, merged last so they win over the defaults.

styleNexera

CSSProperties

Inline style of the root.

labelNexera

VisibleContent

Visible label. It is the accessible name (the description is not part of it), wraps and is never truncated. Write a positive statement ("Email me about leave requests"). No visible label.

aria-labelNexera

string

Overrides the name given by label. Avoid: the name must contain the visible text (WCAG 2.5.3). Accessible name. Translate it. Accessible name; aria-labelledby wins when both are set.

aria-labelledbyNexera

string

Id(s) of element(s) that name the switch instead of label. Id(s) of element(s) that name the switch; wins over aria-label. Id(s) of visible element(s) that name the switch.

validationBehaviorReact Aria

"native" | "aria"

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

valueReact Aria

string

The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue).

defaultSelectedReact Aria

boolean

Whether the element should be selected (uncontrolled).

isSelectedReact Aria

boolean

Whether the element should be selected (controlled).

onChangeReact Aria

(isSelected: boolean) => void

Handler that is called when the element's selection state changes.

isDisabledReact Aria

boolean

Whether the input is disabled.

isReadOnlyReact Aria

boolean

Whether the input can be selected but not changed by the user.

isRequiredReact Aria

boolean

Whether user input is required on the input before form submission.

isInvalidReact Aria

boolean

Whether the input value is invalid.

validateReact Aria

(value: boolean) => true | ValidationError | null

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

autoFocusReact Aria

boolean

Whether the element should receive focus on render.

nameReact Aria

string

The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).

formReact Aria

string

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).

idReact Aria

string

The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).

aria-describedbyReact Aria

string

Identifies the element (or elements) that describes the object.

onPressReact Aria

(e: PressEvent) => void

Handler that is called when the press is released over the target.

onPressStartReact Aria

(e: PressEvent) => void

Handler that is called when a press interaction starts.

onPressEndReact Aria

(e: PressEvent) => void

Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.

onPressChangeReact Aria

(isPressed: boolean) => void

Handler that is called when the press state changes.

onPressUpReact Aria

(e: PressEvent) => void

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

inputRefReact Aria

Ref<HTMLInputElement | null>

A ref for the HTML input element.

* Required. React Aria props shown are the ones most apps use; the component accepts the rest of its React Aria props too.

Accessible by default.

Built on React Aria, and covered by the WCAG 2.2 evidence generated on every build.

WCAG 2.2 evidence

7 direct · 4 supporting

1.3.1Info and RelationshipsLevel A · tested directly
1.4.1Use of ColorLevel A · tested directly
1.4.4Resize TextLevel AA · supporting test
1.4.10ReflowLevel AA · supporting test
1.4.12Text SpacingLevel AA · supporting test
2.1.1KeyboardLevel A · tested directly
2.4.7Focus VisibleLevel AA · tested directly
2.5.3Label in NameLevel A · tested directly
2.5.8Target Size (Minimum)Level AA · supporting test
3.3.1Error IdentificationLevel A · tested directly
4.1.2Name, Role, ValueLevel A · tested directly

Fits any width.

Nexera components respond to the space they are given. Drag the corner of the frame, or pick a width.

0 px · drag the corner

Styling hooks

Pass className to add Tailwind classes (merged last). State is exposed as data attributes, so you can style it with variants like data-pressed:.

data-disabled
data-readonly

Usage

<SwitchField className="data-disabled:opacity-90 shadow-sm" />

Theme studio

SwitchField

Try every prop. Copy the code.

Examples 4

Values and disabled

Platforms

Long text

Right to left

Props 29

Accessible by default.

WCAG 2.2 evidence

Fits any width.

Styling hooks

Used in blocks

Related components