> ## 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 fila de interruptor etiquetada con props de control plano y composición de etiqueta nativa.

## Resumen

`SettingsRow` combina la apariencia de [ListItem](https://docs.twenty.com/es/ui/primitives/navigation/list-item.md) con [Switch](https://docs.twenty.com/es/ui/primitives/input/switch.md). Representa una etiqueta nativa asociada a su interruptor. Tu aplicación proporciona el contenido de la fila y gestiona las actualizaciones de preferencias.

**Light**

[Ejemplo de fila de configuración (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Ejemplo de fila de configuración (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)

## "Uso"

```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>
);
```

## Opciones visuales

Compara los tamaños de los interruptores y los estados activado, deshabilitado y de solo lectura.

**Light**

[Tamaños y estados de las filas de configuración (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Tamaños y estados de las filas de configuración (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 el interruptor

Pasa las [props de Switch](https://docs.twenty.com/es/ui/primitives/input/switch.md) directamente a `SettingsRow`. El estado marcado, los detalles del evento, el comportamiento deshabilitado y de solo lectura, el tamaño, la configuración de formulario nativo, los controladores, las refs y la composición de renderizado configuran el interruptor. `children` proporciona la etiqueta visible de la fila.

Usa `checked` y `onCheckedChange` cuando tu aplicación gestione el valor. El controlador recibe el siguiente estado marcado y los detalles del evento de Base UI. Al hacer clic en la etiqueta o el interruptor, se invoca una vez. Llama a `eventDetails.cancel()` para rechazar un cambio y mantén tu valor controlado sin modificar cuando se cancele el cambio.

```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` para una configuración no controlada. Los usuarios de teclado enfocan el interruptor y presionan la barra espaciadora. `disabled` deshabilita el control y aplica la apariencia deshabilitada de la fila. `readOnly` impide los cambios mientras mantiene el interruptor enfocable.

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

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

## Contenido de la fila y texto accesible

`children`, `startElement` y `description` aceptan nodos propiedad del autor de la llamada. Los elementos secundarios proporcionan el nombre accesible del interruptor, y la descripción proporciona su descripción accesible. Mantén no interactivo el contenido dentro de la etiqueta. Usa [ListItemButton](https://docs.twenty.com/es/ui/components/navigation/list-item-button.md) para filas de acciones o combina [ListItem](https://docs.twenty.com/es/ui/primitives/navigation/list-item.md) con un enlace para la navegación.

**Light**

[Fila de configuración con una descripción (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--with-description\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Fila de configuración con una descripción (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>
);
```

Establece `aria-label`, `aria-labelledby` o `aria-describedby` para proporcionar tu propio texto accesible para el interruptor. Un `aria-label` explícito reemplaza la asociación de nombre generada; los valores explícitos de `aria-labelledby` y `aria-describedby` reemplazan las asociaciones generadas correspondientes.

## Destinos nativos y composición

Las props nativas habituales configuran el control. La personalización de etiquetas tiene dos nombres explícitos:

| "Props" | Destino |
| - | - |
| Atributos nativos, controladores, `className`, `style`, `ref` y `render` | La raíz visible de Switch |
| `inputRef`, `name`, `value`, `uncheckedValue`, `required` y `form` | La casilla de verificación nativa subyacente de Switch |
| `labelRef` y atributos, controladores, clases y estilos proporcionados mediante `labelRender` | La etiqueta nativa externa |

El `htmlFor` de la etiqueta se gestiona internamente y sigue a `id`, o a un ID de control generado cuando no se proporciona ningún ID. Con la composición predeterminada de Switch, este ID identifica la casilla de verificación subyacente. Con `nativeButton`, identifica el botón visible. `ref` se dirige a la raíz visible en ambos casos.

Usa `labelRender` para personalizar la etiqueta nativa de la fila. Conserva un elemento de etiqueta y reenvía las props de devolución de llamada de renderizado a tu elemento. Sus `props.children` contienen la fila completa, incluido el interruptor. La composición de elementos combina sus clases y estilos con los valores predeterminados de la fila.

```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` recibe clics del control. Los controladores nativos proporcionados mediante `labelRender` reciben eventos de etiqueta y eventos de control propagados. Llamar a `preventDefault()` al hacer clic en una etiqueta impide su activación de control nativa. Usa `onCheckedChange` para las actualizaciones de preferencias, en lugar de inferir el estado a partir de un clic en una etiqueta.

El interruptor usa de forma predeterminada `size="sm"`; usa `"md"` para un interruptor más grande. La altura de la fila se mantiene igual. `focused` aplica la apariencia resaltada de la fila sin mover el foco del teclado. `className`, `style` y `render` aceptan devoluciones de llamada de estado de Switch y personalizan el control. Proporciona clases y estilos de etiqueta mediante `labelRender` para personalizar la fila.

## Renderizador de componentes de front-end

Dentro de un componente de front-end, usa la composición de botón nativo para un interruptor anidado en la etiqueta de la fila:

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

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

Esta composición se activa una vez al hacer clic en la etiqueta o el control. El puente de eventos asíncrono del renderizador no puede cancelar a tiempo la activación predeterminada de la etiqueta del host para un control basado en span, lo que puede producir devoluciones de llamada de cambio duplicadas al hacer clic directamente en un control. Los atributos de validación de formularios nativos, como `required`, también se filtran mediante el renderizador actual. `SettingsRow` independiente conserva el contrato completo de formulario de Switch.

## Formularios y restablecimiento

`name`, `value` y `required` configuran la casilla de verificación subyacente para el envío y la validación de formularios. Un interruptor marcado envía su valor. Un interruptor sin marcar omite el valor, a menos que se proporcione `uncheckedValue`. Usa `form` para asociar la entrada con un formulario fuera del árbol principal de la fila.

Para el restablecimiento de formulario controlado, restaura el valor marcado gestionado por la aplicación en el controlador `onReset` del formulario. Base UI 1.8 no restaura el estado del interruptor no controlado al restablecer un formulario nativo. `SettingsRow` conserva este comportamiento ascendente.

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