KeyValue
The mock's .kv (soft tiles, radius 14): a description list, 1–3 columns. Labels and values are isolated (B15).
import { KeyValue } from '@ergasti/bricks';Examples
Facts
Label and value pairs in a grid; locked shows a lock (a value only the platform can change); figure turns the label into a money "?" term.
Code
import { KeyValue, Money, MoneyNotesProvider, useLanguage } from '@ergasti/bricks';
import { moneyNotes } from './sample-data';
function Facts() {
const language = useLanguage();
return (
<MoneyNotesProvider notes={moneyNotes(language)}>
<div style={{ maxWidth: 520 }}>
<KeyValue
items={[
{ label: 'Low warning', value: 'At 20% of your last top-up', locked: true },
{ label: 'Coupons pause', value: 'After 7 days below zero', locked: true },
{ label: 'Creators', value: 42 },
{ label: 'Sales', figure: 'sales', value: <Money value="184300.00" compact /> },
]}
/>
</div>
</MoneyNotesProvider>
);
}Three columns
Code
import { KeyValue } from '@ergasti/bricks';
function Columns() {
return <KeyValue columns={3} items={[{ label: 'Orders', value: 214 }, { label: 'Returns', value: 6 }, { label: 'Net', value: 208 }]} />;
}Nothing to show
KeyValue has no empty state: with no facts, leave it out and say so in a muted line. A value that is unknown is better as "Not set" than an empty cell.
Code
import { KeyValue } from '@ergasti/bricks';
function Empty() {
const items: { label: string; value: string }[] = [];
return (
<div style={{ display: 'grid', gap: 12, maxWidth: 520 }}>
{items.length ? <KeyValue items={items} /> : <p className="kit-muted">No settings recorded yet.</p>}
<KeyValue columns={1} items={[{ label: 'Payout day', value: 'Not set' }]} />
</div>
);
}A control in place of a value
control draws an editable value (a Switch, a field) where the bold value would be; a <Switch rowLabelled> (or a native control that does not name itself) is named by the row's label. locked still adds its line.
Code
import { useState } from 'react';
import { KeyValue, Switch } from '@ergasti/bricks';
function Controls() {
const [on, setOn] = useState(true);
return (
<div style={{ maxWidth: 460 }}>
<KeyValue items={[
{ label: 'Creators can pick gifts', control: <Switch rowLabelled checked={on} onChange={setOn} /> },
{ label: 'Return window', value: '14 days after delivery', locked: true },
]} />
</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 keyValue, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
locked | 🔒 Managed by the platform | 🔒 بيديرها فريق المنصة |
Design guidance
How the BRICKS design system uses KeyValue. Written in docs/content/components/KeyValue.md; the props above are read from the code, which wins where the two disagree.
A grid of soft label / value tiles (a description list, 1–3 columns); use it for read-outs in drawers, receipts and settings: order value, commission, status, rules.
It is the mock's .kv: each pair is a --soft tile (radius 14, padding 14) with a 12px muted label and a 15px bold value. A row can hold an editable control instead of a value, say it is locked (owned by the platform: "🔒 Managed by TRNDR" in the TRNDR preset) or carry a money figure so its label becomes the figure's "?" term. It fills the brand drawers (order, gift, gift order, product), SettingsSection, ReceiptCard, PayoutBatchDetail and the challenge and group drawers.
Anatomy
- List:
dl.kit-kv2, grid of--kv-colsequal columns, 10px gap. - Tile:
div, padding 14, radius 14,--soft(white with a line inside aDetailsDrawersection). - Label:
dt, 12px--ink-3; aMoneyNoteterm whenfigureis set; otherwise isolated text. - Value:
dd > b, 15px bold, 2px under the label, wraps anywhere; or - Control:
.kit-kv2-ctl(6px under the label) holding aSwitch rowLabelledor a native control named by thedt. - Lock note (optional):
.kit-kv2-lock, 12px muted, the provider'skeyValue.lockedcopy.
Variants
| Prop value | Look | When to use |
|---|---|---|
columns={1} | One tile per row | Narrow drawers; long values; settings with controls. |
columns={2} (default) | Two-up | Most drawers and settings cards. |
columns={3} | Three-up | Receipt and payout figures that are short. |
Item figure | Dotted "?" term on the label | Any money value. |
Item locked | Lock line under the value | A rule the platform owns. |
Item control | A control in place of the value | Editable settings (gift rules). |
States
| State | Trigger |
|---|---|
| Read-only | value. |
| Editable | control; the control is named by the row's label. |
| Locked | locked: true. |
| Long value | wraps (overflow-wrap: anywhere), the tile grows. |
Types
| Field | Type | Required | Description |
|---|---|---|---|
key | string | no | React key (defaults to the index). |
label | ReactNode | yes | The label. |
value | ReactNode | no | The bold value; optional with control. |
control | ReactNode | no | An editable value. A <Switch rowLabelled> or a native control without its own name is labelled by the dt. |
locked | boolean | no | Adds the "Managed by …" line. |
figure | MoneyFigureKey | no | Makes the label the figure's MoneyNote term. |
Usage
// Brand › Payments › Commissions › order drawer
<DrawerHead tone="lime" title="Order #48213" sub="Delivered · 12 Nov" />
<KeyValue items={[
{ label: 'Order value', value: <Money value="1240.00" />, figure: 'order_line' },
{ label: 'Commission', value: <Money value="124.00" />, figure: 'order_commission' },
{ label: 'Rule', value: 'Standard 10%' },
{ label: 'Status', value: <StatusPill status="delivered" /> },
]} />
<RowItems label="Creator" items={creatorRow} />// Settings: rules the platform owns
<KeyValue items={[
{ label: 'Low warning', value: 'At 20% of your last top-up', locked: true },
{ label: 'Coupons pause', value: 'After 7 days below zero', locked: true },
]} />// An editable row
<KeyValue columns={1} items={[
{ label: 'Best gift only', control: <Switch rowLabelled checked={best} onChange={setBest} /> },
]} />Where it appears
- Brand › Payments › order drawer; payout drawer (
PayoutBatchDetail); transfer proof (ReceiptCard) (BrandWallet). - Brand › Motivation › gift drawer, gift order drawer; challenge cards and drawer (BrandMotivation).
- Brand › Analytics › product drawer (BrandAnalytics); Home › live challenge figures.
- Brand › Settings › every section's rows (
SettingsSection) (BrandSettings). - Brand › Creators › creator and group drawers (
MyCreatorPanel,GroupPanel);DetailsDrawersections.
Guidelines
Do
- Keep labels short nouns; put the unit in the value ("90 days").
- Give money values a
figureso the "?" explains them. - Use
columns={1}when any value is a sentence.
Don't
- Don't use it for long tabular data; use
DataTableorRowItems. - Don't mix controls and read-only values without
lockedmaking ownership clear.
RTL and Arabic
- Grid order mirrors; text aligns to the inline start.
- Lock copy in Arabic: "🔒 بيديرها فريق المنصة". Money values keep LTR digits through
Money.
Tokens
--soft, --ink-3, --card and --line (inside drawer sections), --kv-cols.
Accessibility
- A real
<dl>withdt/ddpairs. - Controls are named by the row label (
aria-labelledbythedt, orSwitch rowLabelled). - Labels and values are isolated so mixed Arabic / Latin reads correctly.
Found in the source
- No roles, ARIA attributes or key handling are set in this component's own source; it renders native elements and the components it composes.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
SettingsSection: titled settings card built on KeyValue rows.DefaultableRow: a row with a "use default" control.RowItems,DataTable: lists of entities.Tile: one bigger figure.
See also: MoneyNote · useLanguage · MoneyNotesProvider · Money · Switch · Accordion · Card · HeroCard · KpiCard
Source
src/kit/patterns/KeyValue.tsx (line 35) on GitHub.