PermissionMatrix
ComplexAccess
<co-permission-matrix>PermissionMatrix is the role-by-action grid from Compare roles and Roles and Permissions, showing None, View, Edit or Approve for each role.
import { PermissionMatrix } from 'health-components';
Examples
Showcase
Editable
No Differences
Usage
<PermissionMatrix
roles={["Provider", "Nurse / MA", "Biller"]}
rows={rows} onRowsChange={setRows}
editable onChange={(row, role, level) => savePermission(row, role, level)} />
<PermissionMatrix roles={["Provider", "Biller"]} defaultRows={rows} defaultOnlyDifferences />
When to use
- Comparing 1 to 3 roles side by side; editing a role's permissions.
When not to use
- Showing one user what they can do: PermissionState.
Variants and states
| Variant | What it is |
|---|---|
| read | Level tags with icon and word. |
| editable | A select per cell; onChange reports row, role and level. |
| only differences | Hides rows where all roles match; empty text "These roles have the same level on every action." |
Accessibility
- Real table with caption, column headers per role and a row header per action.
- Each level has its own icon and word, so the grid reads without colour.
Do and don't
- Do: Group rows by module (Schedule, Billing, Clinical, Settings).
- Don't: Invent a fifth level per screen.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
roles * | string[] | — | Role names, one column each (1 to 3 recommended); required |
rows | PermissionRow[] | uncontrolled | Rows (controlled): Array<{module, action, levels: Record<role, none|view|edit|approve>}> |
defaultRows | PermissionRow[] | [] | Initial rows (uncontrolled) |
onRowsChange | (rows: PermissionRow[]) => void | none | Called with all rows after a level is edited |
editable | boolean | false | A select per cell instead of level tags |
onlyDifferences | boolean | uncontrolled | Hides rows where every role has the same level (controlled) |
defaultOnlyDifferences | boolean | false | Initial "Only show differences" state (uncontrolled) |
onOnlyDifferencesChange | (on: boolean) => void | none | Called when "Only show differences" is switched |
onChange | (row: PermissionRow, role: string, level: PermissionLevel) => void | none | Called with the edited row (as it was before the edit), the role and the new level |
caption | string | "Permissions by role" | Table caption for screen readers |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, onInput, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-permission-matrix>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-permission-matrix editable only-differences [roles]="roles" (co-rows-change)="onRowsChange($event.detail)"></co-permission-matrix>
| Kind | Name | Description |
|---|---|---|
| property / JSON attribute | roles | Role names, one column each (1 to 3 recommended); required |
| property / JSON attribute | rows | Rows (controlled): Array<{module, action, levels: Record<role, none|view|edit|approve>}>; default uncontrolled |
| property / JSON attribute | default-rows / defaultRows | Initial rows (uncontrolled); default [] |
| attribute | editable | A select per cell instead of level tags; default false |
| attribute | only-differences / onlyDifferences | Hides rows where every role has the same level (controlled); default uncontrolled |
| attribute | default-only-differences / defaultOnlyDifferences | Initial "Only show differences" state (uncontrolled); default false |
| attribute | caption | Table caption for screen readers; default "Permissions by role" |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| event | co-rows-change | Called with all rows after a level is edited; default none (React: onRowsChange) |
| event | co-only-differences-change | Called when "Only show differences" is switched; default none (React: onOnlyDifferencesChange) |
| event | co-change | Called with the edited row (as it was before the edit), the role and the new level; default none (React: onChange) |
| event | co-input | (React: onInput) |