Skip to main content

Layout Components

Layout components provide the fundamental structure and navigation for the WorkPayCore Frontend application. These components handle the overall application layout, navigation, and content organization.

Components Overview​

Primary Layout Components​

  • Sidebar - Main navigation component with collapsible menu structure
  • Navbar - Top navigation bar with user actions and company switching
  • Wrappers - Layout wrapper components that combine sidebar and navbar

The Sidebar component is the primary navigation component that displays hierarchical menu items based on user roles, permissions, and feature flags.

Component Location​

import Sidebar from 'components/Sidebar';

Key Features​

  • Role-based Navigation: Different menu items for admin and employee views
  • Feature Flag Integration: Menu items conditionally rendered based on enabled features
  • Permission-based Access: Menu items filtered by user permissions
  • Hierarchical Structure: Support for nested submenus
  • Responsive Design: Collapsible on mobile devices
  • External Link Support: Handles both internal routing and external applications
  • Analytics Integration: Tracks sidebar navigation events

Props​

PropTypeDefaultDescription
widthobjectundefinedResponsive width configuration
positionstringundefinedCSS position property
hstringundefinedHeight of sidebar
maxHstringundefinedMaximum height
overflowstringundefinedOverflow behavior
onClosefunctionundefinedCallback when sidebar is closed
...otherPropsanyundefinedAdditional props passed to container

The sidebar dynamically generates menu items based on:

Employee View Menu Items​

  • Home
  • My Wallet (Kenya only)
  • Leave
  • Expenses
  • Disciplinary Tracking
  • Salary Advance
  • Earned Wage Access
  • Loans
  • Marketplace
  • Savings
  • Overtime
  • Performance Management
  • Documents
  • Invoices (for contractors/consultants)
  • Organization Structure

Admin View Menu Items​

  • Home
  • Employees (with submenus)
  • Payroll (with submenus)
  • Global Payroll
  • Invoices
  • Earned Wage Access
  • EOR (Employer of Record)
  • Expenses
  • Leave (with submenus)
  • Benefits (with submenus)
  • Time & Attendance
  • Time & Attendance V2
  • Marketplace
  • Assets
  • Documents
  • Piece Rate
  • Performance Management
  • Recruitment
  • Organization Structure

Admin Section​

  • Settings
  • Employment Types
  • Billing

Usage Examples​

Basic Usage​

import Sidebar from 'components/Sidebar';

function App() {
  return (
    <Sidebar
      width={{ base: '0%', lg: '16%' }}
      position='fixed'
      h='100vh'
      maxH='100vh'
      overflow='initial'
    />
  );
}

With Close Handler​

import Sidebar from 'components/Sidebar';

function MobileSidebar() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Sidebar
      width={{ base: '100%', lg: '16%' }}
      onClose={() => setIsOpen(false)}
    />
  );
}

Menu items are configured with the following structure:

interface MenuItem {
  icon: ReactElement;
  name: string;
  link?: string;
  subMenu: number; // 0 for no submenu, 1+ for submenu levels
  view: boolean; // Visibility condition
  isDisabled?: boolean;
  isExternal?: boolean;
  isNew?: boolean;
  subMenus?: SubMenuItem[];
  onClick?: () => void;
}

interface SubMenuItem {
  name: string;
  link: string;
  view: boolean;
  isDisabled: boolean;
  isNew?: boolean;
}

Feature Integration​

Feature Flags​

The sidebar integrates with the feature flag system:

// Example feature flag check
view: isAdminView() && isFeatureEnabled('expenses');

Permissions​

Menu items are filtered based on user permissions:

// Example permission check
view: isAdminViewWithPermissions(['disciplinary_tracking.cases.view']);

Subscription Status​

Menu items are disabled based on subscription status:

// Example subscription check
isDisabled: !hasActiveSubscription || !featureMap?.includes('Expenses');

Styling and Theming​

The sidebar uses Chakra UI theming:

// Active menu item styling
activeStyle={{
  backgroundColor: theme?.colors['hue-green'][50],
}}

// Disabled menu item styling
sx={
  msm.isDisabled
    ? {
        opacity: '0.5',
      }
    : {}
}

Analytics Integration​

The sidebar tracks navigation events:

const trackSidebarEvents = name => {
  const eventName = `view_${name}`;
  analyticsTrackEvent(eventName.replace(' ', '_'));
};

Custom Sidebar Support​

The sidebar supports custom menu configurations:

const { showCustomSidebar, selectedMenu } = useCustomSidebarMenus();
const mainSidebarMenu = showCustomSidebar ? selectedMenu : MainSidebarMenu;

The sidebar supports modal-based interactions:

function handleSidebarModal(option: SidebarModalOption) {
  setModalOption(option);
  onOpen();
}

Accessibility Features​

  • Keyboard Navigation: Full keyboard support for menu navigation
  • Screen Reader Support: Proper ARIA labels and roles
  • Focus Management: Proper focus handling for menu items
  • High Contrast: Supports high contrast mode

Performance Optimizations​

  • Conditional Rendering: Menu items only rendered when visible
  • Memoized Computations: Heavy computations are memoized
  • Lazy Loading: External links are handled efficiently

Migration Notes​

