Skip to Content
BBRICKSv0.7.4
BlocksSettings

DefaultableSetting

The generic "follow the default / own value" control (the console's #1139 tri-state): the control always shows the value in force (the own value, else the platform's); the note under it says "Following the platform default" or "Your own setting" with "Use platform default". Changing the control makes the value the brand's own; "Use platform default" sends null. Three kinds: switch, number with unit (min / max / step, the message read with the field, an optional "Reset to N"), and choice (a chip radiogroup).

import { DefaultableSetting } 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

Labels

Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key defaultableSetting, or with the component's own prop where it has one. A {name} is a value the component fills in.

defaultableSetting
KeyEnglishArabic
followingFollowing the platform defaultماشي على الافتراضي بتاع المنصة
followingUnknownFollowing the platform defaultماشي على الافتراضي بتاع المنصة
ownYour own settingإعدادك إنت
useDefaultUse platform defaultارجع لافتراضي المنصة
defaultIsDefault: {value}الافتراضي: {value}
locked🔒 Set by the platform🔒 المنصة هي اللي بتحدده
onOnشغّال
offOffمقفول
unknownPlatform defaultافتراضي المنصة
resetReset to {value}رجّعه {value}
errEmptyEnter a value, or use the platform default.اكتب قيمة، أو ارجع لافتراضي المنصة.
errNumberEnter a number.اكتب رقم.
errWholeUse a whole number.اكتب رقم صحيح.
errRangeMust be from {min} to {max}.لازم يكون من {min} لـ {max}.
errMinMust be {min} or more.لازم يكون {min} أو أكتر.
errMaxMust be {max} or less.لازم يكون {max} أو أقل.

Design guidance

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

A settings control that either follows the platform default or holds the brand's own value (switch, number or choice), always showing the value in force and a "Use platform default" link; use it for any setting the platform defaults but a brand may override.

