Skip to Content
BBRICKSv0.7.4
PR PortalSettings and permissions

PermissionMatrix

Roles × permissions (PR team roles: who may approve, pay, change fees, message creators). A real table: permissions are row headers in groups, roles are column headers with "N of M" granted. Each cell is a native checkbox named "{permission}: {role}". One tab stop for the grid; arrow keys move between cells (mirrored in RTL), Home / End go to the row's ends, Space toggles. Locked cells stay focusable (aria-disabled, so they are still read) but do not change; the lock's reason is their description (read with the cell, not only a hover title). On touch tiers each checkbox's label is a 44px target.

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

Examples

Roles and permissions

A grid of checkboxes: rows are permissions (grouped), columns are roles. locked freezes a cell (the Admin column here); toggling calls onToggle with the next value.

Code
import { useState } from 'react';
import { PermissionMatrix, type MatrixGroup } from '@ergasti/bricks';

const roles = [{ id: 'admin', label: 'Admin' }, { id: 'lead', label: 'PR lead' }, { id: 'pr', label: 'PR' }, { id: 'finance', label: 'Finance' }];

const groups: MatrixGroup[] = [
  { label: 'Creators', permissions: [{ id: 'approve', label: 'Approve and reject creators' }, { id: 'tiers', label: 'Move a creator down a tier' }, { id: 'message', label: 'Message creators' }] },
  { label: 'Brands and money', permissions: [{ id: 'commission', label: 'Change commission' }, { id: 'fees', label: 'Change the TRNDR fee' }, { id: 'wallet', label: 'Adjust a wallet' }, { id: 'pay', label: 'Pay creators', description: 'Upload receipts' }] },
];

function Matrix() {
  const [grants, setGrants] = useState(new Set(['lead:approve', 'lead:tiers', 'lead:message', 'lead:commission', 'pr:approve', 'pr:message', 'finance:pay', 'finance:wallet']));
  return (
    <PermissionMatrix
      caption="Roles and permissions" roles={roles} groups={groups}
      granted={(role, permission) => role === 'admin' || grants.has(`${role}:${permission}`)}
      locked={(role) => role === 'admin'}
      onToggle={(role, permission, next) => setGrants((all) => { const copy = new Set(all); if (next) copy.add(`${role}:${permission}`); else copy.delete(`${role}:${permission}`); return copy; })}
    />
  );
}

Props

Prop

Type

Labels

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

prPermissionMatrix
KeyEnglishArabic
cell{p}: {r}{p}: {r}
lockedAlways on for this roleشغّالة دايماً للدور ده
of{a} of {b}{a} من {b}
permissionPermissionالصلاحية

Design guidance

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

A roles × permissions grid of checkboxes with grouped permissions, "N of M" per role and locked cells; use it on the PR Portal's roles and permissions settings.

PermissionMatrix shows who on the PR team may approve, pay, change fees or message creators. It is a real table: permissions are row headers in groups, roles are column headers with how many permissions each has. Each cell is a native checkbox named "{permission}: {role}". The whole grid is one tab stop; arrow keys move between cells (mirrored in RTL), Home / End go to the row's ends, Space toggles. Locked cells (the admin role has everything) stay focusable and are read, with the reason, but do not change. Without onToggle it is read-only. Inferred screen (the mock greys Settings as "LATER").

Anatomy

  1. Wrapper: bordered, radius 18px, white, scrolls sideways when narrow.
  2. Table: hidden caption; 13.5px.
  3. Head row: "PERMISSION" (11px upper-case on --tbl-head), then one column per role: the role name and "3 of 7".
  4. Group rows: a rowgroup header on --soft ("Creators", "Brands and money").
  5. Permission rows: row header with the bold label and optional muted description; one centred checkbox per role (18px, raspberry accent, 28px hit area; 44px on touch).

Variants

PropsEffect
onToggle givenEditable
no onToggleRead-only (every cell aria-disabled)
locked(role, perm) trueThat cell fixed at its state, 55% opacity, lock reason

States

StateTrigger
Granted / notgranted(role, perm)
Lockedlocked(...): "Always on for this role" (described-by and tooltip)
Focusfocus ring on the checkbox; roving tab stop
Narrow (≤600px)tighter cells, 10px head

Types

MatrixRole (roles): { id, label, description? }. MatrixGroup (groups): { label, permissions: [{ id, label, description? }] }.

Usage

import { useState } from 'react';
import { PermissionMatrix, type MatrixGroup } from '@ergasti/bricks';

const roles = [{ id: 'admin', label: 'Admin' }, { id: 'lead', label: 'PR lead' }, { id: 'pr', label: 'PR' }, { id: 'finance', label: 'Finance' }];
const groups: MatrixGroup[] = [
  { label: 'Creators', permissions: [{ id: 'approve', label: 'Approve and reject creators' }, { id: 'tiers', label: 'Move a creator down a tier' }, { id: 'message', label: 'Message creators' }] },
  { label: 'Brands and money', permissions: [{ id: 'commission', label: 'Change commission' }, { id: 'fees', label: 'Change the TRNDR fee' }, { id: 'wallet', label: 'Adjust a wallet' }, { id: 'pay', label: 'Pay creators', description: 'Upload receipts' }] },
];

export function Matrix() {
  const [grants, setGrants] = useState(new Set(['lead:approve', 'lead:tiers', 'lead:message', 'lead:commission', 'pr:approve', 'pr:message', 'finance:pay', 'finance:wallet']));
  return (
    <PermissionMatrix
      caption="Roles and permissions" roles={roles} groups={groups}
      granted={(role, permission) => role === 'admin' || grants.has(`${role}:${permission}`)}
      locked={(role) => role === 'admin'}
      onToggle={(role, permission, next) => setGrants((all) => { const copy = new Set(all); if (next) copy.add(`${role}:${permission}`); else copy.delete(`${role}:${permission}`); return copy; })}
    />
  );
}
// Read-only for someone who may not edit roles, with a save bar for editors
<PermissionMatrix caption="Roles and permissions" roles={roles} groups={groups} granted={has} locked={(r) => r === 'admin'} onToggle={canEdit ? toggle : undefined} />
<SaveBar dirty={dirty} onSave={save} onDiscard={discard} />

Where it appears

  • Library-only (no v3 mock screen): Settings › Roles and permissions (the mock greys Settings as "LATER").

Guidelines

Do

  • Lock what cannot change and let the matrix say why.
  • Group permissions by area; keep labels as actions ("Pay creators").

Don't

  • Don't save on every toggle without a way back; batch with a save bar.
  • Don't use more than about six roles: the grid stops fitting.

RTL and Arabic

Columns mirror and arrows follow the reading direction; head text is not upper-cased in Arabic; "N of M" stays dir="ltr".

Tokens

--line, --card, --tbl-head, --ink, --ink-2, --ink-3, --soft, --rasp, --focus-ring, --min-touch-target.

Accessibility

Real table semantics (caption, scope headers, rowgroup); native checkboxes named "{permission}: {role}"; one tab stop with arrow navigation (mirrored in RTL); locked cells keep focus and announce the reason; 44px hit areas on touch.

Found in the source

  • ARIA attributes set: aria-label, aria-describedby, aria-disabled.
  • It moves focus in code.
  • Its tests cover: “a captioned table: groups, permission row headers, roles with ”; “one tab stop; arrows move between cells; Space toggles; locked cells do not change”; “RTL: Left moves to the next role; Arabic”.

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

See also: useLanguage · NumberSetting

Source

src/pr/PermissionMatrix.tsx (line 40) on GitHub.

On this page