Role-Based UI Guard

Overview

Role-Based UI Guard is a TypeScript/React component library that provides a complete role-based access control (RBAC) system for frontend applications. It enables developers to conditionally render UI elements, restrict actions, and manage permissions based on user roles with a hierarchical permission model.

Features

• Role Hierarchy System: 6 predefined roles (guest, viewer, editor, moderator, admin, superadmin) with automatic permission inheritance
• Permission Engine: 10 granular permissions (view:public, edit:content, manage:users, manage:billing, etc.) mapped to roles
• RoleGuard Component: Declarative wrapper to conditionally render content based on roles or permissions
• useGuard Hook: Programmatic access to permission checks within components
• Flexible Matching: Support for single role/permission checks, multiple role checks, and permission combinations (any/all)
• Fallback UI: Optional fallback content when access is denied
• Interactive Demo: Full-featured demo UI showing role switching, permission matrices, and live access control
• TypeScript Support: Fully typed with Role and Permission enums

Tech Stack

• React 19.0.0 — UI framework
• React Router DOM 7.14.2 — Routing support
• TypeScript 5.6.0 — Type safety
• Tailwind CSS 4.2.2 — Styling
• Vite 6.0.0 — Build tool

Setup/Usage

Installation

npm install
npm run dev

Basic Usage

Wrap your app with AuthProvider:

import { AuthProvider, RoleGuard, useGuard } from './App';

function App() {
  return (
    <AuthProvider initialRole="viewer">
      <Dashboard />
    </AuthProvider>
  );
}

Using RoleGuard Component

// Guard by single role
<RoleGuard role="admin">
  <AdminPanel />
</RoleGuard>

// Guard by multiple roles
<RoleGuard roles={["admin", "moderator"]}>
  <ModeratorTools />
</RoleGuard>

// Guard by permission
<RoleGuard permission="edit:content">
  <EditButton />
</RoleGuard>

// Guard by multiple permissions (require all)
<RoleGuard 
  permissions={["manage:users", "manage:billing"]} 
  requireAll={true}
>
  <BillingPanel />
</RoleGuard>

// With fallback UI
<RoleGuard 
  role="admin" 
  fallback={<LockedFeature />}
  showFallback={true}
>
  <AdminFeature />
</RoleGuard>