Utility Components

Utility components provide essential functionality for loading states, error handling, layout management, and other common patterns. These components support the infrastructure of the application and improve user experience.

Loaders & Spinners

FullscreenSpinner

Full-screen loading overlay with spinner and optional text.

Location: src/components/Loaders/FullscreenSpinner.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | isLoading | boolean | Yes | - | Loading state | | children | ReactNode | Yes | - | Content to render | | loadingText | string | No | - | Loading text to display |

Usage:

import FullscreenSpinner from 'components/Loaders/FullscreenSpinner';

<FullscreenSpinner isLoading={isSubmitting} loadingText='Saving changes...'>
  <YourPageContent />
</FullscreenSpinner>;

SuspenseSpinner

Lightweight spinner for React Suspense fallbacks.

Location: src/components/Loaders/Spinner.tsx

Usage:

import SuspenseSpinner from 'components/Loaders/Spinner';

<Suspense fallback={<SuspenseSpinner />}>
  <LazyComponent />
</Suspense>;

FullPageLoader

Full-page loading spinner with overlay.

Location: src/components/commons/FullPageLoader.tsx

Usage:

import FullPageLoader from 'components/commons/FullPageLoader';

{
  isGlobalLoading && <FullPageLoader />;
}

Error Handling

ErrorBoundary

React error boundary with Sentry integration.

Location: src/components/Errors/ErroBoundary.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Child components to wrap | | fallback | ReactNode | No | ErroBoundaryFallback | Custom fallback component |

Usage:

import { ErrorBoundary } from 'components/Errors/ErroBoundary';

<ErrorBoundary fallback={<CustomErrorFallback />}>
  <YourComponent />
</ErrorBoundary>;

Fallback

Default error fallback component with friendly message.

Location: src/components/Errors/Fallback.tsx

Usage:

import Fallback from 'components/Errors/Fallback';

<ErrorBoundary fallback={<Fallback />}>
  <AppContent />
</ErrorBoundary>;

TableError

Error component specifically for table data errors.

Location: src/components/Errors/TableError.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | error | Object | Yes | - | Error response object |

Usage:

import TableError from 'components/Errors/TableError';

{
  error && <TableError error={error} />;
}

Toast & Notifications

CustomToast

Custom toast notification component with various status types.

Location: src/components/CustomToast/index.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | status | string | Yes | - | Status type (success, error, warning, info) | | title | string | No | - | Toast title | | description | string/ReactNode | No | - | Toast description | | onClose | function | No | - | Close handler | | onButton | function | No | - | Button action handler |

Usage:

import CustomToast from 'components/CustomToast';

<CustomToast
  status='success'
  title='Success'
  description='Operation completed successfully'
  onClose={handleClose}
/>;

Banner

Alert banner component with scroll area for long content.

Location: src/components/Banner/index.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | status | string | Yes | - | Alert status (error, warning, success, info) | | title | string | No | - | Banner title | | description | string/ReactNode | Yes | - | Banner description | | onClose | function | No | - | Close handler | | descriptionStyles | CSSProperties | No | - | Description styling |

Usage:

import Banner from 'components/Banner';

<Banner
  status='warning'
  title='Warning'
  description='Please review the following issues before proceeding'
  onClose={handleClose}
/>;

Wrappers & Layouts

GlobalWrapper

Main application wrapper with sidebar and navbar layout.

Location: src/components/Wrappers/GlobalWrapper.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Page content |

Usage:

import GlobalWrapper from 'components/Wrappers/GlobalWrapper';

<GlobalWrapper>
  <YourPageContent />
</GlobalWrapper>;

GlobalNavSidebarWrapper

Wrapper for global navigation with sidebar.

Location: src/components/GlobalNavSidebarWrapper.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Content to render | | width | string/number | No | '460px' | Sidebar width | | button | ReactNode | No | - | Button element |

Usage:

import GlobalNavSidebarWrapper from 'components/GlobalNavSidebarWrapper';

