> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SettingsRow

> Una riga di interruttore etichettata con proprietà di controllo flat e composizione dell'etichetta nativa.

## Panoramica

`SettingsRow` combina l'aspetto di [ListItem](https://docs.twenty.com/it/ui/primitives/navigation/list-item.md) con [Switch](https://docs.twenty.com/it/ui/primitives/input/switch.md). Esegue il rendering di un'etichetta nativa associata al relativo interruttore. La tua applicazione fornisce il contenuto della riga e gestisce eventuali aggiornamenti delle preferenze.

**Light**

[Esempio di riga delle impostazioni (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Esempio di riga delle impostazioni (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--display)

## Utilizzo

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => (
  <SettingsRow startElement={<IconBell aria-hidden />}>
    Notifications
  </SettingsRow>
);
```

## Opzioni visive

Confronta le dimensioni dell'interruttore e gli stati selezionato, disabilitato e di sola lettura.

**Light**

[Dimensioni e stati della riga delle impostazioni (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Dimensioni e stati della riga delle impostazioni (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--catalog)

## Configura l'interruttore

Passa le [prop di Switch](https://docs.twenty.com/it/ui/primitives/input/switch.md) direttamente a `SettingsRow`. Lo stato selezionato, i dettagli dell'evento, il comportamento disabilitato e di sola lettura, le dimensioni, la configurazione del modulo nativo, gli handler, i ref e la composizione del rendering configurano l'interruttore. `children` fornisce l'etichetta visibile della riga.

Usa `checked` e `onCheckedChange` quando la tua applicazione gestisce il valore. Il gestore riceve lo stato selezionato successivo e i dettagli dell'evento Base UI. Facendo clic sull'etichetta o sull'interruttore viene richiamato una sola volta. Chiama `eventDetails.cancel()` per rifiutare una modifica e mantieni invariato il valore controllato quando la modifica viene annullata.

```tsx theme={null}
import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => {
  const [enabled, setEnabled] = useState(false);

  return (
    <SettingsRow
      startElement={<IconBell aria-hidden />}
      checked={enabled}
      onCheckedChange={setEnabled}
    >
      Notifications
    </SettingsRow>
  );
};
```

Usa `defaultChecked` per un'impostazione non controllata. Gli utenti della tastiera attivano lo stato attivo dell'interruttore e premono Spazio. `disabled` disabilita il controllo e applica l'aspetto disabilitato della riga. `readOnly` impedisce le modifiche mantenendo l'interruttore attivabile.

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const WorkspaceSettings = () => (
  <>
    <SettingsRow disabled>Notifications</SettingsRow>
    <SettingsRow readOnly defaultChecked>
      Activity history
    </SettingsRow>
  </>
);
```

## Contenuto della riga e testo accessibile

`children`, `startElement` e `description` accettano nodi gestiti dal chiamante. I children forniscono il nome accessibile dell'interruttore, mentre la descrizione fornisce la relativa descrizione accessibile. Mantieni non interattivo il contenuto all'interno dell'etichetta. Usa [ListItemButton](https://docs.twenty.com/it/ui/components/navigation/list-item-button.md) per le righe di azione, oppure componi [ListItem](https://docs.twenty.com/it/ui/primitives/navigation/list-item.md) con un link per la navigazione.

**Light**

[Riga delle impostazioni con una descrizione (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--with-description\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Riga delle impostazioni con una descrizione (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--with-description\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--with-description)

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const WeeklyDigestSetting = () => (
  <SettingsRow defaultChecked description="Sent every Monday" name="digest">
    Weekly digest
  </SettingsRow>
);
```

Imposta `aria-label`, `aria-labelledby` o `aria-describedby` per fornire il tuo testo accessibile per l'interruttore. Un valore `aria-label` esplicito sostituisce l'associazione del nome generata; i valori `aria-labelledby` e `aria-describedby` espliciti sostituiscono le associazioni generate corrispondenti.

## Destinazioni native e composizione

Le normali prop native configurano il controllo. La personalizzazione dell'etichetta ha due nomi espliciti:

| Props | Destinazione |
| - | - |
| Attributi nativi, handler, `className`, `style`, `ref` e `render` | La radice Switch visibile |
| `inputRef`, `name`, `value`, `uncheckedValue`, `required` e `form` | La casella di controllo nativa sottostante di Switch |
| `labelRef` e attributi, handler, classi e stili forniti tramite `labelRender` | L'etichetta nativa esterna |

`htmlFor` dell'etichetta viene gestito internamente e segue `id`, oppure un ID di controllo generato quando non viene fornito alcun ID. Con la composizione Switch predefinita, questo ID identifica la casella di controllo sottostante. Con `nativeButton`, identifica il pulsante visibile. `ref` fa riferimento alla radice visibile in entrambi i casi.

Usa `labelRender` per personalizzare l'etichetta nativa della riga. Mantieni un elemento label e inoltra le prop della callback di rendering al tuo elemento. Il relativo `props.children` contiene l'intera riga, incluso l'interruttore. La composizione dell'elemento unisce le relative classi e stili con quelli predefiniti della riga.

```tsx theme={null}
import { useRef } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';

export const ComposedNotificationSetting = () => {
  const labelRef = useRef<HTMLLabelElement>(null);
  const controlRef = useRef<HTMLElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <SettingsRow
      id="notification-control"
      ref={controlRef}
      inputRef={inputRef}
      nativeButton
      render={<button />}
      labelRef={labelRef}
      labelRender={<label id="notification-row" data-setting="notifications" />}
    >
      Notifications
    </SettingsRow>
  );
};
```

`onClick` riceve i clic sul controllo. Gli handler nativi forniti tramite `labelRender` ricevono gli eventi dell'etichetta e gli eventi del controllo propagati. La chiamata a `preventDefault()` su un clic dell'etichetta impedisce l'attivazione nativa del relativo controllo. Usa `onCheckedChange` per gli aggiornamenti delle preferenze, anziché dedurre lo stato da un clic sull'etichetta.

L'interruttore usa per impostazione predefinita `size="sm"`; usa `"md"` per un interruttore più grande. L'altezza della riga rimane invariata. `focused` applica l'aspetto evidenziato della riga senza spostare lo stato attivo della tastiera. `className`, `style` e `render` accettano callback dello stato di Switch e personalizzano il controllo. Fornisci classi e stili dell'etichetta tramite `labelRender` per personalizzare la riga.

## Renderer del componente front-end

All'interno di un componente front-end, usa la composizione del pulsante nativo per un interruttore annidato nell'etichetta della riga:

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const FrontComponentNotificationSetting = () => (
  <SettingsRow nativeButton render={<button />}>
    Notifications
  </SettingsRow>
);
```

Questa composizione si attiva una sola volta quando si fa clic sull'etichetta o sul controllo. Il bridge asincrono degli eventi del renderer non può annullare in tempo l'attivazione predefinita dell'etichetta host per un controllo basato su span, il che può produrre callback di modifica duplicate quando si fa clic direttamente sul controllo. Gli attributi di convalida del modulo nativo, come `required`, vengono anch'essi filtrati dal renderer corrente. `SettingsRow` autonomo mantiene il contratto completo del modulo Switch.

## Moduli e reimpostazione

`name`, `value` e `required` configurano la casella di controllo sottostante per l'invio e la convalida del modulo. Un interruttore selezionato invia il proprio valore. Un interruttore non selezionato omette il valore, a meno che non venga fornito `uncheckedValue`. Usa `form` per associare l'input a un modulo esterno all'albero padre della riga.

Per la reimpostazione di un modulo controllato, ripristina il valore selezionato gestito dall'applicazione nell'handler `onReset` del modulo. Base UI 1.8 non ripristina lo stato dell'interruttore non controllato alla reimpostazione del modulo nativo. `SettingsRow` mantiene questo comportamento upstream.

```tsx theme={null}
import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { Button } from 'twenty-ui/primitives/input';

export const NotificationPreferences = () => {
  const [enabled, setEnabled] = useState(true);

  return (
    <form onReset={() => setEnabled(true)}>
      <SettingsRow
        checked={enabled}
        onCheckedChange={setEnabled}
        name="notifications"
        value="enabled"
        uncheckedValue="disabled"
      >
        Notifications
      </SettingsRow>
      <Button type="reset">Reset</Button>
    </form>
  );
};
```

## Props

**checked** `boolean`

Whether the switch is currently active.

To render an uncontrolled switch, use the `defaultChecked` prop instead.

**children** `ReactNode` *required*

Visible label and default accessible name of the switch. Use non-interactive node content.

**className** `string | ((state: SwitchRootState) =\> string | undefined)`

Customizes the visible Switch root and accepts a Switch state callback.

**defaultChecked** `boolean` (default: false)

Whether the switch is initially active.

To render a controlled switch, use the `checked` prop instead.

**description** `ReactNode`

Non-interactive supporting node content, used as the default accessible description of the switch.

**disabled** `boolean` (default: false)

Whether the component should ignore user interaction.

**focused** `boolean` (default: false)

Applies the highlighted row style without moving keyboard focus.

**form** `string`

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

**id** `string`

Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID.

**inputRef** `Ref\<HTMLInputElement\>`

Targets the underlying native checkbox.

**labelRef** `Ref\<HTMLLabelElement\>`

Targets the outer native label.

**labelRender** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Customizes the outer native label with its complete composed row children. Preserve a label element and forward its props to retain control association.

**name** `string`

Identifies the field when a form is submitted.

**nativeButton** `boolean` (default: 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.

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

Receives the next checked value and Base UI event details. Controlled callers own accepted state updates; cancellation prevents a change.

**onClick** `((event: BaseUIEvent\<MouseEvent\<HTMLSpanElement, MouseEvent\>\>) =\> void)`

Native click handler for the visible Switch root.

**readOnly** `boolean` (default: false)

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

**ref** `Ref\<HTMLSpanElement\>`

Targets the visible Switch root, which defaults to a span.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, SwitchRootState\>`

Customizes the visible Switch root with control props and Switch state. Use nativeButton when composing a button.

**required** `boolean` (default: false)

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

**size** `"md" | "sm"` (default: sm)

Visual size of the switch. Defaults to sm.

**startElement** `ReactNode`

Non-interactive node content before the label.

**style** `CSSProperties | ((state: SwitchRootState) =\> CSSProperties | undefined)`

Customizes the visible Switch root and accepts a Switch state callback.

**uncheckedValue** `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.

**value** `string`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.