aurcare-ui

A modern, flexible UI component library for healthcare applications built with React, Next.js, and HeroUI.

Features

• Dynamic Sidebar: Collapsible sidebar with nested navigation, RTL support, and badges
• Dynamic Navbar: User profile, notifications, theme switcher, and language switcher
• TypeScript: Full type safety with comprehensive TypeScript definitions
• Dark Mode: Built-in dark mode support with next-themes
• RTL Support: Full right-to-left language support
• Customizable: Extensive props for customization including background control and per-item styling
• Accessible: Built with accessibility in mind

Installation

npm install aurcare-ui

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom next next-themes @heroui/button @heroui/badge @heroui/dropdown @heroui/avatar @heroui/divider @heroui/theme lucide-react

Sidebar Component

Basic Usage

import { Sidebar } from 'aurcare-ui';
import { Home, Users, Calendar, Settings } from 'lucide-react';

function App() {
  return (
    <Sidebar
      sections={[
        {
          id: 'main',
          title: 'Main',
          items: [
            {
              id: 'home',
              label: 'Home',
              href: '/',
              icon: Home,
            },
            {
              id: 'users',
              label: 'Users',
              href: '/users',
              icon: Users,
              badge: 5,
              badgeColor: 'danger',
            },
          ],
        },
        {
          id: 'settings',
          title: 'Settings',
          items: [
            {
              id: 'settings',
              label: 'Settings',
              href: '/settings',
              icon: Settings,
            },
          ],
        },
      ]}
      appName="My App"
      appSubtitle="Dashboard"
    />
  );
}

Nested Navigation

<Sidebar
  sections={[
    {
      id: 'main',
      items: [
        {
          id: 'patients',
          label: 'Patients',
          icon: Users,
          subItems: [
            {
              id: 'patient-list',
              label: 'Patient List',
              href: '/patients',
              icon: List,
            },
            {
              id: 'patient-add',
              label: 'Add Patient',
              href: '/patients/add',
              icon: UserPlus,
            },
          ],
        },
      ],
    },
  ]}
/>

Controlled Collapse

const [isCollapsed, setIsCollapsed] = useState(false);

<Sidebar
  sections={sections}
  isCollapsed={isCollapsed}
  onCollapse={setIsCollapsed}
/>

RTL Support

<Sidebar
  sections={sections}
  locale="ar"
  appName="تطبيقي"
  appSubtitle="لوحة التحكم"
/>

Custom Header and Footer

<Sidebar
  sections={sections}
  customHeader={
    <div className="p-4">
      <h1>Custom Header</h1>
    </div>
  }
  customFooter={
    <div className="p-4 border-t">
      <p>Version 1.0.0</p>
    </div>
  }
/>

Background Control (v1.2.0)

Control the entire background of the Sidebar for custom light/dark themes:

// Custom dark theme with slate background
<Sidebar
  sections={navigationSections}
  backgroundClassName="bg-slate-50 dark:bg-slate-950"
/>

// Custom gradient background
<Sidebar
  sections={navigationSections}
  backgroundClassName="bg-gradient-to-b from-blue-50 to-white dark:from-slate-900 dark:to-slate-800"
/>

// Different border style
<Sidebar
  sections={navigationSections}
  backgroundClassName="bg-gray-100 dark:bg-gray-900 border-r-4 border-primary"
/>

Per-Item Styling (v1.2.0)

Add custom styles to individual navigation items:

import { NavSection } from 'aurcare-ui';
import { Home, Users, Settings, AlertTriangle, Brain, Star } from 'lucide-react';

const navigationSections: NavSection[] = [
  {
    id: 'main',
    items: [
      {
        id: 'dashboard',
        label: 'Dashboard',
        href: '/dashboard',
        icon: Home,
        // Custom styling for this item
        className: 'bg-blue-50 dark:bg-blue-950 border-l-4 border-blue-500'
      },
      {
        id: 'users',
        label: 'Users',
        href: '/users',
        icon: Users,
        // Different style for this item
        className: 'bg-green-50 dark:bg-green-950'
      },
      {
        id: 'emergency',
        label: 'Emergency',
        href: '/emergency',
        icon: AlertTriangle,
        // Special highlight for important item
        className: 'bg-red-100 dark:bg-red-950 text-red-700 dark:text-red-400 font-bold ring-2 ring-red-500'
      },
      {
        id: 'new-feature',
        label: 'AI Analytics',
        href: '/analytics',
        icon: Brain,
        badge: 'BETA',
        badgeColor: 'warning',
        // Beta feature badge styling
        className: 'bg-purple-50 dark:bg-purple-950 border-l-4 border-purple-500'
      },
      {
        id: 'premium',
        label: 'Premium Reports',
        href: '/reports/premium',
        icon: Star,
        // Premium feature styling
        className: 'bg-gradient-to-r from-yellow-50 to-orange-50 dark:from-yellow-950 dark:to-orange-950 border-l-4 border-yellow-500'
      }
    ]
  }
];

