Application shell, sidebar, and header

The shell composes navigation, page outlets, top-level actions, preferences, and overlays.

Start with your first page. Shared ui* providers are registered by createAdmin. Examples belong inside a route template, not the root HTML document. The page and its optional controller load through Atrium’s lazy route registry.

Minimal example

/**
 * Integrate application shell, sidebar, and header into an application-owned route.
 *
 * @author Laurent Declercq l.declercq@agon-innovation.ch
 * @version 20260921
 */
import { createAdmin } from '@agon/atrium';

// Use the complete configuration from src/starter/main.js.
// Register the application once, then call its start method once.

Settings and behavior

• Required consumer configuration includes base, namespace, brand, routes, pages, groups, messages, and session.
• Use a unique namespace to isolate persisted UI preferences.
• The sidebar supports expanded and collapsed desktop states and a mobile drawer.
• The header’s avatar badge opens the user menu, with arrow-key navigation and Escape dismissal.
• The customizer controls light/dark appearance, palette, RTL, content width, and pinned, docked, or scrolling header/sidebar modes.
• Routes can select default, auth, or wallboard layout.
• Keep the root document focused on the shell and router outlets.

Nested navigation

Set group on the parent route and parent on each child route. The parent value is the parent’s logical path. This supports one submenu level. Both parent and child remain real, directly addressable pages with their own lazy templates.

/**
 * Declare a component overview and one independently loaded child page.
 *
 * @author Laurent Declercq l.declercq@agon-innovation.ch
 * @version 20260921
 */
export const routes = [
  {
    path: '/components',
    label: 'components',
    icon: 'layers',
    group: 'library',
    template: 'pages/components.html',
  },
  {
    path: '/components/buttons',
    label: 'buttons',
    parent: '/components',
    template: 'pages/components/buttons.html',
  },
];

Declare the library group and both message keys in your application configuration. Child routes omit group. Navigation and global search require both the child’s and parent’s presentation capabilities. Define the child’s own capability for page access checks, and enforce authorization independently in your backend.

The parent’s link opens its overview and toggles its submenu in the same click or Enter-key activation. The link exposes aria-expanded and aria-controls without a separate disclosure button. Navigating to the overview preserves the selected expansion state. Child deep links and history navigation to a child open the matching submenu, with aria-current on the exact page. Submenu expansion lasts for the current shell instance. Selecting a parent from the desktop icon rail expands the sidebar and reveals its children. Mobile route selection closes the navigation drawer. Long menus scroll within the sidebar while its brand and footer remain accessible.

External navigation links

Add links to a sidebar group for public HTTP or HTTPS destinations that do not have an application page. The group remains visible without routes and appears in the order declared by groups. Its external links follow any permitted routes in the same group.

/**
 * Append a public documentation destination after the application navigation groups.
 *
 * @author Laurent Declercq l.declercq@agon-innovation.ch
 * @version 20260921
 */
export const groups = [
  { id: 'workspace', label: 'workspaceGroup' },
  {
    id: 'documentation',
    label: 'documentationGroup',
    links: [
      {
        href: 'https://docs.example.com',
        label: 'documentationSite',
        icon: 'document'
      }
    ]
  }
];

Supply the group and link message keys in each consumer locale. These are ordinary browser links that navigate in the same tab, retain their absolute URL under subdirectory or hash routing, and close the mobile drawer when selected. They do not receive an active-page state, a lazy route template, or a global page-search entry. Keep destinations in trusted application configuration. These public links have no presentation capability filter. The destination owns its authorization.

The showcase declares its final Documentation group in src/showcase/config/routes.js and links to the production documentation hostname. The link is present during local development too, but its destination requires the hosted documentation site. Local browser checks substitute the destination response and do not require that site to be reachable.

Integration notes

Install @agon/atrium-starter and run yarn atrium-starter publish for a working shell. See theming for tokens and integration for backend ownership and hosting.

Working reference

See the starter composition root. Return to the component index.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921