Permissions Matrix React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Permissions Matrix is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import PermissionsMatrix from @/components/ui/permissions-matrix.

import { useState } from "react"
import { FileText, Users } from "lucide-react"
import {
  PermissionsMatrix,
  countPermissionChanges,
  type PermissionGroup,
  type PermissionRole,
  type PermissionsValue,
} from "@/components/ui/permissions-matrix"

const roles: PermissionRole[] = [
  { id: "owner", name: "Owner", locked: true, memberCount: 1 },
  { id: "sales", name: "Sales", memberCount: 3 },
  { id: "accounting", name: "Accounting", memberCount: 1 },
]

const groups: PermissionGroup[] = [
  {
    id: "clients",
    label: "Clients",
    icon: <Users />,
    permissions: [
      { id: "clients.view", label: "View clients" },
      { id: "clients.delete", label: "Delete clients", requires: ["clients.view"], dangerous: true },
    ],
  },
  {
    id: "invoices",
    label: "Invoices",
    icon: <FileText />,
    permissions: [
      { id: "invoices.view", label: "View invoices" },
      { id: "invoices.issue", label: "Issue invoices", requires: ["invoices.view"] },
    ],
  },
]

const saved: PermissionsValue = { sales: ["clients.view"], accounting: ["clients.view", "invoices.view", "invoices.issue"] }

// 1 change, 3 changes
const changesLabel = (n: number) => (n === 1 ? "1 change" : `${n} changes`)

export function RolePermissions() {
  const [value, setValue] = useState<PermissionsValue>(saved)
  const changes = countPermissionChanges(value, saved, { ignoreRoles: ["owner"] })
  return (
    <div className="flex flex-col gap-3">
      <PermissionsMatrix
        roles={roles}
        groups={groups}
        value={value}
        onValueChange={setValue}
        compareTo={saved}
        searchPlaceholder="Search permissions"
        labels={{ changes: changesLabel, permission: "Permission", caption: "Permissions by role" }}
      />
      {changes > 0 && <p className="text-sm text-muted-foreground">{changesLabel(changes)} to save</p>}
    </div>
  )
}

Props

• roles*
  PermissionRole[]

  The columns: { id, name, description?, locked? (every permission, not editable), tone? / color? (a dot and the granted bar), memberCount? }. Zero roles shows an empty state.

• groups*
  PermissionGroup[]

  The rows, by module: { id, label, description?, icon?, permissions: { id, label, description?, requires?: string[], dangerous? }[] }.

• value
  PermissionsValue

  Controlled grants. Boolean mode: Record<roleId, string[]>. Levels mode: Record<roleId, Record<permissionId, level>>. Ids that are not in groups are kept untouched; locked roles are ignored (always everything).

• defaultValuedefault "{}"
  PermissionsValue

  The grants to start with while uncontrolled.

• onValueChange
  (value: PermissionsValue, change: { roleId: string; permissionIds: string[]; granted: boolean | string }) => void

  Every change with the next value. permissionIds lists every cell that changed, dependencies included (the one you pressed first). The grid resolves them with resolvePermissionDependencies (see Parts), which you can reuse to validate a change on the server.

• compareTo
  PermissionsValue

  The saved state. Cells that differ get data-changed, a dot (with a screen reader "changed") and a faint tint, and the toolbar shows the count. countPermissionChanges (see Parts) gives the same count for a save bar, on the server too.

• modedefault "boolean"
  PermissionsMatrixMode = "boolean" | "levels"

  levels: every cell is a compact ghost select of levels (None / View / Edit / Full), the module row sets all at once.

• levelsdefault "[{ value: "none", label: "None" }, { value: "view", label: "View" }, { value: "edit", label: "Edit" }, { value: "full", label: "Full" }]"
  PermissionLevel[]

  { value, label, short? } for levels mode; the cell shows short or the label. The first level means not granted, the second is what a requirement is raised to. An unknown value in the data shows as is.

• defaultSearchdefault ""
  string

  The search to start with, uncontrolled. Pair search / onSearchChange to drive it.

• search
  string

  Controlled search text.

• onSearchChange
  (query: string) => void

  Called as the search text changes.

• searchPlaceholderdefault "Search permissions"
  string

  The search field's placeholder and accessible name.

• labels
  Partial<PermissionsMatrixLabels>

  Every visible and announced string, English by default (see Parts): caption, permission, changes(n), changed, locked, requires(names), dangerous, granted(permission, role), revoked(permission, role), levelSet(permission, role, level), alsoGranted(names), alsoRevoked(names), expandAll, collapseAll, noResults, noResultsDescription, clearSearch, results(n) (the match count in the search field, announced), noRoles, noRolesDescription, members(n), count(granted, total), group(label, role), mixed, yes, no, role.

• densitydefault "default"
  "compact" | "default"

  Rows of 40 or 48px; the compact row grows to 44px on touch.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The checkbox, switch, role chip and changed-dot color.

• colordefault ""
  string

  Any CSS color; replaces the tone. The check turns black or white by lightness.

• showDescriptionsdefault true
  boolean

  Permission descriptions under their labels (two lines at most).

• showCountsdefault true
  boolean

  The granted count ("12/18") and a small bar under every role; on phones the count badge of each role and the count beside each module switch.

• readOnlydefault false
  boolean

  Cells become check and dash icons (levels show their name); module rows show a count. All roles locked means read-only too.

• searchabledefault true
  boolean

  A search field that keeps only the matching rows (modules with no match hide) and marks the matches.

• enforceDependenciesdefault true
  boolean

  Granting adds what a permission requires, revoking a requirement revokes its dependents; the cells that changed on their own flash and the change is announced.

• collapsibleGroupsdefault true
  boolean

  Module rows fold their permissions away; adds Expand all / Collapse all to the toolbar.

• defaultCollapsedGroupsdefault "[]"
  string[]

  Module ids folded at first.

• stickyHeaderdefault true
  boolean

  The role row sticks to the top of the scroller (or of the page at --topbar-offset when maxHeight is 0 and the grid fits sideways).

• maxHeightdefault 0
  number

  Caps the grid's height in px so it scrolls inside; 0 grows with the page.

• mobileLayoutdefault "accordion"
  "accordion" | "role-picker"

  Below 768px: one accordion card per role with switches, or a row of role chips over one list. The grid never scrolls sideways on a phone.

• layoutdefault "auto"
  "auto" | "grid" | "list"

  auto: the grid from 768px, the phone list below. grid or list force one, e.g. list in a narrow side panel.

• onRoleClick
  (role: PermissionRole) => void

  Turns the role headers into buttons (edit the role); they join the grid's arrow navigation.

• classNames
  Partial<Record<"toolbar" | "search" | "changes" | "expandAll" | "panel" | "scroller" | "table" | "head" | "role" | "group" | "groupToggle" | "row" | "permission" | "cell" | "mobile" | "mobileRole" | "empty", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root; the remaining props spread onto it.

Parts

FAQ

Used in

More React table and list components