Dynamic Per-Item Styling

import { useTranslations } from 'next-intl';
import { NavSection } from 'aurcare-ui';
import { Mail, Activity } from 'lucide-react';

function useNavigationSections() {
  const t = useTranslations();
  const hasUnreadMessages = true; // From your state
  const isSystemHealthCritical = false; // From your state

  const navigationSections: NavSection[] = [
    {
      id: 'main',
      items: [
        {
          id: 'messages',
          label: t('messages'),
          href: '/messages',
          icon: Mail,
          badge: hasUnreadMessages ? '5' : undefined,
          badgeColor: 'danger',
          // Dynamic styling based on unread messages
          className: hasUnreadMessages
            ? 'bg-red-50 dark:bg-red-950/50 border-l-4 border-red-500'
            : ''
        },
        {
          id: 'system',
          label: t('systemHealth'),
          href: '/system',
          icon: Activity,
          // Dynamic styling based on system status
          className: isSystemHealthCritical
            ? 'bg-red-100 dark:bg-red-950 text-red-700 dark:text-red-400 animate-pulse'
            : 'bg-green-50 dark:bg-green-950'
        }
      ]
    }
  ];

  return navigationSections;
}

Sidebar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | sections | NavSection[] | Required | Navigation sections with items | | isCollapsed | boolean | undefined | Controlled collapse state | | onCollapse | (collapsed: boolean) => void | undefined | Collapse state change callback | | currentPath | string | undefined | Current active path | | locale | string | 'en' | Locale for RTL support | | appName | string | 'Aurcare' | App name in header | | appSubtitle | string | 'Healthcare System' | App subtitle in header | | appLogo | React.ElementType | LayoutDashboard | App logo icon | | className | string | undefined | Additional CSS classes | | expandedWidth | string | 'w-72' | Width when expanded | | collapsedWidth | string | 'w-20' | Width when collapsed | | hideCollapseButton | boolean | false | Hide collapse button | | customHeader | ReactNode | undefined | Custom header component | | customFooter | ReactNode | undefined | Custom footer component | | onNavigate | (item: NavItem) => void | undefined | Navigation callback | | logoClassName | string | undefined | Logo section wrapper classes (v1.1.0) | | logoContainerClassName | string | undefined | Logo container box classes (v1.1.0) | | logoIconClassName | string | undefined | Logo icon classes (v1.1.0) | | navItemClassName | string | undefined | All navigation items classes (v1.1.0) | | navSectionClassName | string | undefined | Section title wrapper classes (v1.1.0) | | backgroundClassName | string | undefined | Control entire sidebar background (v1.2.0) |

Navbar Component

Basic Usage

import { Navbar } from 'aurcare-ui';

function App() {
  return (
    <Navbar
      user={{
        name: 'John Doe',
        email: '[email protected]',
        role: 'Administrator',
      }}
      onLogout={() => console.log('Logout')}
    />
  );
}

With Notifications

<Navbar
  user={{ name: 'John Doe' }}
  notifications={[
    {
      id: '1',
      type: 'info',
      title: 'New Message',
      message: 'You have a new message from Jane',
      time: '5 minutes ago',
      read: false,
    },
    {
      id: '2',
      type: 'success',
      title: 'Task Completed',
      message: 'Your task has been completed successfully',
      time: '1 hour ago',
      read: true,
    },
  ]}
  onNotificationClick={(notification) => console.log(notification)}
  onMarkAllAsRead={() => console.log('Mark all as read')}
/>

With Theme and Language Switcher

<Navbar
  user={{ name: 'John Doe' }}
  showThemeToggle={true}
  showLanguageSwitcher={true}
  languages={[
    { code: 'en', label: 'English' },
    { code: 'ar', label: 'العربية' },
    { code: 'es', label: 'Español' },
  ]}
  currentLanguage="en"
  onLanguageChange={(code) => console.log('Language:', code)}
/>

With Custom Content

<Navbar
  user={{ name: 'John Doe' }}
  leftContent={
    <div className="flex items-center gap-2">
      <Search className="w-5 h-5" />
      <input type="text" placeholder="Search..." />
    </div>
  }
  rightContent={
    <Button variant="flat" color="primary">
      New Task
    </Button>
  }
/>

Background Control (v1.2.0)

Control the entire background of the Navbar for custom themes:

// Custom background with shadow
<Navbar
  user={user}
  backgroundClassName="bg-slate-50 dark:bg-slate-950 shadow-lg"
/>

