Skip to Content
BBRICKSv0.7.4
KitPatterns

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.

keyValue
KeyEnglishArabic
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

  1. List: dl.kit-kv2, grid of --kv-cols equal columns, 10px gap.
  2. Tile: div, padding 14, radius 14, --soft (white with a line inside a DetailsDrawer section).
  3. Label: dt, 12px --ink-3; a MoneyNote term when figure is set; otherwise isolated text.
  4. Value: dd > b, 15px bold, 2px under the label, wraps anywhere; or
  5. Control: .kit-kv2-ctl (6px under the label) holding a Switch rowLabelled or a native control named by the dt.
  6. Lock note (optional): .kit-kv2-lock, 12px muted, the provider's keyValue.locked copy.

Variants

Prop valueLookWhen to use
columns={1}One tile per rowNarrow drawers; long values; settings with controls.
columns={2} (default)Two-upMost drawers and settings cards.
columns={3}Three-upReceipt and payout figures that are short.
Item figureDotted "?" term on the labelAny money value.
Item lockedLock line under the valueA rule the platform owns.
Item controlA control in place of the valueEditable settings (gift rules).

States

StateTrigger
Read-onlyvalue.
Editablecontrol; the control is named by the row's label.
Lockedlocked: true.
Long valuewraps (overflow-wrap: anywhere), the tile grows.

Types

KeyValueItem:

FieldTypeRequiredDescription
keystringnoReact key (defaults to the index).
labelReactNodeyesThe label.
valueReactNodenoThe bold value; optional with control.
controlReactNodenoAn editable value. A <Switch rowLabelled> or a native control without its own name is labelled by the dt.
lockedbooleannoAdds the "Managed by …" line.
figureMoneyFigureKeynoMakes 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); DetailsDrawer sections.

Guidelines

Do

  • Keep labels short nouns; put the unit in the value ("90 days").
  • Give money values a figure so the "?" explains them.
  • Use columns={1} when any value is a sentence.

Don't

  • Don't use it for long tabular data; use DataTable or RowItems.
  • Don't mix controls and read-only values without locked making 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> with dt / dd pairs.
  • Controls are named by the row label (aria-labelledby the dt, or Switch 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.

See also: MoneyNote · useLanguage · MoneyNotesProvider · Money · Switch · Accordion · Card · HeroCard · KpiCard

Source

src/kit/patterns/KeyValue.tsx (line 35) on GitHub.

On this page