Cambia

Panoramica

Usa Switch per una preferenza di attivazione o disattivazione. Assegna al controllo un’etichetta visibile o un nome accessibile.

Utilizzo

Stato non controllato

Usa defaultChecked per impostare lo stato iniziale di selezione. Lo switch gestisce le modifiche successive.

import { useId } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch id={switchId} name="notifications" />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};

Opzioni visive

Confronta le due dimensioni negli stati attivato, disattivato, disabilitato, di sola lettura e attivo. Utilizza gli esempi abilitati per provare ad attivare e disattivare.

Stato controllato

Passa checked e aggiornalo con onCheckedChange per gestire la stessa preferenza nello stato di React.

import { useId, useState } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();
  const [checked, setChecked] = useState(false);

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch
        id={switchId}
        name="notifications"
        checked={checked}
        onCheckedChange={setChecked}
      />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};

onCheckedChange riceve il booleano successivo e i dettagli dell’evento. La prop size accetta sm o md e per impostazione predefinita è md. Per una riga a larghezza intera coerente con un’icona, una descrizione e un interruttore, usa SettingsRow.

Tastiera e moduli

Tab sposta lo stato attivo sullo switch; Spazio lo attiva o disattiva. Facendo clic sulla relativa etichetta lo si attiva o disattiva. Usa disabled per impedire l’interazione oppure readOnly per mantenere un controllo selezionabile il cui valore non può essere modificato. Uno switch con nome invia il proprio valore quando è selezionato. Usa value per personalizzare tale valore e uncheckedValue se il modulo deve inviare un valore anche quando è disattivato.

Parti e contenuto personalizzato

Switch assembla la root con stile e il relativo thumb predefinito. Usa Switch.Root con Switch.Thumb per gestire il contenuto del thumb. Root gestisce lo stato e l’aspetto della traccia; Thumb esegue il rendering del contenuto fornito.

import { Switch } from 'twenty-ui/primitives/input';

export const CustomPreference = () => (
  <Switch.Root aria-label="Updates" defaultChecked>
    <Switch.Thumb></Switch.Thumb>
  </Switch.Root>
);

SwitchRootProps e SwitchThumbProps sono tipi pubblici esportati da twenty-ui/primitives/input. Entrambe le parti accettano attributi nativi, handler, ref, render e callback className e style basati sullo stato. Il ref di Root punta al controllo visibile; inputRef punta all’input nativo. Il ref della parte punta al relativo elemento sottoposto a rendering. Passa nativeButton con render={<button />} quando sostituisci Root con un pulsante. Le prop di aspetto appartengono a Root; classi e stili espliciti vengono uniti con quelli predefiniti. Thumb riceve lo stato corrente di checked, disabled, readOnly, required e Field. La sua posizione segue la direzione di lettura. L’assembly richiamabile e il relativo tipo SwitchProps rimangono supportati. Sostituisci l’assembly con Root e la sua parte quando fornisci contenuto thumb personalizzato anziché aggiungere un’altra parte ai figli dell’assembly. Per il ripristino controllato del modulo, gestisci l’onReset del modulo e ripristina checked al valore iniziale. Base UI 1.8 non ripristina lo stato dei componenti non controllati al ripristino nativo del modulo. required, form, value e uncheckedValue mantengono il comportamento dell’input nativo upstream.

Props

Il riferimento include le prop specifiche del componente e le prop Base UI ereditate. Sono accettati anche attributi nativi quali aria-label e data-*.

boolean

Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.

string | ((state: SwitchRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

predefinito:"false"

Whether the switch is initially active.To render a controlled switch, use the checked prop instead.

boolean

predefinito:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.

string

The id of the hidden input element.When nativeButton is true, the id is applied to the root element.

Ref<HTMLInputElement>

A ref to access the hidden <input> element.

string

Identifies the field when a form is submitted.

boolean

predefinito:"false"

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)

Event handler called when the switch is activated or deactivated.

boolean

predefinito:"false"

Whether the user should be unable to activate or deactivate the switch.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

boolean

predefinito:"false"

Whether the user must activate the switch before submitting a form.

"md" | "sm"

predefinito:"md"

Visual size of the switch.

CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

string

The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.

string

The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.

Switch.Root

boolean

Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.

string | ((state: SwitchRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

predefinito:"false"

Whether the switch is initially active.To render a controlled switch, use the checked prop instead.

boolean

predefinito:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.

string

The id of the hidden input element.When nativeButton is true, the id is applied to the root element.

Ref<HTMLInputElement>

A ref to access the hidden <input> element.

string

Identifies the field when a form is submitted.

boolean

predefinito:"false"

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

Event handler called when the switch is activated or deactivated.

boolean

predefinito:"false"

Whether the user should be unable to activate or deactivate the switch.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

boolean

predefinito:"false"

Whether the user must activate the switch before submitting a form.

"md" | "sm"

predefinito:"md"

Visual size of the switch.

CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

string

The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.

string

The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.

Switch.Thumb

string | ((state: SwitchThumbState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchThumbState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: SwitchThumbState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Stato non controllato

Opzioni visive

Stato controllato

Tastiera e moduli

Parti e contenuto personalizzato

Props

Switch.Root

Switch.Thumb

​Panoramica

​Utilizzo

​Stato non controllato

​Opzioni visive

​Stato controllato

​Tastiera e moduli

​Parti e contenuto personalizzato

​Props

​Switch.Root

​Switch.Thumb

Panoramica

Utilizzo

Stato non controllato

Opzioni visive

Stato controllato

Tastiera e moduli

Parti e contenuto personalizzato

Props

Switch.Root

Switch.Thumb