// Transparent navbar with blur
<Navbar
  user={user}
  backgroundClassName="bg-white/80 dark:bg-slate-900/80 backdrop-blur-md"
/>

// Colored navbar
<Navbar
  user={user}
  backgroundClassName="bg-blue-600 dark:bg-blue-900 text-white"
/>

With Translation Function

import { useTranslations } from 'next-intl';

function App() {
  const t = useTranslations();

  return (
    <Navbar
      user={{ name: 'John Doe' }}
      t={t}
    />
  );
}

Navbar Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | user | UserProfile | { name: 'Admin', role: 'Administrator' } | User profile information | | notifications | Notification[] | [] | Notifications array | | onNotificationClick | (notification: Notification) => void | undefined | Notification click callback | | onMarkAllAsRead | () => void | undefined | Mark all as read callback | | onLogout | () => void | undefined | Logout callback | | onProfileClick | () => void | undefined | Profile click callback | | onSettingsClick | () => void | undefined | Settings click callback | | languages | LanguageOption[] | [{ code: 'en', label: 'English' }, { code: 'ar', label: 'العربية' }] | Available languages | | currentLanguage | string | 'en' | Current language code | | onLanguageChange | (code: string) => void | undefined | Language change callback | | showThemeToggle | boolean | true | Show theme toggle | | showNotifications | boolean | true | Show notifications | | showLanguageSwitcher | boolean | true | Show language switcher | | leftContent | ReactNode | undefined | Custom left content | | rightContent | ReactNode | undefined | Custom right content | | className | string | undefined | Additional CSS classes | | t | (key: string) => string | defaultTranslate | Translation function | | containerClassName | string | undefined | Navbar container classes (v1.1.0) | | notificationsClassName | string | undefined | Notifications dropdown classes (v1.1.0) | | userMenuClassName | string | undefined | User menu dropdown classes (v1.1.0) | | backgroundClassName | string | undefined | Control entire navbar background (v1.2.0) |

Complete Examples

Basic Layout Example

import { Sidebar, Navbar } from 'aurcare-ui';
import { Home, Users, Calendar, Settings } from 'lucide-react';

function DashboardLayout({ children }) {
  const [isCollapsed, setIsCollapsed] = useState(false);

  const sections = [
    {
      id: 'main',
      title: 'Main',
      items: [
        { id: 'home', label: 'Home', href: '/', icon: Home },
        { id: 'users', label: 'Users', href: '/users', icon: Users, badge: 5 },
        { id: 'calendar', label: 'Calendar', href: '/calendar', icon: Calendar },
      ],
    },
    {
      id: 'settings',
      title: 'Settings',
      items: [
        { id: 'settings', label: 'Settings', href: '/settings', icon: Settings },
      ],
    },
  ];

  const notifications = [
    {
      id: '1',
      type: 'info',
      title: 'New Appointment',
      message: 'You have a new appointment scheduled',
      time: '5 minutes ago',
      read: false,
    },
  ];

  return (
    <div className="flex h-screen">
      <Sidebar
        sections={sections}
        isCollapsed={isCollapsed}
        onCollapse={setIsCollapsed}
        appName="Healthcare"
        appSubtitle="Management System"
      />
      <div className="flex-1 flex flex-col">
        <Navbar
          user={{
            name: 'Dr. Jane Smith',
            email: '[email protected]',
            role: 'Administrator',
          }}
          notifications={notifications}
          onLogout={() => console.log('Logout')}
          onNotificationClick={(n) => console.log(n)}
        />
        <main className="flex-1 overflow-y-auto p-6">
          {children}
        </main>
      </div>
    </div>
  );
}

Complete Customization Example (v1.2.0)

Combining all customization features including background control and per-item styling:

import { Sidebar, Navbar } from 'aurcare-ui';
import { NavSection } from 'aurcare-ui';
import { Home, Users, Settings, Bell } from 'lucide-react';

