All components (244)

Permission matrix

Management · PermissionMatrix · .amset-matrix

What it is and when to use it

The permission matrix of a role: modules in rows, what can be done in columns and a checkbox at each crossing. For the role editor of a management application.

When to use it

Building or reviewing what a role or a user can do on each module.
modules are the rows and actions, the columns. value is a map from module to the list of granted action keys ({ invoices: ['read', 'create'] }); without value, the matrix keeps its own state from initialValue.
There is one checkbox per row, another per column and another in the corner to tick or clear everything at once, with an intermediate state when only part is ticked.
locked fixes cells that cannot be changed (a permission inherited from another role, one the system imposes), in the same format as value. Ticking a whole row respects them.
readOnly to see what is granted without touching it; disabled to switch it off entirely.

When not to

A single loose permission: a checkbox or a switch.
Hiding a button depending on what is granted: PermissionGate.
Ticking it here grants nothing by itself: what counts is decided by the server when saving and when executing.

Keyboard: it is a single stop of the tab order and is moved through with the arrows like a spreadsheet. Home and End go to the start and end of the row, Ctrl+Home and Ctrl+End to the first and last checkbox. Space ticks and unticks.

Accessibility: it is a named grid (label, required). Each checkbox is named by its crossing ("Invoices: Delete"); the row and column ones say what they tick. Each change is announced, also that of a whole row or column, because it changes checkboxes that whoever is listening does not see. Locked cells carry aria-disabled and stay focusable, so they can be read.

Fine appearance: variables --amset-matrix-cell (the pressable area, 44 px with a finger), --amset-matrix-box (the checkbox) and --amset-matrix-row-width (the width of the modules column).

What it looks like

<PermissionMatrix
  label="Permissions for the “Manager” role"
  modules={modulos}
  actions={acciones}
  value={permisos}
  onChange={setPermisos}
  locked={{ pedidos: ["view"] }}
  showCounts
/>

Props

Import it with import { PermissionMatrix } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`actions`required	`readonly PermissionAction[]`	The columns: what can be done (view, create, edit, delete...).
`label`required	`string`	What the matrix is called: it names the grid for whoever uses a screen reader. Required.
`modules`required	`readonly PermissionModule[]`	The rows: the modules or resources permissions are granted on.
`className`	`string`	Merged with the library classes; it does not replace them.
`disabled`	`boolean`	—
`initialValue`	`Readonly<Record<string, readonly string[]>>`	—
`locked`	`Readonly<Record<string, readonly string[]>>`	Cells that cannot be changed (an inherited role, a permission the system imposes): same format as `value`.
`onChange`	`(value: PermissionGrants) => void`	—
`readOnly`	`boolean`	Read only: the checkboxes can be seen and moved through with the keyboard, but they do not change.
`showCounts`	`boolean`	The "3 of 5" of each row. On by default.
`value`	`Readonly<Record<string, readonly string[]>>`	What is granted: each module with the list of action keys. If passed, the matrix is controlled.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-matrix-cell`	`2.5rem`
`--amset-matrix-box`	`1.125rem`
`--amset-matrix-row-width`	`14rem`

How to change it

.amset-matrix {
  --amset-matrix-cell: ...;
  --amset-matrix-box: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech:

	View	Edit	Delete
OrdersView and manage orders
Invoices
Customers
Settings