@rqdhw3n/react-access-control

Lightweight access control utilities for React applications. The package provides a small context provider, a declarative Can component, focused hooks, pure utility functions, and an optional React Router entrypoint for page protection.

GitHub: https://github.com/rqdhw3ns

Features

• Tiny runtime footprint
• React 18+ compatible
• Works with Vite, Next.js, CRA, and TypeScript React apps
• Roles and permissions support
• Declarative and programmatic access checks
• Optional React Router v6 route protection
• Shared access context across both the main package and router entrypoint
• ESM, CJS, and TypeScript declaration output

Installation

Install the core package:

npm install @rqdhw3n/react-access-control

If you want route protection, install React Router too:

npm install @rqdhw3n/react-access-control react-router-dom

yarn add @rqdhw3n/react-access-control react-router-dom

pnpm add @rqdhw3n/react-access-control react-router-dom

Quick Start

import {
  AccessProvider,
  Can,
  useCanPermission
} from '@rqdhw3n/react-access-control';

function DeleteButton() {
  const canDeleteUsers = useCanPermission('users.delete');

  if (!canDeleteUsers) {
    return null;
  }

  return <button type="button">Delete user</button>;
}

export function App() {
  return (
    <AccessProvider
      roles={['admin']}
      permissions={['users.create', 'users.delete']}
    >
      <Can role="admin">
        <section>Admin panel</section>
      </Can>

      <DeleteButton />
    </AccessProvider>
  );
}

AccessProvider

Wrap your app with AccessProvider to make the current user's roles and permissions available throughout the tree.

import { AccessProvider } from '@rqdhw3n/react-access-control';

<AccessProvider
  roles={['admin']}
  permissions={['users.create', 'users.delete']}
>
  <App />
</AccessProvider>;

Can Component

Render children only when the access requirement is satisfied.

import { Can } from '@rqdhw3n/react-access-control';

<Can role="admin">
  <AdminPanel />
</Can>;

<Can permission="users.delete" fallback={<NoAccess />}>
  <DeleteButton />
</Can>;

<Can permissions={['users.create', 'users.update']} requireAll>
  <UserActions />
</Can>;

You can combine role and permission requirements. When requireAll is false, matching any supplied role or permission is enough. When requireAll is true, every supplied role and permission requirement must match.

ProtectedRoute

ProtectedRoute is available from a separate router entrypoint so apps that do not use React Router do not need the dependency. It uses the same AccessProvider context as the main package, so one provider can drive both component-level and route-level access checks.

import { ProtectedRoute } from '@rqdhw3n/react-access-control/router';

ProtectedRoute must be rendered inside AccessProvider.

Basic Example

import { AccessProvider } from '@rqdhw3n/react-access-control';
import { ProtectedRoute } from '@rqdhw3n/react-access-control/router';

<AccessProvider
  roles={['admin']}
  permissions={['users.view', 'users.delete']}
>
  <ProtectedRoute permission="users.delete" redirectTo="/">
    <DeleteUsersPage />
  </ProtectedRoute>
</AccessProvider>;

React Router v6 Example

import { BrowserRouter, Route, Routes } from 'react-router-dom';
import { AccessProvider } from '@rqdhw3n/react-access-control';
import { ProtectedRoute } from '@rqdhw3n/react-access-control/router';

function App() {
  return (
    <AccessProvider
      roles={['admin']}
      permissions={['dashboard.view', 'users.view', 'users.delete']}
    >
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<HomePage />} />

          <Route
            path="/dashboard"
            element={
              <ProtectedRoute permission="dashboard.view" redirectTo="/">
                <DashboardPage />
              </ProtectedRoute>
            }
          />

          <Route
            path="/admin"
            element={
              <ProtectedRoute role="admin" redirectTo="/">
                <AdminPage />
              </ProtectedRoute>
            }
          />

          <Route
            path="/users/delete"
            element={
              <ProtectedRoute permission="users.delete" redirectTo="/">
                <DeleteUsersPage />
              </ProtectedRoute>
            }
          />
        </Routes>
      </BrowserRouter>
    </AccessProvider>
  );
}

