App shell usage guidelines

Caution

This component is currently in an unstable state and may undergo significant changes in future releases.

The app shell is a layout component that provides the foundational structure for applications. It creates a consistent layout that accommodates header, navigation, and main content areas.

When to use

• As the root layout component for applications to provide consistent structure.
• When you need a responsive layout that adapts to different screen sizes.
• To create applications with persistent navigation and header elements.

Usage

Preview

Code

import {
  AppHeader,
  UNSTABLE_AppShell as AppShell,
  UNSTABLE_AppShellBody as AppShellBody,
  Text,
} from '@cimpress-ui/react';

export default function Demo() {
  return (
    <AppShell>
      <AppHeader title="My app" titleLink={{ href: '#', target: '_self' }} />
      <AppShellBody>
        <Text as="p" margin={16}>
          Hello, world!
        </Text>
      </AppShellBody>
    </AppShell>
  );
}

Copy code Open in StackBlitz

The basic app shell provides a simple layout structure with a header and main content area.

With side nav

Preview

Code

import {
  AppHeader,
  UNSTABLE_AppShell as AppShell,
  UNSTABLE_AppShellBody as AppShellBody,
  UNSTABLE_SideNav as SideNav,
  UNSTABLE_SideNavList as SideNavList,
  UNSTABLE_SideNavListItem as SideNavListItem,
  Text,
} from '@cimpress-ui/react';
import { IconPlaceholder } from '@cimpress-ui/react/icons';

export default function Demo() {
  return (
    <AppShell>
      <AppHeader title="My app" titleLink={{ href: '#', target: '_self' }} />
      <SideNav>
        <SideNavList>
          <SideNavListItem href="#1" isActive={true} icon={<IconPlaceholder />}>
            Menu item 1
          </SideNavListItem>
          <SideNavListItem href="#2" isActive={false} icon={<IconPlaceholder />}>
            Menu item 2
          </SideNavListItem>
          <SideNavListItem href="#3" isActive={false} icon={<IconPlaceholder />}>
            Menu item 3
          </SideNavListItem>
        </SideNavList>
      </SideNav>
      <AppShellBody>
        <Text as="p" margin={16}>
          Hello, world!
        </Text>
      </AppShellBody>
    </AppShell>
  );
}

Copy code Open in StackBlitz

App shell can include a side nav to provide navigation throughout the application. Side nav is preferred for applications with a large number of pages.

When used inside app shell, responsive behavior is handled automatically. On smaller screens, the side nav collapses to an overlay that can be toggled open/closed by the navigation toggle in the app header.

With collapsible side nav (unstable)

Preview

Code

import {
  AppHeader,
  UNSTABLE_AppShell as AppShell,
  UNSTABLE_AppShellBody as AppShellBody,
  UNSTABLE_SideNav as SideNav,
  UNSTABLE_SideNavList as SideNavList,
  UNSTABLE_SideNavListItem as SideNavListItem,
  Text,
} from '@cimpress-ui/react';
import { IconPlaceholder } from '@cimpress-ui/react/icons';

export default function Demo() {
  return (
    <AppShell>
      <AppHeader title="My app" titleLink={{ href: '#', target: '_self' }} />
      <SideNav UNSTABLE_isCollapsible>
        <SideNavList>
          <SideNavListItem href="#1" isActive={true} icon={<IconPlaceholder />}>
            Menu item 1
          </SideNavListItem>
          <SideNavListItem href="#2" isActive={false} icon={<IconPlaceholder />}>
            Menu item 2
          </SideNavListItem>
          <SideNavListItem href="#3" isActive={false} icon={<IconPlaceholder />}>
            Menu item 3
          </SideNavListItem>
        </SideNavList>
      </SideNav>
      <AppShellBody>
        <Text as="p" margin={16}>
          Hello, world!
        </Text>
      </AppShellBody>
    </AppShell>
  );
}

Copy code Open in StackBlitz

Side nav can be configured to collapse to an icon-only rail on large viewports. See collapsible in the side nav documentation for more details.

With top nav

Preview

Code

import {
  AppHeader,
  UNSTABLE_AppShell as AppShell,
  UNSTABLE_AppShellBody as AppShellBody,
  Text,
  UNSTABLE_TopNav as TopNav,
  UNSTABLE_TopNavItem as TopNavItem,
} from '@cimpress-ui/react';

export default function Demo() {
  return (
    <AppShell>
      <AppHeader title="My app" titleLink={{ href: '#', target: '_self' }} />
      <TopNav>
        <TopNavItem href="#" isActive>
          Home
        </TopNavItem>
        <TopNavItem href="#about">About</TopNavItem>
        <TopNavItem href="#contact">Contact</TopNavItem>
      </TopNav>
      <AppShellBody>
        <Text as="p" margin={16}>
          Hello, world!
        </Text>
      </AppShellBody>
    </AppShell>
  );
}

Copy code Open in StackBlitz

The app shell can include a top nav for a horizontal navigation bar between related sections or pages.