Skip to Content
BBRICKSv0.7.4
BlocksSettings

DefaultableRow

One settings line around a DefaultableSetting (or any control): the bold label, a muted help line, the control at the end (under them on a phone). The control inside takes its name from the label and reads the help with itself. off dims the row (a setting that does not apply while another is off).

import { DefaultableRow } from '@ergasti/bricks';

Examples

Follow the default, or set your own

A setting is either null (follow the platform default, shown beside it) or an override; a "Use default" button sets it back to null. It comes as a number, a switch or a choice.

Code
import { useState } from 'react';
import { DefaultableRow, DefaultableSetting } from '@ergasti/bricks';

function Settings() {
  const [days, setDays] = useState<string | null>(null);
  const [gifts, setGifts] = useState<boolean | null>(null);
  const [mode, setMode] = useState<string | null>('last_match');
  return (
    <div style={{ display: 'grid', gap: 4, maxWidth: 620 }}>
      <DefaultableRow label="Gift cooldown" help="Days before the same creator can pick another gift.">
        <DefaultableSetting kind="number" value={days} defaultValue={90} min={0} max={365} unit="days" onChange={setDays} />
      </DefaultableRow>
      <DefaultableRow label="One gift per challenge">
        <DefaultableSetting kind="switch" value={gifts} defaultValue={true} onChange={setGifts} />
      </DefaultableRow>
      <DefaultableRow label="When more than one code matches">
        <DefaultableSetting kind="choice" value={mode} defaultValue="first_match" options={[{ value: 'first_match', label: 'First match' }, { value: 'last_match', label: 'Last match' }]} onChange={setMode} />
      </DefaultableRow>
      <DefaultableRow label="Not editable" off>
        <DefaultableSetting kind="number" value="14" defaultValue={14} readOnly onChange={() => {}} />
      </DefaultableRow>
    </div>
  );
}

Disabled while saving

disabled locks the control (and its "Use default") while the app saves; readOnly is for a value the platform owns.

Code
import { DefaultableRow, DefaultableSetting } from '@ergasti/bricks';

function Disabled() {
  return (
    <div style={{ maxWidth: 620 }}>
      <DefaultableRow label="Gift cooldown">
        <DefaultableSetting kind="number" value="30" defaultValue={90} unit="days" disabled onChange={() => {}} />
      </DefaultableRow>
    </div>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses DefaultableRow. Written in docs/content/components/DefaultableRow.md; the props above are read from the code, which wins where the two disagree.

One settings line: a bold label, a muted help line and a control at the end (under them on a phone); use it to lay out a DefaultableSetting, or any single control, in a settings card.

It is the row half of the library's "follow the default / own value" settings pattern. Beyond layout, it gives the control inside its accessible name (the label's id) and its description (the help's id) through context, so a DefaultableSetting needs no label prop.

Anatomy

  1. Row (.kit-blk-defrow): flex, gap 16, 16px block padding, a 1px --line top border (none on the first row).
  2. Text (.kit-blk-defrow-t): the label in bold 14px (id used as the control's name) and the help in muted 13px.
  3. Control slot (.kit-blk-defrow-c): no-shrink, at most 60% wide, its DefaultableSetting aligned to the end.

Variants

PropLookUse when
defaultLabel and control side by sideDesktop and tablet.
offText and control at 55% opacityThe setting does not apply while another one is off.
help omittedLabel onlySelf-explanatory settings.
Below 600pxControl stacks under the text, start-alignedAutomatic (media query).

States

StateHow
Default—
Off (dimmed)off; also pass disabled to the control so it cannot change.
Long label / helpText wraps; the control keeps its width.

Usage

<DefaultableRow label="Gift cooldown" help="Days a creator waits after a gift before picking another one">
  <DefaultableSetting kind="number" value="45" defaultValue={60} min={1} max={365} unit="days" onChange={setCooldown} />
</DefaultableRow>
// Rows stacked in a card; the second applies only while the first is on
<Card>
  <Card.Header title="Gift rules" />
  <DefaultableRow label="Creators can pick gifts" help="Show the gift list in the creator app">
    <DefaultableSetting kind="switch" value={pick} defaultValue={true} onChange={setPick} />
  </DefaultableRow>
  <DefaultableRow label="One gift per challenge" help="A creator takes one gift in each challenge" off={pick === false}>
    <DefaultableSetting kind="switch" value={one} defaultValue={true} disabled={pick === false} onChange={setOne} />
  </DefaultableRow>
</Card>

Where it appears

  • Not drawn in the v3 mocks (their settings are read-only KeyValue tiles). Built for editable Brand › Settings rules.
  • Library gallery: gallery/MissingBrandGallery.tsx ("Settings · Follow the default or set your own").

Guidelines

Do

  • Write the label as the setting's name ("Gift cooldown") and the help as what it does.
  • Stack rows directly in a Card; the borders between them come from the row.

Don't

  • Don't put two controls in one row.
  • Don't use it for read-only facts; use KeyValue.
  • Don't pass label to the inner DefaultableSetting as well: the row already names it.

RTL and Arabic

  • The control sits on the left in Arabic; text aligns to the start.
  • Arabic labels wrap; keep the help to one sentence.

Tokens

--line (row divider). Text uses the inherited ink and .kit-muted.

Accessibility

  • The label <b> has an id that the inner DefaultableSetting uses as aria-labelledby; the help id joins its aria-describedby.
  • A non-Defaultable child does not read the context: give it its own label (e.g. Switch rowLabelled or aria-labelledby).
  • off is visual only; disable the control too.

Found in the source

  • Roles in the markup: radiogroup, radio.
  • ARIA attributes set: aria-describedby, aria-hidden, aria-invalid, aria-readonly, aria-disabled, aria-checked.
  • It moves focus in code.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

See also: Switch · useLanguage

Source

src/blocks/settings-controls/DefaultableSetting.tsx (line 249) on GitHub.

On this page