Skip to main content

Side Navigation Block

The SideNavigation Component is a fully customizable and accessible side navigation menu built with React and TypeScript. It provides a complete navigation interface with modern design patterns, mobile-responsive behavior, floating and fixed modes, and flexible customization options.

πŸš€ Installation​

npm install @nodeblocks/frontend-side-navigation-block@0.3.0

πŸ“– Usage​

import {SideNavigation} from '@nodeblocks/frontend-side-navigation-block';
Live Editor
function SimpleSideNavigation() {
  const links = [
    {icon: DashboardIcon, text: 'Dashboard', href: '/dashboard'},
    {icon: InventoryIcon, text: 'Products', href: '/products'},
    {icon: ShoppingCartIcon, text: 'Orders', href: '/orders'},
    {icon: PeopleIcon, text: 'Customers', href: '/customers'},
    {icon: AnalyticsIcon, text: 'Analytics', href: '/analytics'},
    {icon: SettingsIcon, text: 'Settings', href: '/settings'},
  ];

  const header = {
    icon: HomeIcon,
    text: 'My App',
    href: '/',
  };

  return (
    <SideNavigation header={header} links={links} />
  );
}
Result
Loading...

πŸ”§ Props Reference​

Main Component Props​

The main SideNavigation component inherits all props from MUI Stack component with component="aside".

PropTypeDefaultDescription
isFloatingbooleanundefinedWhether the navigation should float over content (mobile-style) or be fixed in place
isMenuOpenbooleanfalseControls whether the navigation menu is open or closed. If not provided, uses internal state
setIsMenuOpen(isMenuOpen: boolean) => voidInternal setterFunction to control the menu open/close state. If not provided, uses internal state setter
header{ icon?: SvgIconComponent; text?: ReactNode; href: string }undefinedHeader link object with optional MUI icon component, text content, and href
links{ icon?: SvgIconComponent; text?: ReactNode; href: string }[]RequiredArray of navigation link objects with optional MUI icon components
childrenBlocksOverrideundefinedFunction to override default blocks or add custom navigation components
classNamestringundefinedAdditional CSS class name(s)
sxSxProps<Theme>See belowMUI system props for styling

Default sx styling:

{
  display: 'inline-flex',
  maxWidth: 300,
  alignItems: 'stretch',
  backgroundColor: 'background.paper',
  width: 'fit-content',
  height: '100%',
  // When open: minWidth: 240
  // When floating: position: 'absolute', top: 0, right: 0, zIndex: theme.zIndex.drawer
  // When floating and closed: display: 'none'
}

Sub-Components​

The SideNavigation component provides several sub-components. All sub-components receive their default values from the main component's context and can override these values through props.

SideNavigation.Overlay​

A full-screen overlay that appears when the floating menu is open. Inherits all MUI Box props.

PropTypeDefaultDescription
childrenReactNodeundefinedCustom content for the overlay
setIsMenuOpen(isMenuOpen: boolean) => voidFrom contextFunction to control menu state when overlay is clicked
onClick(event) => voidCloses menuClick handler (defaults to calling setIsMenuOpen(false))
classNamestringundefinedAdditional CSS class name(s)
sxSxProps<Theme>See belowMUI system props for styling

Default sx styling:

{
  position: 'fixed',
  top: 0,
  left: 0,
  right: 0,
  bottom: 0,
  backgroundColor: '#1d1e20b2',
  zIndex: 'inherit',
}

Note: This component inherits all MUI Box component props.

SideNavigation.MenuButton​

The hamburger menu button for toggling the navigation. Inherits all MUI IconButton props.

PropTypeDefaultDescription
childrenReactNode<SvgIcon component={Menu} />Custom content for the button (defaults to Menu/MenuOpen icon)
isFloatingbooleanFrom contextWhether in floating mode
isMenuOpenbooleanFrom contextCurrent menu open state
setIsMenuOpen(isMenuOpen: boolean) => voidFrom contextFunction to toggle menu state
onClick(event) => voidToggles menuClick handler (defaults to toggling isMenuOpen)
classNamestringundefinedAdditional CSS class name(s)
sxSxProps<Theme>See belowMUI system props for styling

Default sx styling:

{
  display: 'inline-flex',
  border: 'none',
  background: 'none',
  alignSelf: 'flex-start',
  // Floating: p: 1.25
  // Non-floating: p: 1.5, mx: 1.5
}

Note: This component inherits all MUI IconButton component props. The default icon changes between Menu and MenuOpen based on state (non-floating mode).

The navigation links container. Inherits all MUI Stack props with component="nav".

PropTypeDefaultDescription
childrenReactNodeDefault links renderingCustom content to override default links rendering
isFloatingbooleanFrom contextWhether in floating mode (affects link styling)
isMenuOpenbooleanFrom contextWhether menu is open (controls text visibility)
header{ icon?: SvgIconComponent; text?: ReactNode; href: string }From contextHeader link object to display
links{ icon?: SvgIconComponent; text?: ReactNode; href: string }[]From contextArray of navigation links to display
classNamestringundefinedAdditional CSS class name(s)
sxSxProps<Theme>See belowMUI system props for styling

Default sx styling:

{
  position: 'relative',
  zIndex: 'inherit',
}

Note: This component inherits all MUI Stack component props. Each link is rendered as an MUI Link with consistent styling.

🎨 Configuration examples​

Custom Styling​

import HomeIcon from '@mui/icons-material/Home';
import FolderIcon from '@mui/icons-material/Folder';
import GroupIcon from '@mui/icons-material/Group';
import SettingsIcon from '@mui/icons-material/Settings';

