Roles & permissions

A React block (a whole screen) in Beamline's Blocks category.

What each role may do, as one matrix: permissions grouped by area down the side, roles across the top with their head counts, a check per cell; a group's box sets the whole area. Edits gather in a draft whose changed cells are marked and counted in a save bar, risky grants are flagged, and custom roles can be created from an existing one or deleted with their people moved. In a narrow room it shows one role at a time.

Use it for

Role-based access in a SaaS workspace: owners and admins decide what Admin, Member, Viewer and custom roles can do.
Any yes/no grid of capabilities by tier that a person edits and then saves as one change (feature flags by plan, scopes by app).

Not for

Who has which role (team-members).
Per-channel notification choices that apply at once (notification-preferences).
Scopes of a single API key (api-keys).

Anatomy

header: title, one line, New role (the primary action until there is a draft)
toolbar: find a permission; the role picker in a narrow room
matrix: a pinned permission column (name, one line, risk mark), a header row of roles (name, people count, lock on a role that cannot change, actions on custom roles), group rows whose box sets the area, a check per cell; the row and column under the pointer are lit
narrow room (under 42rem): one role at a time, chosen above the list, each permission a row with its box
save bar: how many changes in which roles, Discard, Save changes (the primary action while there is a draft)
new role dialog: name, start from a role, one line of description
delete role dialog: where its people go

States

loading
load failed (Try again)
clean
draft: changed cells marked, the save bar counts them; setting a cell back removes its mark
saving (permission edits and role actions wait until the save settles); saved (marks settle, toast); save failed (the bar keeps the message, Save becomes Try again, the draft stays)
locked role (owner: every permission, not editable)
risky grant in the draft (named in the save bar)
no permission matches the search (Clear search)
new role creating, created (its column arrives lit); name taken
delete role: moving N people, failed

Keyboard

The matrix is one Tab stop: arrows move between cells (Home/End to the row's ends), Space toggles, a group row's box sets the whole area
⌘S saves the draft, Esc in the save bar discards after asking nothing (Discard is undoable by editing again)
Dialogs trap focus and return it to what opened them

Motion

A cell's check draws itself; a changed cell gains its mark with a short glow and loses it when set back. The save bar rises with the first change and keeps its place while its count rolls. A new role's column arrives lit and settles. Pointer rows and columns light at once and fade on leaving. Reduced motion places everything at once.

Props

Prop	Type	Default	Description
`roles / defaultRoles / onRolesChange` (required)	`PermissionRole[]`	—	The saved roles with the permission ids each holds; onRolesChange gets the saved list after Save, a new role or a deletion.
`permissions` (required)	`PermissionDef[]`	—	Every permission: id, label, group, optional description and risk "high".
`onSave` (required)	`(roles: PermissionRole[], changes: PermissionChange[]) => Promise<void>`	—	Persist the draft; a rejection keeps it with the message.
`onCreateRole`	`(input: { name, description, from }) => Promise<PermissionRole>`	—	Shows New role.
`onDeleteRole`	`(id, moveTo) => Promise<void>`	—	Shows Delete on custom roles; their people move to moveTo.
`loading / error / onRetry`	`boolean / ReactNode / () => void \| Promise<unknown>`	—
`level`	`1 \| 2`	—
`className / classNames / style / ref`	`string / RolesPermissionsClassNames / CSSProperties / Ref<HTMLDivElement>`	—

Built from

checkbox
search-field
select
segmented-control
button
badge
dialog
alert-dialog
input
dropdown-menu
tooltip
toast
skeleton
empty-state

Dependencies

lucide-react, motion

Import

import { RolesPermissions } from "@/blocks/roles-permissions/roles-permissions";

Get it

Roles & permissions is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent