Skip to main content

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​

Storybook

Editable​

Storybook

No Differences​

Storybook

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​

VariantWhat it is
readLevel tags with icon and word.
editableA select per cell; onChange reports row, role and level.
only differencesHides 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​

PropTypeDefaultDescription
roles *string[]—Role names, one column each (1 to 3 recommended); required
rowsPermissionRow[]uncontrolledRows (controlled): Array<{module, action, levels: Record<role, none|view|edit|approve>}>
defaultRowsPermissionRow[][]Initial rows (uncontrolled)
onRowsChange(rows: PermissionRow[]) => voidnoneCalled with all rows after a level is edited
editablebooleanfalseA select per cell instead of level tags
onlyDifferencesbooleanuncontrolledHides rows where every role has the same level (controlled)
defaultOnlyDifferencesbooleanfalseInitial "Only show differences" state (uncontrolled)
onOnlyDifferencesChange(on: boolean) => voidnoneCalled when "Only show differences" is switched
onChange(row: PermissionRow, role: string, level: PermissionLevel) => voidnoneCalled with the edited row (as it was before the edit), the role and the new level
captionstring"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>
KindNameDescription
property / JSON attributerolesRole names, one column each (1 to 3 recommended); required
property / JSON attributerowsRows (controlled): Array<{module, action, levels: Record<role, none|view|edit|approve>}>; default uncontrolled
property / JSON attributedefault-rows / defaultRowsInitial rows (uncontrolled); default []
attributeeditableA select per cell instead of level tags; default false
attributeonly-differences / onlyDifferencesHides rows where every role has the same level (controlled); default uncontrolled
attributedefault-only-differences / defaultOnlyDifferencesInitial "Only show differences" state (uncontrolled); default false
attributecaptionTable caption for screen readers; default "Permissions by role"
attributedefault-checked / defaultChecked
property / JSON attributedefault-value / defaultValue
attributeauto-focus / autoFocus
eventco-rows-changeCalled with all rows after a level is edited; default none (React: onRowsChange)
eventco-only-differences-changeCalled when "Only show differences" is switched; default none (React: onOnlyDifferencesChange)
eventco-changeCalled with the edited row (as it was before the edit), the role and the new level; default none (React: onChange)
eventco-input (React: onInput)