SwitchSettingsList

Notification preferences

Security alerts
Password changes and new recovery methods.
New device sign-in
When your account is used on a device for the first time.
Weekly summary

import { useState } from 'react';
import { SwitchSettingsItem, SwitchSettingsList } from '@rookcom/monarch-react';

function wait(ms: number) {
  return new Promise<void>((resolve) => setTimeout(resolve, ms));
}

function NotificationsDemo() {
  const [prefs, setPrefs] = useState({ alerts: true, devices: true, digest: false });
  const save = (key: keyof typeof prefs) => async (next: boolean) => {
    await wait(700);
    setPrefs((p) => ({ ...p, [key]: next }));
  };
  return (
    <div style={{ width: '100%', maxWidth: 560 }}>
      <SwitchSettingsList
        title="Security notifications"
        description="Emails about activity on your account."
      >
        <SwitchSettingsItem
          label="Security alerts"
          description="Password changes and new recovery methods."
          checked={prefs.alerts}
          onCheckedChange={save('alerts')}
        />
        <SwitchSettingsItem
          label="New device sign-in"
          description="When your account is used on a device for the first time."
          checked={prefs.devices}
          onCheckedChange={save('devices')}
        />
        <SwitchSettingsItem
          label="Weekly summary"
          checked={prefs.digest}
          onCheckedChange={save('digest')}
        />
      </SwitchSettingsList>
    </div>
  );
}

<NotificationsDemo />

Usage examples

Failed save, rollback and retry

import { SwitchSettingsItem, SwitchSettingsList } from '@rookcom/monarch-react';

function wait(ms: number) {
  return new Promise<void>((resolve) => setTimeout(resolve, ms));
}

function FailingDemo() {
  return (
    <div style={{ width: '100%', maxWidth: 560 }}>
      <SwitchSettingsList title="Delivery">
        <SwitchSettingsItem
          label="In-app notifications"
          description="This example always fails, to show rollback and retry."
          defaultChecked
          onCheckedChange={async () => {
            await wait(700);
            throw new Error('Check your connection and try again.');
          }}
        />
      </SwitchSettingsList>
    </div>
  );
}

<FailingDemo />

Purpose

Shows a group of on/off preferences, such as notification or privacy settings, where each switch saves immediately. Every row has its own saving, saved and failed state, so one failure never hides behind a page-level toast.

Use when

Each toggle is persisted on its own (a PATCH per preference) rather than with a form Save button.
Saves can fail and the user must see which setting did not stick.

Avoid when

Switches are submitted together with other fields: use Field with layout="row" and a Switch inside a form.
A single setting with no group: a Switch with label and description, or SettingsRow.

Design principles

Optimistic: the switch moves at once and rolls back only if the save fails.
Status lives on the row it belongs to: a spinner while saving, a brief "Saved", or the error with Retry.
Results are announced, not only shown, so screen-reader users hear "Saved" or the error.
No data fetching: the product passes checked and an onCheckedChange that returns its save promise.

API reference

import { SwitchSettingsItem, SwitchSettingsList } from '@rookcom/monarch-react';

Export	Kind	Rendering	Root class
`SwitchSettingsItem`	component	client	`.mn-switch-settings-`
`SwitchSettingsList`	component	client	`.mn-switch-settings-`

SwitchSettingsList renders a <div> (role group when it has a title or label) with an optional heading and a <ul> of rows; the ref goes to the <div>.

SwitchSettingsItem renders an <li> (ref) with the label, description, status and a Monarch Switch.

Status wording (labels: saving, saved, error, retry), savedDuration and getErrorMessage are set on the list and can be overridden per row.

Generated from the TypeScript declarations of packages/react/src/components/forms/switch-settings-list.

Properties

`SwitchSettingsItem`

One setting row: label and description on the left, the switch and its save status on the right.

Prop	Type	Description
`label` required	`ReactNode`	The setting's name. Labels the switch.
`checked`	`boolean`	The saved state (controlled).
`children`	`ReactNode`
`className`	`string`
`defaultChecked`	`boolean`	The initial saved state (uncontrolled).
`description`	`ReactNode`	What the setting does. Describes the switch.
`disabled`	`boolean`
`id`	`string`
`labels`	`SwitchSettingsLabels`	Override the list's status wording for this row.
`onCheckedChange`	`((checked: boolean) => void \| Promise<void>)`	Saves the new state. The switch moves at once; return a promise to show "Saving" and then "Saved", or reject it to roll the switch back and show the error with a retry button.
`onStatusChange`	`((status: SwitchSettingsStatus) => void)`	Called whenever the row's save status changes.