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.
| Key | English | Arabic |
|---|---|---|
following | Following the platform default | ماشي على الافتراضي بتاع المنصة |
followingUnknown | Following the platform default | ماشي على الافتراضي بتاع المنصة |
own | Your own setting | إعدادك إنت |
useDefault | Use platform default | ارجع لافتراضي المنصة |
defaultIs | Default: {value} | الافتراضي: {value} |
locked | 🔒 Set by the platform | 🔒 المنصة هي اللي بتحدده |
on | On | شغّال |
off | Off | مقفول |
unknown | Platform default | افتراضي المنصة |
reset | Reset to {value} | رجّعه {value} |
errEmpty | Enter a value, or use the platform default. | اكتب قيمة، أو ارجع لافتراضي المنصة. |
errNumber | Enter a number. | اكتب رقم. |
errWhole | Use a whole number. | اكتب رقم صحيح. |
errRange | Must be from {min} to {max}. | لازم يكون من {min} لـ {max}. |
errMin | Must be {min} or more. | لازم يكون {min} أو أكتر. |
errMax | Must 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
- Control (by
kind):switch: an iOS-style kitSwitchand the words "On" / "Off" beside it (.kit-blk-def-sw).number: a 96px LTR number input (tabular numbers; ink-3 text while following), theunitafter 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 forceon.
- 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". - "Use platform default" link (
.kit-blk-def-use): only while the value is the brand's own and the control is editable. - Error (
.kit-field-err): the number's validation message.
Variants
kind | Value type | Default type | Extra props | Use when |
|---|---|---|---|---|
'switch' | boolean | null | boolean | null | — | On/off rules ("Creators can pick gifts"). |
'number' | string | null (as typed) | number | null | min, max, step (1), unit, resetTo, error | Counts and periods ("Gift cooldown: 45 days"). |
'choice' | string | null | string | null | options: { value, label }[] | One of a few values ("Payout window: Weekly / Monthly / Quarterly"). |
States
| State | How | Look |
|---|---|---|
| Following the default | value={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 value | value set | "Your own setting · Default: 60 days" and the "Use platform default" link. |
| Read-only | readOnly | Value in force, lock note "Set by the platform", no link; input readonly on --soft, chips not clickable (aria-readonly). |
| Disabled | disabled | Native disabled control; no link. Pair with DefaultableRow off. |
| Invalid number | own value outside the rule | aria-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 error | error (number) | Replaces the built-in message. |
| Reset link | resetTo (number) | "Reset to 90" shows while the field is empty or differs from 90. |
| Focus | keyboard | Input: 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"). GiftRulesCardtakes its own per-rule "following the default" state instead.
Guidelines
Do
- Send
nullto the server for "follow the default"; never copy the default into the brand's value. - Pass
defaultValueso the control and the "Default: …" note show the real platform value. - Use
readOnlyfor values the TRNDR team owns, so the brand still sees them.
Don't
- Don't add your own "Reset" button next to it; use
resetTofor a house value and the built-in link for the platform default. - Don't use
choicefor more than about five options; use a select. - Don't hide a setting that does not apply: dim it with
DefaultableRow offanddisabled.
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
labelor the surrounding row (aria-labelledbythe row's label); the row's help and the status line are inaria-describedby, so "Following the platform default" is read with the control. - Number:
type="number",inputModenumeric/decimal,aria-invalid, the error joined toaria-describedby. - Choice:
role="radiogroup"ofrole="radio"buttons witharia-checked, roving tabindex, arrow keys select;aria-readonly/aria-disabledwhen 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.
Related
DefaultableRow: the label + help line it sits in.Switch,SettingsSection: plain settings without a platform default.GiftRulesCard: the gift rules card with its own default handling.
See also: useLanguage
Source
src/blocks/settings-controls/DefaultableSetting.tsx (line 146) on GitHub.