Redirect Example

<ProtectedRoute permission="users.delete" redirectTo="/">
  <DeleteUsersPage />
</ProtectedRoute>

Fallback Example

<ProtectedRoute role="admin" fallback={<NoAccessPage />}>
  <AdminPage />
</ProtectedRoute>

If access is denied, ProtectedRoute behaves like this:

• redirectTo provided: renders React Router's <Navigate />
• fallback provided without redirectTo: renders the fallback
• neither provided: returns null

Hooks

useAccess()

import { useAccess } from '@rqdhw3n/react-access-control';

function Summary() {
  const { roles, permissions, canAccess } = useAccess();

  return (
    <pre>
      {JSON.stringify(
        {
          roles,
          permissions,
          canManageUsers: canAccess({ permission: 'users.manage' })
        },
        null,
        2
      )}
    </pre>
  );
}

useCanRole(role)

import { useCanRole } from '@rqdhw3n/react-access-control';

function AdminBadge() {
  const isAdmin = useCanRole('admin');

  return isAdmin ? <span>Admin</span> : null;
}

useCanPermission(permission)

import { useCanPermission } from '@rqdhw3n/react-access-control';

function CreateUserButton() {
  const canCreateUser = useCanPermission('users.create');

  return canCreateUser ? <button>Create user</button> : null;
}

useCanAccess(options)

import { useCanAccess } from '@rqdhw3n/react-access-control';

function UserActions() {
  const canManageUsers = useCanAccess({
    roles: ['admin', 'manager'],
    permissions: ['users.create', 'users.update'],
    requireAll: false
  });

  return canManageUsers ? <div>User actions</div> : null;
}

Utility Functions

All utility functions are pure and can be used outside React.

import {
  hasRole,
  hasPermission,
  canAccess
} from '@rqdhw3n/react-access-control';

hasRole(['admin', 'editor'], ['admin']);
hasPermission(['users.create'], ['users.create', 'users.update'], false);

canAccess({
  userRoles: ['manager'],
  userPermissions: ['reports.view'],
  roles: ['admin', 'manager'],
  permission: 'reports.view'
});

Props

AccessProviderProps

| Prop | Type | Required | Description | | --- | --- | --- | --- | | roles | string[] | No | Current user roles | | permissions | string[] | No | Current user permissions | | children | ReactNode | Yes | React tree that receives access context |

CanProps

| Prop | Type | Required | Description | | --- | --- | --- | --- | | role | string | No | Single required role | | roles | string[] | No | Multiple required roles | | permission | string | No | Single required permission | | permissions | string[] | No | Multiple required permissions | | requireAll | boolean | No | Require all supplied checks to pass | | fallback | ReactNode | No | Rendered when access is denied | | children | ReactNode | Yes | Rendered when access is allowed |

ProtectedRouteProps

| Prop | Type | Required | Description | | --- | --- | --- | --- | | role | string | No | Single required role | | roles | string[] | No | Multiple required roles | | permission | string | No | Single required permission | | permissions | string[] | No | Multiple required permissions | | requireAll | boolean | No | Require all supplied checks to pass | | redirectTo | string | No | Redirect path when access is denied | | fallback | ReactNode | No | Rendered when access is denied and no redirect is used | | children | ReactNode | Yes | Rendered when access is allowed |

TypeScript

The package ships with full type declarations and exports the main public types:

import type {
  AccessProviderProps,
  CanProps,
  AccessContextValue,
  AccessCheckOptions,
  ProtectedRouteProps
} from '@rqdhw3n/react-access-control';

Security Note

This package only controls client-side rendering and navigation. Your backend must still enforce roles, permissions, and authorization rules for every protected action and route.

Example App

A minimal Vite example app is included in example/ for local development and manual testing.

License

MIT