> ## 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

> A labeled switch row for settings and filters.

export const StoryEmbed = ({storyId, title, height = 240}) => <>
    <Tabs>
      <Tab title="Light">
        <iframe title={`${title} (light)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:light`} width="100%" height={height} loading="lazy" style={{
  border: 0
}} />
      </Tab>
      <Tab title="Dark">
        <iframe title={`${title} (dark)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:dark`} width="100%" height={height} loading="lazy" style={{
  border: 0
}} />
      </Tab>
    </Tabs>
    <a href={`https://storybook.twenty.com/?path=/story/${storyId}`}>
      Open in Storybook
    </a>
  </>;

`SettingsRow` combines [ListItem](/ui/primitives/navigation/list-item) and [Switch](/ui/primitives/input/switch). It associates the visible label with the switch, makes the whole row clickable, and keeps disabled behavior consistent.

<StoryEmbed storyId="ui-components-settingsrow--default" title="Settings row example" height={160} />

## Controlled setting

Pass `checked` and `onCheckedChange` when your application owns the value. The handler receives the next checked state and Base UI event details. Clicking either the label or switch invokes it once; keyboard users can focus the switch and press Space.

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

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

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

## Description and initial value

Use `defaultChecked` for an uncontrolled setting. `description` supplies supporting text and the switch's accessible description, while the children provide its accessible name.

<StoryEmbed storyId="ui-components-settingsrow--with-description" title="Settings row with a description" height={160} />

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

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

`name`, `value`, and `required` configure the switch's underlying checkbox for form submission. An unchecked switch does not submit a value.

## Disabled and read-only settings

Pass `disabled` once to disable both the row and switch. Use `readOnly` to prevent changes while keeping the switch focusable.

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

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

## Appearance and composition

The switch defaults to `size="sm"`; use `size="md"` for a larger switch. The row height stays the same. `focused` applies the row's highlighted style without moving keyboard focus.

Native label attributes, `className`, `style`, and `ref` target the outer label. The label and switch association is managed internally. Keep the children, description, and icon non-interactive. Use `onCheckedChange` for value updates.

For navigation or action rows, use [ListItem](/ui/primitives/navigation/list-item) with a button or link.

## Props

<ParamField body="checked" type="boolean">
  Controlled checked state of the switch.
</ParamField>

<ParamField body="children" type="ReactNode" required>
  Visible label and accessible name of the switch. Use non-interactive content.
</ParamField>

<ParamField body="defaultChecked" type="boolean" default="false">
  Initial checked state when uncontrolled.
</ParamField>

<ParamField body="description" type="ReactNode">
  Non-interactive supporting content, associated with the switch as its accessible description.
</ParamField>

<ParamField body="disabled" type="boolean" default="false">
  Disables both the row and its switch.
</ParamField>

<ParamField body="focused" type="boolean" default="false">
  Applies the highlighted row style without moving keyboard focus.
</ParamField>

<ParamField body="name" type="string">
  Name of the hidden checkbox used in form submission.
</ParamField>

<ParamField body="onCheckedChange" type="((checked: boolean, eventDetails: { reason: &#x22;none&#x22;; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)">
  Called when the switch value changes, with the next checked state and Base UI event details.
</ParamField>

<ParamField body="readOnly" type="boolean" default="false">
  Keeps the switch focusable while preventing changes.
</ParamField>

<ParamField body="required" type="boolean" default="false">
  Requires the switch to be checked for form submission.
</ParamField>

<ParamField body="size" type="&#x22;md&#x22; | &#x22;sm&#x22;" default="sm">
  Visual size of the switch. The row height stays the same.
</ParamField>

<ParamField body="startIcon" type="ReactNode">
  Decorative content before the label.
</ParamField>

<ParamField body="value" type="string">
  Value submitted when the switch is checked.
</ParamField>