useRoleGuard

auth

Installation

npx usehooks-cli@latest add use-role-guard

Description

A React hook for role-based access control that checks user permissions against required roles. Provides utilities for authorization, redirection, and session management.

Parameters

Name	Type	Default	Description
requiredRoles	string[]	-	Array of roles required to access the resource
options?	UseRoleGuardOptions	-	Configuration options for the role guard

Parameter Properties

options properties:

Name	Type	Description
user?	User \| null	User object with id and roles array
redirectTo?	string	URL to redirect to when unauthorized (default: '/unauthorized')
onUnauthorized?	() => void	Callback function to execute when user is unauthorized
sessionKey?	string	Session storage key for user data (default: 'user')

Return Type

UseRoleGuardReturn

Property	Type	Description
hasAccess	boolean	Whether the user has access to the current resource
hasAnyRole	(roles: string[]) => boolean	Function to check if user has any of the specified roles
hasAllRoles	(roles: string[]) => boolean	Function to check if user has all of the specified roles
isLoading	boolean	Whether the hook is currently loading user data
user	User \| null	Current user object with roles
checkAccess	(requiredRoles: string[]) => boolean	Function to check access for specific roles
redirect	() => void	Function to manually trigger redirect

Examples

Role-based component protection

Protecting components based on user roles

import { useRoleGuard } from '@usehooks.io/use-role-guard';

function AdminPanel() {
  const { hasAccess, isLoading, user, hasAnyRole } = useRoleGuard(
    ['admin', 'moderator'],
    {
      redirectTo: '/login',
      onUnauthorized: () => console.log('Access denied')
    }
  );

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!hasAccess) {
    return <div>Access denied</div>;
  }

  return (
    <div>
      <h1>Admin Panel</h1>
      <p>Welcome, {user?.id}</p>
      {hasAnyRole(['admin']) && (
        <button>Admin Only Action</button>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Automatically redirects unauthorized users if redirectTo is provided
•Loads user data from session storage if no user is provided
•Uses hasAnyRole logic for access checking by default
•Handles loading state while retrieving user data from session

Implementation

'use client';

import { useState, useEffect, useCallback } from "react";

interface User {
  id: string;
  roles: string[];
  [key: string]: any;
}

interface UseRoleGuardOptions {
  user?: User | null;
  redirectTo?: string;
  fallbackComponent?: React.ComponentType;
  onUnauthorized?: () => void;
  sessionKey?: string;
}

interface UseRoleGuardReturn {
  hasAccess: boolean;
  hasAnyRole: (roles: string[]) => boolean;
  hasAllRoles: (roles: string[]) => boolean;
  isLoading: boolean;
  user: User | null;
  checkAccess: (requiredRoles: string[]) => boolean;
  redirect: () => void;
}

export function useRoleGuard(
  requiredRoles: string[],
  options: UseRoleGuardOptions = {}
): UseRoleGuardReturn {
  const {
    user: providedUser,
    redirectTo = "/unauthorized",
    onUnauthorized,
    sessionKey = "user",
  } = options;

  const [user, setUser] = useState<User | null>(providedUser || null);
  const [isLoading, setIsLoading] = useState(!providedUser);

  // Get user from session storage if not provided
  useEffect(() => {
    if (!providedUser && typeof window !== "undefined") {
      try {
        const sessionUser = sessionStorage.getItem(sessionKey);
        if (sessionUser) {
          const parsedUser = JSON.parse(sessionUser);
          setUser(parsedUser);
        }
      } catch (error) {
        console.error("Error parsing user from session:", error);
      } finally {
        setIsLoading(false);
      }
    }
  }, [providedUser, sessionKey]);

  // Check if user has any of the required roles
  const hasAnyRole = useCallback(
    (roles: string[]): boolean => {
      if (!user || !user.roles) return false;
      return roles.some((role) => user.roles.includes(role));
    },
    [user]
  );

  // Check if user has all of the required roles
  const hasAllRoles = useCallback(
    (roles: string[]): boolean => {
      if (!user || !user.roles) return false;
      return roles.every((role) => user.roles.includes(role));
    },
    [user]
  );

  // Check access based on required roles
  const checkAccess = useCallback(
    (roles: string[]): boolean => {
      return hasAnyRole(roles);
    },
    [hasAnyRole]
  );

  // Calculate if user has access to current resource
  const hasAccess = checkAccess(requiredRoles);

  // Redirect function
  const redirect = useCallback(() => {
    if (typeof window !== "undefined" && redirectTo) {
      window.location.href = redirectTo;
    }
  }, [redirectTo]);

  // Handle unauthorized access
  useEffect(() => {
    if (!isLoading && !hasAccess) {
      if (onUnauthorized) {
        onUnauthorized();
      } else if (redirectTo && typeof window !== "undefined") {
        redirect();
      }
    }
  }, [hasAccess, isLoading, onUnauthorized, redirect, redirectTo]);

  return {
    hasAccess,
    hasAnyRole,
    hasAllRoles,
    isLoading,
    user,
    checkAccess,
    redirect,
  };
}

useFullscreen

CLI Docs All Hooks

useTimeout