function CustomStyledSideNavigation() {
  const links = [
    {icon: HomeIcon, text: 'Home', href: '/'},
    {icon: FolderIcon, text: 'Files', href: '/files'},
    {icon: GroupIcon, text: 'Profile', href: '/profile'},
    {icon: SettingsIcon, text: 'Settings', href: '/settings'},
  ];

  const header = {
    text: 'Menu',
    href: '/',
  };

  return (
    <SideNavigation
      header={header}
      links={links}
      sx={{
        width: 260,
        bgcolor: 'grey.900',
        borderRight: '1px solid',
        borderColor: 'grey.800',
        minHeight: 400,
      }}
    >
      <SideNavigation.Links
        sx={{
          p: 2,
          '& .MuiListItem-root': {
            borderRadius: 1,
            mb: 0.5,
            color: 'grey.300',
            '&:hover': {
              bgcolor: 'grey.800',
            },
          },
          '& .MuiSvgIcon-root': {
            color: 'primary.light',
          },
        }}
      />
    </SideNavigation>
  );
}

Floating Navigation​

import {useState} from 'react';
import DashboardIcon from '@mui/icons-material/Dashboard';
import InventoryIcon from '@mui/icons-material/Inventory';
import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
import SettingsIcon from '@mui/icons-material/Settings';
import HomeIcon from '@mui/icons-material/Home';

function FloatingSideNavigation() {
  const [isMenuOpen, setIsMenuOpen] = useState(false);

  const links = [
    {icon: DashboardIcon, text: 'Dashboard', href: '/dashboard'},
    {icon: InventoryIcon, text: 'Products', href: '/products'},
    {icon: ShoppingCartIcon, text: 'Orders', href: '/orders'},
    {icon: SettingsIcon, text: 'Settings', href: '/settings'},
  ];

  const header = {
    icon: HomeIcon,
    text: 'App',
    href: '/',
  };

  return (
    <SideNavigation
      header={header}
      links={links}
      isFloating={true}
      isMenuOpen={isMenuOpen}
      setIsMenuOpen={setIsMenuOpen}
    >
      <SideNavigation.Overlay />
      <SideNavigation.MenuButton />
      <SideNavigation.Links />
    </SideNavigation>
  );
}
<SideNavigation.Links 
  sx={{ 
    bgcolor: 'grey.100', 
    borderRadius: 2,
    p: 1
  }} 
/>

Custom Menu Button Styling​

<SideNavigation.MenuButton 
  sx={{ 
    color: 'primary.main',
    '&:hover': { bgcolor: 'primary.light' }
  }} 
/>

Custom Overlay Styling​

<SideNavigation.Overlay 
  sx={{ 
    bgcolor: 'rgba(0, 0, 0, 0.7)' 
  }} 
/>

πŸ”§ TypeScript Support​

Full TypeScript support with comprehensive type definitions:

import {SideNavigation} from '@nodeblocks/frontend-side-navigation-block';
import {SvgIconComponent} from '@mui/icons-material';
import DashboardIcon from '@mui/icons-material/Dashboard';
import AnalyticsIcon from '@mui/icons-material/Analytics';
import InventoryIcon from '@mui/icons-material/Inventory';
import SettingsIcon from '@mui/icons-material/Settings';
import HomeIcon from '@mui/icons-material/Home';
import {useState} from 'react';

interface NavLink {
  icon?: SvgIconComponent;
  text?: React.ReactNode;
  href: string;
}

interface NavHeader {
  icon?: SvgIconComponent;
  text?: React.ReactNode;
  href: string;
}

function TypedSideNavigation() {
  const [isMenuOpen, setIsMenuOpen] = useState(false);

  const navigationLinks: NavLink[] = [
    {
      icon: DashboardIcon,
      text: 'Dashboard',
      href: '/dashboard',
    },
    {
      icon: AnalyticsIcon,
      text: 'Analytics',
      href: '/analytics',
    },
    {
      icon: InventoryIcon,
      text: 'Products',
      href: '/products',
    },
    {
      icon: SettingsIcon,
      text: 'Settings',
      href: '/settings',
    },
  ];

  const navigationHeader: NavHeader = {
    icon: HomeIcon,
    text: 'App Name',
    href: '/',
  };

  return (
    <SideNavigation
      header={navigationHeader}
      links={navigationLinks}
      isFloating={false}
      isMenuOpen={isMenuOpen}
      setIsMenuOpen={setIsMenuOpen}
      sx={{
        width: 280,
        minHeight: '100vh',
        borderRight: '1px solid #e5e7eb',
      }}
    >
      <SideNavigation.Links />
    </SideNavigation>
  );
}

πŸ“ Notes​

  1. MUI Integration: The component uses MUI Stack, Box, IconButton, Link, and SvgIcon components under the hood.

  2. Icon Type: The icon property expects an SvgIconComponent from @mui/icons-material, not a string. Import icons like Home, Dashboard, etc.

  3. Internal State Management: If isMenuOpen and setIsMenuOpen are not provided, the component manages its own state internally.

  4. Floating vs Fixed Mode:

    • Floating mode: Navigation appears on top of content with an overlay, positioned absolutely on the right side. Menu button appears outside the navigation.
    • Fixed mode: Navigation is inline with content. Menu button appears inside the navigation with a close button that appears outside when open.

  5. Responsive Behavior: In floating mode, the navigation is hidden when closed (display: 'none'). The overlay blocks interaction with the page content.

  6. Block Override Pattern: Use the children function to customize sub-components while preserving the default block structure.

  7. Z-Index: The component uses theme.zIndex.drawer for floating mode to ensure proper layering.

Built with ❀️ using React, TypeScript, MUI, and modern web standards.