When updating the sidebar:

  1. Feature Flag Updates: Update feature flag checks when adding new menu items
  2. Permission Updates: Ensure proper permission checks for new features
  3. Icon Updates: Use consistent icon components from WPIcons
  4. Analytics Updates: Add tracking for new menu items

Best Practices​

  1. Menu Organization: Keep menu items logically grouped
  2. Permission Checks: Always include proper permission checks
  3. Feature Flags: Use feature flags for new menu items
  4. Accessibility: Ensure all menu items are keyboard accessible
  5. Performance: Minimize heavy computations in render cycles

The Navbar component provides the top navigation bar with user actions, company switching, and global controls.

Component Location​

import Navbar from 'components/Navbar';

Key Features​

  • User Profile Menu: Avatar, profile access, logout functionality
  • Company Switching: Multi-company support with country selection
  • Help System: Integrated help drawer and documentation links
  • Notifications: Changelog and updates widget
  • Portal Switching: Admin/Employee portal switching
  • Responsive Design: Mobile-friendly navigation

Props​

The Navbar component accepts standard Chakra UI Box props and additional custom props for configuration.

Usage Examples​

Basic Usage​

import Navbar from 'components/Navbar';

function App() {
  return (
    &lt;Box&gt;
      <Navbar />
      {/* Page content */}
    </Box>
  );
}

In Layout Wrapper​

import Navbar from 'components/Navbar';

function Layout({ children }) {
  return (
    &lt;Box&gt;
      <Box position='fixed' top={0} left={0} right={0} zIndex='banner'>
        <Navbar />
      </Box>
      <Box mt='80px'>{children}</Box>
    </Box>
  );
}

Features​

User Profile Menu​

  • User avatar and name display
  • Profile editing access
  • Account settings
  • Logout functionality

Company Management​

  • Company switching modal
  • Country selection for multi-region support
  • Branch switching capabilities

Help and Support​

  • Help drawer with documentation
  • Contact support options
  • Feature request submissions

Notifications​

  • Changelog notifications
  • System updates
  • Feature announcements

Integration Points​

Authentication​

The navbar integrates with the authentication system for user profile and logout functionality.

Company Context​

Multi-company support with context switching capabilities.

Feature Flags​

Conditional rendering based on enabled features.

Analytics​

User action tracking for navigation events.

Styling and Theming​

The navbar uses consistent theming with the sidebar and supports:

  • Brand colors and typography
  • Responsive design breakpoints
  • Dark/light mode support
  • Custom company branding

Accessibility Features​

  • Keyboard Navigation: Full keyboard support
  • Screen Reader Support: Proper ARIA labels
  • Focus Management: Logical tab order
  • High Contrast: Accessibility compliance

Wrappers​

Layout wrapper components that combine sidebar and navbar to create the complete application layout.

GlobalWrapper​

The main layout wrapper that combines sidebar and navbar with proper positioning and responsive behavior.

Component Location​

import GlobalWrapper from 'components/Wrappers/GlobalWrapper';

Usage Examples​

Basic Layout​

import GlobalWrapper from 'components/Wrappers/GlobalWrapper';

function App() {
  return (
    &lt;GlobalWrapper&gt;
      <YourPageContent />
    </GlobalWrapper>
  );
}

With Custom Styling​

import GlobalWrapper from 'components/Wrappers/GlobalWrapper';

function CustomLayout({ children }) {
  return (
    &lt;GlobalWrapper&gt;
      <Box p={8} bg='gray.50'>
        {children}
      </Box>
    </GlobalWrapper>
  );
}

Features​

Layout Structure​

  • Fixed sidebar on desktop
  • Collapsible sidebar on mobile
  • Fixed top navbar
  • Responsive content area

Context Providers​

  • Table context for data table components
  • Theme context for consistent styling
  • Authentication context

Responsive Design​

  • Mobile-first approach
  • Breakpoint-based sidebar behavior
  • Flexible content area

Integration​

TableProvider​

import { TableProvider } from 'components/Tables/TableContext/TableContext';

// Automatically included in GlobalWrapper
&lt;TableProvider&gt;{/* Layout content */}</TableProvider>;

Responsive Configuration​

// Sidebar configuration
<Sidebar
  width={{ base: '0%', lg: '16%' }}
  position='fixed'
  h='100vh'
/>

// Content area configuration
<Stack
  width={{ base: '100%', lg: '84%' }}
  ml={{ base: '0%', lg: '16%' }}
/>

Customization​

Layout Spacing​

// Custom content padding
<Box p={{ base: 1, lg: 8 }} mt='80px !important'>
  {children}
</Box>

Background Colors​

// Custom background
<Flex bgColor='#F2F2F2' minHeight='100vh'>
  {/* Layout content */}
</Flex>

Best Practices​

  1. Consistent Layout: Use GlobalWrapper for consistent page layouts
  2. Responsive Design: Test on multiple screen sizes
  3. Context Management: Leverage provided contexts
  4. Performance: Minimize re-renders in layout components
  5. Accessibility: Ensure proper focus management

Migration Notes​

When updating layout components:

  1. Breakpoint Updates: Review responsive breakpoints
  2. Context Updates: Update context providers as needed
  3. Styling Updates: Maintain consistent theming
  4. Component Updates: Update child component integrations

Resources​