export function CustomLayout({ children }) {
  const navigationSections: NavSection[] = [
    {
      id: 'main',
      title: 'Main Menu',
      items: [
        {
          id: 'dashboard',
          label: 'Dashboard',
          href: '/dashboard',
          icon: Home,
          // Per-item custom styling
          className: 'bg-blue-50 dark:bg-blue-950'
        },
        {
          id: 'users',
          label: 'Users',
          href: '/users',
          icon: Users,
          badge: '12',
          badgeColor: 'primary',
          // Per-item custom styling
          className: 'hover:bg-green-100 dark:hover:bg-green-900'
        }
      ]
    },
    {
      id: 'system',
      title: 'System',
      items: [
        {
          id: 'settings',
          label: 'Settings',
          href: '/settings',
          icon: Settings,
          // Per-item custom styling with border
          className: 'border-l-4 border-purple-500'
        }
      ]
    }
  ];

  return (
    <div className="flex h-screen">
      <Sidebar
        sections={navigationSections}
        appName="My App"
        appSubtitle="Admin Panel"

        // Background control
        backgroundClassName="bg-slate-50 dark:bg-slate-950"

        // Logo customization (v1.1.0)
        logoClassName="px-8 py-4"
        logoContainerClassName="w-14 h-14 rounded-2xl"
        logoIconClassName="w-8 h-8"

        // Navigation items customization (v1.1.0)
        navItemClassName="px-5 py-4 mx-2 rounded-xl"
        navSectionClassName="px-5 mb-4 text-xs"
      />

      <div className="flex-1 flex flex-col">
        <Navbar
          user={{ name: 'John Doe', role: 'Administrator' }}
          notifications={[]}

          // Background control
          backgroundClassName="bg-slate-50 dark:bg-slate-950 shadow-md"

          // Container customization (v1.1.0)
          containerClassName="h-20 px-8"

          // Dropdown customization (v1.1.0)
          notificationsClassName="w-[600px]"
          userMenuClassName="w-96"

          showThemeToggle
          showNotifications
        />

        <main className="flex-1 overflow-y-auto bg-white dark:bg-slate-900">
          <div className="p-6">
            {children}
          </div>
        </main>
      </div>
    </div>
  );
}

Matching Sidebar and Navbar Example

Create a cohesive design with matching backgrounds:

const customTheme = {
  light: "bg-gray-50",
  dark: "bg-slate-950"
};

const backgroundClasses = `${customTheme.light} dark:${customTheme.dark}`;

return (
  <div className="flex h-screen">
    <Sidebar
      sections={navigationSections}
      backgroundClassName={backgroundClasses}
      appName="My App"
      locale={locale}
    />
    <div className="flex-1 flex flex-col">
      <Navbar
        user={user}
        backgroundClassName={backgroundClasses}
        notifications={notifications}
      />
      <main className="flex-1 overflow-y-auto">
        {children}
      </main>
    </div>
  </div>
);

TypeScript Support

All components are fully typed with TypeScript. Import types as needed:

import type {
  NavItem,
  NavSection,
  SidebarProps,
  Notification,
  UserProfile,
  NavbarProps,
} from 'aurcare-ui';

Type Definitions

// NavItem interface
export interface NavItem {
  id: string;
  label: string;
  href?: string;
  icon: React.ElementType;
  subItems?: NavItem[];
  badge?: string | number;
  badgeColor?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
  render?: (item: NavItem, isActive: boolean) => ReactNode;
  className?: string;  // v1.2.0
}

// NavSection interface
export interface NavSection {
  id: string;
  title?: string;
  items: NavItem[];
}

// UserProfile interface
export interface UserProfile {
  name: string;
  email?: string;
  role?: string;
  avatar?: string;
}

// Notification interface
export interface Notification {
  id: string;
  type: 'info' | 'success' | 'warning' | 'danger';
  title: string;
  message: string;
  time: string;
  read: boolean;
}

Styling

This library uses Tailwind CSS and HeroUI. Make sure to include them in your project:

// tailwind.config.js
import { heroui } from '@heroui/theme';

export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  darkMode: 'class',
  plugins: [heroui()],
};

Migration Guide

From v1.1.0 to v1.2.0

No breaking changes! All v1.1.0 code works perfectly in v1.2.0.

New Features:

• backgroundClassName prop for Sidebar and Navbar components
• className prop for individual NavItem objects

// Before (v1.1.0) - Still works!
<Sidebar
  sections={navigationSections}
  logoClassName="px-8"
/>

// After (v1.2.0) - With new features
<Sidebar
  sections={navigationSections}
  logoClassName="px-8"
  backgroundClassName="bg-gray-50 dark:bg-gray-950"  // NEW
/>

// Before (v1.1.0) - Still works!
const sections = [
  {
    id: 'main',
    items: [
      { id: 'home', label: 'Home', href: '/', icon: Home }
    ]
  }
];

// After (v1.2.0) - With new features
const sections = [
  {
    id: 'main',
    items: [
      {
        id: 'home',
        label: 'Home',
        href: '/',
        icon: Home,
        className: 'bg-blue-50 dark:bg-blue-950'  // NEW
      }
    ]
  }
];

Version History

v1.2.0

• Added backgroundClassName prop to Sidebar and Navbar for complete background control
• Added className prop to NavItem for per-item styling
• No breaking changes

v1.1.0

• Added extensive customization props for Sidebar (logo, nav items, sections)
• Added customization props for Navbar (container, dropdowns)
• No breaking changes

v1.0.0

• Initial release with Sidebar and Navbar components

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions, please visit GitHub Issues.