<GlobalNavSidebarWrapper width='400px' button={<ActionButton />}>
  <NavigationContent />
</GlobalNavSidebarWrapper>;

WPPageContainer

Standard page container with title, description, and actions.

Location: src/components/WPagesTemplates/WPPageContainer.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Page content | | pageTitle | ReactNode | No | - | Page title | | pageDescription | ReactNode | No | - | Page description | | pageActions | ReactNode | No | - | Action buttons | | BackButton | ReactNode | No | - | Back navigation button |

Usage:

import WpPageContainer from 'components/WPagesTemplates/WPPageContainer';

<WpPageContainer
  pageTitle='User Management'
  pageDescription='Manage user accounts and permissions'
  pageActions={&lt;Button&gt;Add User</Button>}
  BackButton={<BackButton />}
>
  <UserManagementContent />
</WpPageContainer>;

WPPage

Simple page wrapper component.

Location: src/components/WPagesTemplates/WPage.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Page content | | ...otherProps | StackProps | No | - | Additional Chakra UI props |

Usage:

import { WPPage } from 'components/WPagesTemplates/WPage';

<WPPage spacing={6} p={4}>
  <PageHeader />
  <PageContent />
</WPPage>;

Scroll & Navigation

ScrollArea

Custom scrollable area with styled scrollbar.

Location: src/components/ScrollArea.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Scrollable content | | scrollThumbColor | string | No | 'whiteAlpha.500' | Scrollbar thumb color |

Usage:

import ScrollArea from 'components/ScrollArea';

<ScrollArea scrollThumbColor='green.500'>
  <LongContent />
</ScrollArea>;

GlobalSidebar

Application sidebar with navigation menu.

Location: src/components/GlobalSidebar.tsx

Features:

• Nested navigation menus
• Permission-based menu items
• Responsive design
• Logo and branding
• User portal switching

Usage:

import GlobalSidebar from 'components/GlobalSidebar';

<GlobalSidebar />;

GlobalNavbar

Application navbar with user menu and actions.

Location: src/components/GlobalNavbar/index.tsx

Features:

• User profile menu
• Company switching
• Help system integration
• Responsive design
• Logout functionality

Usage:

import GlobalNavbar from 'components/GlobalNavbar';

<GlobalNavbar />;

Empty States

ComingSoon

Empty state component for features under development.

Location: src/components/ComingSoon.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | page | string | No | - | Page/feature name | | plural | boolean | No | false | Use plural form | | variant | string | No | - | Variant (maintenance, under-maintenance) |

Usage:

import ComingSoon from 'components/ComingSoon';

<ComingSoon page='Reports' plural variant='maintenance' />;

NotDataFound

Empty state for data tables and charts.

Location: src/components/WPIcons/Illustrations/NoDataIcon.tsx

Usage:

import NoDataIcon from 'components/WPIcons/Illustrations/NoDataIcon';

<VStack>
  <NoDataIcon />
  &lt;Text&gt;No data available</Text>
</VStack>;

Providers

TableProvider

Context provider for table state management.

Location: src/components/Tables/TableContext/TableContext.tsx

Features:

• Pagination state
• Sorting state
• Filter state
• Search state

Usage:

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

<TableProvider>
  <YourTableComponent />
</TableProvider>;

useTableState

Hook to access table context state.

Usage:

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

const { pagination, sorting, filters } = useTableState();

useTableDispatch

Hook to dispatch table actions.

Usage:

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

const dispatch = useTableDispatch();
dispatch({ type: 'PAGE_RESET' });

Filter Utilities

FilteringComponent (ReusableFilter)

Reusable filter component with popover interface.

Location: src/components/ReusableFilter/index.tsx

