Permission system for access control

Interactive playground

Toggle permissions and roles below to see how Can, Cannot, Role, and the hooks react in real time.

Provider setup

Wrap your application with PermissionProvider to enable permission and role checking throughout the component tree.

import { PermissionProvider } from "@zentauri-ui/zentauri-components/permission";

function App() {
  return (
    <PermissionProvider
      roles={["admin"]}
      permissions={[
        "users.read",
        "users.create",
        "users.delete",
        "billing.view",
      ]}
    >
      <YourApp />
    </PermissionProvider>
  );
}

Declarative components

Use Can, Cannot, and Role to conditionally render UI elements.

import { Can, Cannot, Role } from "@zentauri-ui/zentauri-components/permission";

<Can permission="users.delete">
  <button>Delete User</button>
</Can>

<Can permissions={["users.create", "users.update"]} mode="all">
  <button>Edit</button>
</Can>

<Cannot permission="billing.edit">
  <Alert>You cannot edit billing.</Alert>
</Cannot>

<Role name="admin">
  <AdminPanel />
</Role>

Hooks

Programmatic permission and role checking with hooks.

import { usePermission, useRole, useCan } from "@zentauri-ui/zentauri-components/permission";

function DeleteButton() {
  const canDelete = usePermission("users.delete");
  const isAdmin = useRole("admin");

  const { allowed, missingPermissions } = useCan({
    permissions: ["users.delete", "users.create"],
    mode: "any",
  });

  return canDelete ? <button>Delete</button> : null;
}

Route guard

Protect entire route segments with RouteGuard.

import { RouteGuard } from "@zentauri-ui/zentauri-components/permission";

<RouteGuard
  permission="users.read"
  fallback={<div>Access denied</div>}
  redirectTo="/403"
>
  <UsersPage />
</RouteGuard>

Async permissions

Load permissions from an API asynchronously.

import { PermissionProvider, PermissionBoundary } from "@zentauri-ui/zentauri-components/permission";

function App() {
  return (
    <PermissionProvider
      loadPermissions={async () => {
        const res = await fetch("/api/permissions");
        return res.json();
      }}
      loadRoles={async () => {
        const res = await fetch("/api/roles");
        return res.json();
      }}
    >
      <PermissionBoundary
        loading={<Spinner />}
        fallback={<NoAccess />}
      >
        <Dashboard />
      </PermissionBoundary>
    </PermissionProvider>
  );
}