The v3 mock shows every settings value read-only; the nearest pattern is the gift cooldown's "Default 90 days" / "Reset to 90". The library builds the console's tri-state (#1139) here: value === null means "follow the default", any other value is the brand's own. Changing the control makes the value the brand's own; "Use platform default" sends null. Put it inside a DefaultableRow, which gives it its label and help.

Anatomy

  1. Control (by kind):
    • switch: an iOS-style kit Switch and the words "On" / "Off" beside it (.kit-blk-def-sw).
    • number: a 96px LTR number input (tabular numbers; ink-3 text while following), the unit after it, and an optional "Reset to 90" link (.kit-blk-def-num).
    • choice: a radiogroup of filter chips (.kit-blk-def-ch, kit-chipf), the one in force on.
  2. Status line (.kit-blk-def-st, 12px): "Following the platform default" (muted), or "Your own setting" (raspberry, bold) · "Default: 60 days", or, read-only, a lock glyph and "Set by the platform".
  3. "Use platform default" link (.kit-blk-def-use): only while the value is the brand's own and the control is editable.
  4. Error (.kit-field-err): the number's validation message.

Variants

kindValue typeDefault typeExtra propsUse when
'switch'boolean | nullboolean | null—On/off rules ("Creators can pick gifts").
'number'string | null (as typed)number | nullmin, max, step (1), unit, resetTo, errorCounts and periods ("Gift cooldown: 45 days").
'choice'string | nullstring | nulloptions: { value, label }[]One of a few values ("Payout window: Weekly / Monthly / Quarterly").

States

StateHowLook
Following the defaultvalue={null}Control shows defaultValue; muted "Following the platform default". If defaultValue is null (older server), the switch reads "Platform default" and the number is empty.
Own valuevalue set"Your own setting · Default: 60 days" and the "Use platform default" link.
Read-onlyreadOnlyValue in force, lock note "Set by the platform", no link; input readonly on --soft, chips not clickable (aria-readonly).
DisableddisabledNative disabled control; no link. Pair with DefaultableRow off.
Invalid numberown value outside the rulearia-invalid, red border, message: "Enter a value, or use the platform default." / "Enter a number." / "Use a whole number." / "Must be from 1 to 365." / "Must be 1 or more." / "Must be 365 or less."
Server errorerror (number)Replaces the built-in message.
Reset linkresetTo (number)"Reset to 90" shows while the field is empty or differs from 90.
FocuskeyboardInput: raspberry border + field focus ring; chips: focus ring; arrows move and select chips (roving tabindex).

Types

kind: 'number' only: min?, max?, step? (default 1; whole steps require whole numbers), unit? ("days", "%"), resetTo? (a house value with its own "Reset to N" link), error?: string | null (replaces the built-in message).

kind: 'choice' only: options (required), ReadonlyArray<{ value: string; label: string }>.

Helper: defaultableNumberError(value, { min, max, step }, language, labels?) returns the message or null; use it to block Save.

DefaultableCopy (labels): following, followingUnknown, own, useDefault, defaultIs(v), locked, on, off, unknown, reset(v), and the six err* messages.

Usage

const [cooldown, setCooldown] = useState<string | null>('45');

<DefaultableRow label="Gift cooldown" help="Days a creator waits after a gift before picking another one">
  <DefaultableSetting kind="number" value={cooldown} defaultValue={60} min={1} max={365} unit="days" resetTo={90} onChange={setCooldown} />
</DefaultableRow>
// The gift rules card: four editable rows and one the platform owns
<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">
    <DefaultableSetting kind="switch" value={one} defaultValue={true} onChange={setOne} />
  </DefaultableRow>
  <DefaultableRow label="Payout window" help="How often your creators are paid">
    <DefaultableSetting kind="choice" value={payWindow} defaultValue="monthly" onChange={setPayWindow}
      options={[{ value: 'weekly', label: 'Weekly' }, { value: 'monthly', label: 'Monthly' }, { value: 'quarterly', label: 'Quarterly' }]} />
  </DefaultableRow>
  <DefaultableRow label="TRNDR fee" help="Set by the TRNDR team">
    <DefaultableSetting kind="number" value={null} defaultValue={5} unit="%" readOnly onChange={() => {}} />
  </DefaultableRow>
</Card>
import { useState } from 'react';
import { Button, DefaultableSetting, defaultableNumberError, useLanguage } from '@ergasti/bricks';

// Block Save while a number is invalid; show the server's refusal
export function CooldownSetting({ save, serverError }: { save: (value: string | null) => void; serverError: string | null }) {
  const language = useLanguage();
  const [cooldown, setCooldown] = useState<string | null>('45');
  const err = cooldown === null ? null : defaultableNumberError(cooldown, { min: 1, max: 365 }, language);
  return (
    <>
      <DefaultableSetting kind="number" label="Gift cooldown" value={cooldown} defaultValue={60} min={1} max={365} unit="days"
        error={serverError} onChange={setCooldown} />
      <Button variant="rasp" disabled={Boolean(err)} onClick={() => save(cooldown)}>Save</Button>
    </>
  );
}

Where it appears

  • Not drawn in the v3 mocks (all settings are read-only there). Built for Brand › Settings › Gift rules and Payout rules once they become editable; nearest mock element: the gift cooldown's "Default 90 days" / "Reset to 90".
  • Shown in the library gallery (gallery/MissingBrandGallery.tsx, "Settings · Follow the default or set your own").
  • GiftRulesCard takes its own per-rule "following the default" state instead.

Guidelines

Do

  • Send null to the server for "follow the default"; never copy the default into the brand's value.
  • Pass defaultValue so the control and the "Default: …" note show the real platform value.
  • Use readOnly for values the TRNDR team owns, so the brand still sees them.

Don't

  • Don't add your own "Reset" button next to it; use resetTo for a house value and the built-in link for the platform default.
  • Don't use choice for more than about five options; use a select.
  • Don't hide a setting that does not apply: dim it with DefaultableRow off and disabled.

RTL and Arabic

  • In a row the control aligns to the end (left in Arabic); on phones it moves under the label.
  • The number input stays dir="ltr"; Arabic-Indic digits typed are converted (toAsciiDigits) before validation; messages format numbers per language.
  • Arabic copy: "ماشي على الافتراضي بتاع المنصة", "إعدادك إنت", "ارجع لافتراضي المنصة", "شغّال" / "مقفول".

Tokens

--line, --card, --ink, --ink-3 (following value), --soft (read-only input), --rasp (focus border), --rasp-d ("Your own setting"), --bad (invalid), --field-h, --field-radius, --focus-ring, --focus-ring-field, --min-touch-target.

Accessibility

  • Name comes from label or the surrounding row (aria-labelledby the row's label); the row's help and the status line are in aria-describedby, so "Following the platform default" is read with the control.
  • Number: type="number", inputMode numeric/decimal, aria-invalid, the error joined to aria-describedby.
  • Choice: role="radiogroup" of role="radio" buttons with aria-checked, roving tabindex, arrow keys select; aria-readonly / aria-disabled when locked.
  • Switch: "On"/"Off" words are aria-hidden (the switch states itself); "Use platform default" is described by the row label.

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: useLanguage

Source

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

On this page