Props: | Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | children | ReactNode | Yes | - | Filter form content | | handleSubmit | function | Yes | - | Filter submit handler | | query | Object | Yes | - | Current filter state | | setQuery | function | Yes | - | Filter state setter | | isOpen | boolean | Yes | - | Popover open state | | onOpen | function | Yes | - | Open handler | | onClose | function | Yes | - | Close handler | | isLoading | boolean | Yes | - | Loading state | | isDisabled | boolean | Yes | - | Disabled state | | handleReset | function | No | - | Reset handler |

Usage:

import FilteringComponent from 'components/ReusableFilter';

<FilteringComponent
  handleSubmit={handleFilter}
  query={filters}
  setQuery={setFilters}
  isOpen={isFilterOpen}
  onOpen={onFilterOpen}
  onClose={onFilterClose}
  isLoading={isFiltering}
  isDisabled={false}
  handleReset={resetFilters}
>
  <VStack spacing={4}>
    &lt;FormControl&gt;
      &lt;FormLabel&gt;Status</FormLabel>
      <Select {...register('status')}>
        <option value='active'>Active</option>
        <option value='inactive'>Inactive</option>
      </Select>
    </FormControl>
    &lt;FormControl&gt;
      &lt;FormLabel&gt;Date Range</FormLabel>
      <DateRangePicker {...register('dateRange')} />
    </FormControl>
  </VStack>
</FilteringComponent>;

Conditional Rendering Utilities

useFilterState

Custom hook for managing filter state.

Usage:

import { useFilterState } from 'components/ReusableFilter';

const [filterState, handleChange] = useFilterState({});

Child Component Cloning

Pattern for enhancing child components with additional props.

Usage:

const RenderedChildren = Children.map(children, child => {
  if (isValidElement(child)) {
    return React.cloneElement(child, {
      ...child.props,
      variant,
      filterState,
      currentState,
      handleChange,
    });
  }
  return child;
});

Best Practices

Error Boundary Usage

// Wrap route components
<ErrorBoundary>
  <Route path="/dashboard" component={Dashboard} />
</ErrorBoundary>

// Wrap async components
<ErrorBoundary fallback={<ComponentError />}>
  <Suspense fallback={<Loading />}>
    <LazyComponent />
  </Suspense>
</ErrorBoundary>

Loading State Management

// Use loading wrappers for page-level loading
<FullscreenSpinner isLoading={isPageLoading} loadingText='Loading page...'>
  <PageContent />
</FullscreenSpinner>;

// Use inline spinners for component-level loading
{
  isComponentLoading ? <SuspenseSpinner /> : <Component />;
}

Scroll Area Implementation

// Use for sidebar navigation
<ScrollArea>
  <NavigationMenu />
</ScrollArea>

// Use for modal content
&lt;ModalBody&gt;
  &lt;ScrollArea&gt;
    <LongModalContent />
  </ScrollArea>
</ModalBody>

Toast Notification Patterns

// Success toast
toast({
  render: () => (
    <CustomToast
      status='success'
      title='Success'
      description='Operation completed successfully'
    />
  ),
  duration: 3000,
  isClosable: true,
});

// Error toast with action
toast({
  render: () => (
    <CustomToast
      status='error'
      title='Error'
      description='Something went wrong'
      onButton={handleRetry}
    />
  ),
  duration: null,
  isClosable: true,
});

Performance Considerations

Lazy Loading

• Use React.lazy() with Suspense and SuspenseSpinner
• Implement code splitting for large components
• Use ErrorBoundary to catch loading errors

Memory Management

• Clean up event listeners in ScrollArea
• Dispose of toast notifications properly
• Use React.memo for expensive wrapper components

Optimization Tips

• Use useCallback for filter handlers
• Implement proper dependency arrays in useEffect
• Debounce search and filter operations
• Use virtual scrolling for large lists

Related Components

• Layout Components: Integration with layout structure
• Table Components: Context providers and error handling
• Form Components: Filter utilities and validation
• Interactive Components: Modal and popover wrappers

Styling and Theming

All utility components support:

• Chakra UI theme integration
• Responsive design patterns
• Custom color schemes
• Accessibility features
• Dark mode compatibility