Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

Layout Block


Interactive Live Preview
Try it. Make it yours.

Variant 1 of 8

Live Preview and Source

Open
Setting the scene...

Interactive preview

Add This Block

Add a complete navigation layout to an existing Preact app in three steps. Copy the source, connect the Kamod dependencies and bring your own pages. The files live in your project, so you can adapt the sidebar, header and account menu as your application grows.

  1. Copy the Block

    Copy the files from the Showcase’s Code Tab into src/components/application-shell-1. Skip preview.tsx, demo-data.tsx and assets/kamod-ui-logo.svg unless you want the demo. To keep the demo branding, copy the SVG into the same assets subfolder.

    Keep the Reusable Files Together: application-shell-1.tsx, app-sidebar.tsx, nav-main.tsx, nav-user.tsx, menu.tsx, types.ts and index.ts. Their relative imports work within this folder; the entrypoint exports the component and its public types. The examples assume an importing file at src/App.tsx; adjust the relative import if yours lives elsewhere. Keep the repository’s license with your copy.

  2. Install Missing Dependencies

    Install the packages your app does not already have. Kamod UI supplies the interactive components, Icons supplies the SVG icons, and Themes and Preact Signals support the shared styling and state setup. Use your project's existing package manager.

    Install PackagesTerminal
    pnpm add @kamod-ch/ui @kamod-ch/icons @kamod-ch/themes @preact/signals
    Keep your existing setup
    Compatibility:
    @kamod-ch/ui must export useDropdown and support the portal prop on DropdownContent, and expose createRovingFocus from @kamod-ch/ui/lib/interactive. The shell's menu adapters use these APIs to manage keyboard navigation and keep menus outside the sidebar's scroll container. Use a UI release that includes these APIs before integrating the block.
  3. Set Up Styles and Import

    Follow the Theme and Tailwind Setup
    in your app's global stylesheet, then ensure Tailwind scans the copied files as well as the Kamod components. An app that already uses Kamod can keep its existing theme setup. Import the shell from your new local folder:
    Import SetupTypeScript
    import { ApplicationShell1 } from "./components/application-shell-1";
    Check the First Render

    The sidebar, borders and page background should follow your app's theme. If the layout appears unstyled, check the global CSS import and Tailwind source detection before changing the block's classes.

Usage

Pass your brand, navigation, user and breadcrumbs
, then place your page content inside the shell. Mount it in your app's shared layout so pages can reuse the same navigation. The example below starts with one destination and lets the shell manage its own sidebar state.
Usage PatternTypeScript
import { ApplicationShell1 } from "./components/application-shell-1";

export const App = () => (
  <ApplicationShell1
    brand={{ name: "Kamod UI", description: "Component library", href: "/" }}
    navigationGroups={[{
      id: "workspace", label: "Workspace",
      items: [{ id: "overview", label: "Overview", href: "/overview" }],
    }]}
    user={{ name: "Alex Morgan", email: "alex@example.com" }}
    breadcrumbs={[{ label: "Overview" }]}
    currentPath="/overview"
    onUserAction={(action) => console.log(action)}
  >
    <h1 class="text-2xl font-semibold">Overview</h1>
    <p>Your application content goes here.</p>
  </ApplicationShell1>
);
Keep the Shell Mounted Across Routes

Replace its children and route data without changing the shell’s key to preserve local sidebar state. The shell already owns its SidebarProvider; adding a second provider outside it will not control its inner navigation. Use the public Desktop State Props instead.

Connect navigation
Links use their href by default. With a client router, pass its current path to currentPath and handle ordinary clicks in onNavigate. Update the breadcrumbs with each page; they are not inferred from the navigation tree.
Connect account actions
Replace the example's console logging with your account, billing, notification and logout handlers. Place your routed content inside the shell; it already provides the page's main landmark and content padding.

Props and Data

Supply the identity, destinations and page content; the shell supplies the layout and controls. Start with the four required data props, then add callbacks or controlled desktop state as your app needs them. All ten public types are exported by your local application-shell-1 entrypoint.

API reference
Your API, from source

Definitions and field comments below come directly from types.ts, keeping the reference aligned with the block's public API. Explore the Data Type Reference for complete data shapes, required and optional fields, and practical notes on how each type is used.

Component Props

Each row lists a prop accepted by ApplicationShell1, its TypeScript type and how it affects the shell. Follow a linked type to open its full definition, including individual fields and their documentation. Optional props let you supply page content, connect navigation and account actions, control desktop expansion or adjust wrapper styling.

The red asterisk
marks the four required props: brand, navigationGroups, user and breadcrumbs. Supply all four when using the block; the two array props may be empty. Props without this marker are optional. Hover, focus or tap the icon to see its label.
ApplicationShell1 props, types and descriptions; required props are marked
Prop / typeDescription
brand
ApplicationShellBrand
Sidebar identity, an optional logo and an optional home or workspace link.
navigationGroups
Readonly ApplicationShellNavigationGroup[]
Ordered groups of destinations, with at most one level of child links. See Type Your Navigation Data.
user
ApplicationShellUser
Account name and email, with an optional avatar or custom initials. No session is inferred.
breadcrumbs
Readonly ApplicationShellDestination[]
An independent, ordered trail. The last entry is never a link; earlier entries hide below 768px. An empty array omits the trail and its separator.
children
ComponentChildren
Page content inside the existing main landmark and padded content area. No placeholder content is inserted.
currentPath
string
Exact URL used to match item href values. An item's explicit active value takes precedence; no router or path normalization is applied.
onNavigate
ApplicationShellNavigate
Handles linked brand, breadcrumb and navigation activation, or a leaf action button. Native links still work without it.
onUserAction
(Action: ApplicationShellUserAction) => Void
Receives an account menu selection. Your app implements the resulting navigation or account operation.
open
boolean
Controls desktop expansion: true expands, false collapses to icons. Update this value in onOpenChange to respond to the toggle. See Sidebar State.
defaultOpen
boolean
Initial uncontrolled desktop state. Ignored when open is supplied; changing it after mount does not reset the sidebar.
onOpenChange
(open: boolean) => void
Reports requested desktop expansion in either state mode. Mobile visibility does not call this callback.
class
string
Additional classes merged onto the outer SidebarProvider wrapper.
className
string
Alias for class, merged after it when both are supplied.
Wrapper Styling Outer layer

class and className style the outer wrapper. Keep customization at that boundary: arbitrary HTML attributes and other provider options are not forwarded.

One main is enough. The shell already renders main; don’t nest another.See the structure

Complete Component Signature

13 declared fields
ApplicationShell1Props
All required and optional inputs in one copyable declaration. Inspect the Complete Definition of ApplicationShell1Props before adapting it.

Type Your Navigation Data

Use stable IDs
and keep child destinations to one level. Group IDs must be unique among groups, and item IDs among siblings. This example gives Projects its own page and an expandable submenu. Pass the resulting array to navigationGroups and set currentPath="/projects/recent" to mark Recent projects as current. The satisfies operator checks the shape without replacing the inferred type.
Usage PatternTypeScript
import { FolderIcon } from "@kamod-ch/icons/lucide";
import type { ApplicationShellNavigationGroup } from "./components/application-shell-1";

export const navigationGroups = [{
  id: "workspace",
  label: "Workspace",
  items: [{
    id: "projects",
    label: "Projects",
    href: "/projects",
    icon: FolderIcon,
    items: [
      { id: "recent", label: "Recent projects", href: "/projects/recent" },
      { id: "archive", label: "Archive", href: "/projects/archive", disabled: true },
    ],
  }],
}] satisfies readonly ApplicationShellNavigationGroup[];
One tree, three types
Group → Item → Child Link. A child is a leaf, so it cannot contain another submenu.
Keep selection explicit
Matching is exact: /projects and /projects/ differ. Use active when your app needs its own matching rules.

Data Type Reference

Open a definition to inspect its exact fields, optional markers and original JSDoc. Multiple definitions can stay open for comparison. Types joined with & inherit the fields of the referenced type. The asterisk identifies each shape's required fields, including inherited ones.

Required Type
marks a type used directly by a required shell prop. The prop must be supplied; navigationGroups and breadcrumbs may still be empty arrays.

ComponentChildren, ComponentType and JSX in these definitions are Preact types. The copied types.ts already imports them.

Brand and Logo

4 declared fields
Required Type
ApplicationShellBrand
The identity shown at the top of the sidebar, including in icon mode. Inspect the Complete Definition of ApplicationShellBrand before adapting it.
Required fields
name

Account Identity

4 declared fields
Required Type
ApplicationShellUser
Display data for the sidebar footer and account menu. Inspect the Complete Definition of ApplicationShellUser before adapting it.
Required fields
name, email

Navigation Groups

3 declared fields
Required Type
ApplicationShellNavigationGroup
The outer level of your navigation: an ID, optional heading and ordered items. Inspect the Complete Definition of ApplicationShellNavigationGroup before adapting it.
Required fields
id, items
src/components/application-shell-1/types.ts9 lines
/** Ordered navigation section; its optional label appears above its items. */
export type ApplicationShellNavigationGroup = {
  /** Stable key, unique among groups. */
  id: string;
  /** Section heading; omitted headings do not leave an empty label. */
  label?: string;
  /** Destinations displayed in the supplied order. */
  items: readonly ApplicationShellNavigationItem[];
};

Keep group IDs unique and item IDs unique among siblings. Omitting a group label leaves no empty heading. Readonly arrays work directly; the shell preserves your order.

Top-Level Items and Branches

7 declared fields
ApplicationShellNavigationItem
A navigation link that can also contain one level of child links. Inspect the Complete Definition of ApplicationShellNavigationItem before adapting it.
Required fields
id, label
6 declared fields
ApplicationShellNavigationLink
A destination plus its stable ID, optional icon and interaction state. Inspect the Complete Definition of ApplicationShellNavigationLink before adapting it.
Required fields
id, label
Required Type
ApplicationShellDestination
The shared label and optional URL used by breadcrumbs and navigation callbacks. Inspect the Complete Definition of ApplicationShellDestination before adapting it.
Required fields
label

Navigation Icons

Declaration
ApplicationShellIcon
A Preact component that accepts the shell's SVG styling and accessibility props. Inspect the Complete Definition of ApplicationShellIcon before adapting it.
Branch Selection

An active child makes the branch start expanded and highlights its icon-mode menu or URL-free disclosure trigger. A parent rendered as a separate link keeps its own active state; a child does not mark that parent link as the current page. Later path changes do not reset an already mounted disclosure. Switching to desktop icon mode replaces the disclosure with a dropdown; expanding the sidebar creates a new disclosure from the current active state.

Navigation and Callbacks

Native links need no callback. For client routing
, supply onNavigate and cancel only the clicks your router handles. Keep currentPath and breadcrumbs in sync with your router; the shell does not infer either.

Navigation Handler

Declaration
ApplicationShellNavigate
Receives a destination and the Preact click event from its link or action button. Inspect the Complete Definition of ApplicationShellNavigate before adapting it.

This adapter preserves modified clicks and leaves external, hash-only and other non-root-relative URLs to the browser. Connect it to your router's navigation function and pass the returned handler to onNavigate.

Usage PatternTypeScript
import type { ApplicationShellNavigate } from "./components/application-shell-1";

// Supply your router's navigation function when creating this handler.
export const createNavigateHandler = (
  navigate: (href: string) => void,
): ApplicationShellNavigate => (destination, event) => {
  if (
    event.defaultPrevented || event.button !== 0 ||
    event.metaKey || event.ctrlKey || event.shiftKey || event.altKey
  ) return;

  const { href } = destination;
  // This example intercepts only app-local, root-relative URLs.
  if (!href?.startsWith("/") || href.startsWith("//")) return;

  event.preventDefault();
  navigate(href);
};
Mobile Navigation

Ordinary brand and navigation selections close the mobile sheet after the callback runs, including when it calls preventDefault(). Modified clicks leave the sheet open. Disabled destinations do not call the handler.

ApplicationShellUserAction
The exact action identifiers passed to onUserAction, without a click event. Inspect the Complete Definition of ApplicationShellUserAction before adapting it.

Sidebar State

Uncontrolled Default
Omit open. The desktop sidebar starts expanded; use defaultOpen={false} to start with icons. onOpenChange can observe changes without owning state.
Controlled
Supply open. To let the built-in toggles change it, update this value in onOpenChange; otherwise the sidebar keeps the supplied state. Your app owns desktop expansion in this mode.
Usage PatternTypeScript
import { useState } from "preact/hooks";
import {
  ApplicationShell1,
  type ApplicationShell1Props,
} from "./components/application-shell-1";

type AppFrameProps = Omit<
  ApplicationShell1Props,
  "open" | "defaultOpen" | "onOpenChange"
>;

export const AppFrame = (props: AppFrameProps) => {
  const [open, setOpen] = useState(true);

  return (
    <ApplicationShell1 {...props} open={open} onOpenChange={setOpen} />
  );
};
Desktop and Mobile Are Separate

Below 768px the sidebar uses an independently managed sheet that starts closed when the shell mounts. The toggle opens that sheet instead of changing desktop expansion, so mobile toggles do not call onOpenChange. Setting open or defaultOpen does not open the mobile sheet; your desktop preference still applies when returning to a wider screen.

Remember the Desktop Preference. For optional persistence, install @kamod-ch/hooks with your package manager (for example, pnpm add @kamod-ch/hooks) and use this version of AppFrame. Kamod Hooks' useLocalStorageState handles storage and state updates while keeping the same open/onOpenChange wiring. This package is only needed for this optional example.

Usage PatternTypeScript
import { useLocalStorageState } from "@kamod-ch/hooks";
import {
  ApplicationShell1,
  type ApplicationShell1Props,
} from "./components/application-shell-1";

type AppFrameProps = Omit<
  ApplicationShell1Props,
  "open" | "defaultOpen" | "onOpenChange"
>;

export const AppFrame = (props: AppFrameProps) => {
  const [open, setOpen] = useLocalStorageState<boolean>("app-sidebar-desktop-open", {
    defaultValue: true,
    getInitialValueInEffect: true,
    deserializer: (raw) => raw !== "false",
    onError: () => { /* Storage is optional; the toggle still works in memory. */ },
  });

  return (
    <ApplicationShell1 {...props} open={open} onOpenChange={setOpen} />
  );
};
What is remembered
Only desktop expansion is saved in this browser for this site. A missing or invalid value falls back to expanded; blocked storage leaves the toggle usable without persistence. The mobile sheet and navigation submenu states are not saved.
First render
getInitialValueInEffect uses the expanded default for both server rendering and the first client render, then restores storage after mounting. The sidebar may briefly appear expanded before a saved collapsed preference is restored. To avoid that shift, your server can read the core sidebar's sidebar_state cookie and pass its parsed boolean as defaultOpen on the first render, or initialize controlled state with it. The core writes this cookie but does not restore it automatically.

About This Block

Application Shell 1 Is the Frame Around Your Application. It gives people a consistent place to navigate, understand where they are and reach their account controls, while your pages occupy the main content area. It suits dashboards, workspaces and internal tools that share navigation across several screens.

Structure and Composition

The layout has three parts: a sidebar, a compact header and a flexible content area. The Sidebar Keeps Context in View with a brand at the top, grouped links in the middle and an account menu at the bottom. The header places the sidebar toggle beside a vertical separator and a breadcrumb trail. A bottom border separates these controls from the page below.

The block composes existing Kamod components. SidebarProvider coordinates the sidebar controls, AppSidebar combines the brand and navigation, and SidebarInset provides the main landmark. Breadcrumb, Collapsible, Dropdown, Avatar and Separator supply the smaller pieces. This keeps the shell consistent with the rest of your Kamod interface and lets you customize a part without replacing the whole layout. Start with the minimal integration, then use Component Props to introduce your application’s data.

Navigation and Routing

Navigation is driven by navigationGroups, displayed in the order you supply. Each group has a stable ID, an optional heading and its items. An item can be a direct link or a branch with One Level of Child Links. Branches expand inline in the full sidebar. If a parent also has an href, its link and disclosure toggle stay separate, so opening a submenu does not unexpectedly navigate away.

Pass currentPath to highlight links by an exact match with their href. An item's explicit active value takes precedence, including false. A branch initially opens when it or a child is active; later path changes update the highlight without overriding the user's disclosure choice. Disabled items cannot be activated, and disabling a branch also disables its child links.

Exact matching is intentional. The Navigation Helper uses this expression to resolve an item’s active state:

Usage PatternTypeScript
item.active ?? (item.href !== undefined && item.href === path);

An explicit active= overrides even a matching URL. Normalize trailing slashes in your route data, or supply active for a parent that should stay highlighted on descendant pages. The typed navigation example shows how groups, items and child destinations fit together.

The Shell Does Not Choose a Router for You. Links follow their URLs normally. To use client-side routing, handle onNavigate(destination, event), call event.preventDefault() for the click you handle and update your route. Preserve Ctrl/Cmd, Shift and Alt clicks so browser shortcuts keep working. A leaf without an href acts as an action button; a branch without one only toggles its submenu. Breadcrumbs are supplied separately: the last entry describes the current page, while earlier entries may link to parent destinations. Use the router adapter example to preserve native browser actions.

Responsive Behavior and State

Desktop navigation keeps its hierarchy. At desktop widths, the sidebar starts expanded and can collapse to an icon rail. Direct links keep accessible names and tooltips; branches open dropdowns that expose their parent destination, when present, and child links. The header toggle and sidebar rail both control this state, so nested navigation remains reachable even when space is limited.

Below the sidebar’s 768px breakpoint, the same navigation moves into a modal sheet opened by the header toggle. The sheet starts closed and closes after an ordinary navigation selection, including a selection handled by your router. Modified clicks leave it open. On narrow screens, the breadcrumb trail shows only the current page to leave room for the toggle and page title.

Use defaultOpen for an initial desktop preference, or pass open and onOpenChange to control it from your app. The callback can also observe changes in uncontrolled mode. Desktop Collapse and Mobile Visibility Are Independent: the mobile sheet manages its own state and does not overwrite the desktop preference. See Sidebar State for controlled and persisted examples; mount one provider for this frame.

Account Menu and Page Content

The footer displays the user's name, email and optional avatar. When an image is unavailable, it shows initials from the first two words of the name, or the initials you provide. The account menu offers Account, Billing, Notifications and Log Out. Choosing one reports its identifier through onUserAction and dismisses the menu. Connect these callbacks to your own pages, dialogs or authentication service; the block itself does not manage a session. The account action reference lists the exact identifiers, and nav-user.tsx is the place to change which actions are offered.

Everything passed as children appears beneath the header inside the existing main landmark. Replace the demo's muted placeholders with a dashboard, form, table or routed page. The content wrapper provides padding and flexible vertical space, while your page owns its headings, loading states and data. Avoid nesting another main element inside the shell.

Accessibility and Styling

Navigation controls retain accessible labels in icon mode, current links expose aria-current, and disclosure buttons report whether their content is expanded. Menus focus the first enabled item when opened; Arrow Up/Down move between items and Home/End jump to the first or last. Escape closes a menu and returns focus to its trigger. Inside the mobile sheet, closing the account menu with Escape leaves the sheet open; a subsequent Escape closes the sheet and restores focus to its opener.

Colors come from semantic sidebar tokens, including bg-sidebar, text-sidebar-foreground and border-sidebar-border. Pair page surfaces with bg-background and text-foreground. The same markup supports light and dark themes, and reduced-motion preferences suppress the shell's transitions and animations. Keep labels meaningful, maintain visible focus styles and use the app-wide theme setup when adapting the block. Long labels and email addresses truncate visually, so concise names remain easier to scan.

Making It Your Own

Start by replacing the brand, navigation groups, user data and breadcrumbs. Keep group and item IDs stable, supply real destination URLs and connect the callbacks your app needs. Use class or className for wrapper styling, and edit the copied components when you need a different header, account action or navigation arrangement.

The showcase’s sample workspace and hash links live in demo-data.tsx. preview.tsx adds local selection messages and placeholder panels so you can explore the interactions without an application backend. These files are optional: The Reusable Shell Has No Dependency on the Demo's Content or Routing State. After integration, check your longest labels, nested destinations and account actions on both a narrow screen and a desktop, using the keyboard as well as the pointer. Include a failed page request and an empty result: those belong in your page content while the navigation remains usable. The whole-journey checklist gives you a final review sequence.

Prepare for Production

Turn the working preview into a dependable application boundary. Add one real route and one service-backed action before expanding the navigation. The frame supplies structure; your application owns identity, permissions, records and recovery.

Routes and State Ownership

Mount the shell above the changing page. Replacing children should not recreate the sidebar provider on every route. Keep the same component type and avoid a route-dependent key on the shell when users expect their desktop collapse choice to survive. Derive currentPath, breadcrumbs and navigation permissions from the router/session rather than synchronizing another selected-item state.

Use stable IDs for navigation groups and items. Build static navigation outside the component; use useMemo only when its inputs actually change, such as a project ID, locale or permissions. Do not put draft text in those dependencies. Native links remain useful without a router callback; intercept only the clicks your client router handles and preserve modified clicks for opening another tab.

Keep the final breadcrumb descriptive and noninteractive. Pass an empty trail for pages that do not need one. Each shell already supplies a main landmark: start page content with its heading or a section, not a second nested main. Review State Ownership before moving values into global state.

Requests and Cleanup

Cancel work when its owning route changes. The shell does not fetch records or install polling timers. A page that fetches project data should release its request, subscription or observer when it unmounts or changes record. Keep pending and error states next to the action that creates them, and update a saved baseline only after the server confirms the write.

This effect belongs in a route component with projectId, setProject and setError supplied by that page. Import useEffect from preact/hooks. The cancellation guard prevents an obsolete response from replacing a newer project:

Usage PatternTypeScript
useEffect(() => {
  const request = new AbortController();
  async function loadProject() {
    try {
      const response = await fetch("/api/projects/" + encodeURIComponent(projectId), {
        signal: request.signal,
      });
      if (!response.ok) throw new Error("Project could not be loaded.");
      const project = await response.json();
      if (!request.signal.aborted) setProject(project);
    } catch (error) {
      if (!request.signal.aborted) setError(error);
    }
  }
  void loadProject();
  return () => request.abort();
}, [projectId]);

Validate returned data at your service boundary. Clear the previous error and choose whether to keep stale content or display a loading state when the route changes. Aborting a browser request does not undo a server-side mutation; use your service’s retry and deduplication policy for saves. See Submission and Recovery for preserving edits after a failed submission.

Release Checks

Test a real journey, from opening a page to saving a change. These checks belong to your integrated application: the shell supplies the frame, while your router, forms and services supply the behavior. Work through the steps once, then repeat the journey at the sizes and settings below.

Start with one real journey

For example: open a project, change its name, save it and return to the overview. Use realistic records and a test account with limited access as well as a full-access account.

Screen widths
320 · 768 · 1024 · 1440px
Appearance
Light + dark · your app’s theme
Content
Long labels · empty + busy pages
  1. Follow the route

    Try this

    Open a nested destination, refresh that page, then use the browser’s Back and Forward buttons. Collapse and expand the desktop sidebar. On mobile, open the menu and choose a destination. Connect these actions through your router and navigation data.

    Looks right when

    The URL, page heading, active link and breadcrumbs agree. A direct link opens the correct page, selecting a mobile destination closes the sheet, and an unavailable destination does not navigate or run an action.

  2. Take the keyboard route

    Try this

    Put the pointer aside. Use Tab and Shift + Tab to reach the sidebar toggle, links and account menu. Use arrow keys inside the menu, then press Escape. Repeat with the mobile sheet and check the page with a screen reader.

    Looks right when

    Focus is visible and follows a sensible order. Controls announce useful names and their expanded state. Closing a menu or sheet with Escape returns focus to its trigger. After navigation, your app makes the new page heading discoverable.

  3. Give the layout a stretch

    Try this

    Try the screen sizes above with a long page title, translated navigation labels and a wide table. Switch between light and dark, then zoom the browser to 200%. Review Layout and Styling if content spills outside the frame.

    Looks right when

    Text remains readable and controls stay reachable. The document does not scroll sideways; a wide table or editor scrolls inside its own area. Long names remain understandable, and text, focus rings and active items stay clear in both modes.

  4. Keep unfinished work safe

    Try this

    Type a draft, toggle the sidebar and open the account menu before saving. If your page has an inspector or another dismissible panel, close and reopen it. Decide separately what should happen when users leave the route.

    Looks right when

    Shell controls do not erase a page’s draft. State that must survive an unmounted panel lives above that panel. Navigation follows your app’s save, discard or confirmation policy; the shell does not persist drafts for you.

  5. Make the unhappy paths useful

    Try this

    Try a slow request, an empty result, a failed save and an account without access. Give each case a clear message and a useful next action. Follow the submission and recovery guide when connecting a real form.

    Looks right when

    Loading eventually resolves to content or an explanation. Failed saves preserve edits and offer a safe retry. Empty pages explain how to get started. Your service checks permissions even when a navigation item is hidden.

  6. Check the work behind the screen

    Try this

    In a production build, record a route change and a short typing session with realistic data using the browser’s performance tools. Switch records while a request is pending, then leave and revisit the page. Inspect the request and cleanup boundaries.

    Looks right when

    Typing and navigation stay responsive. An old response cannot overwrite the new record, and timers, listeners and subscriptions stop when their owner leaves. Paginate or virtualize long lists when measurements show a need; keep layout in CSS where possible.

Leave a trail for the next release

Record the build or commit, browser, screen size and result in your release notes. For a failure, include the steps, expected behavior and a screenshot or short recording. Fix and repeat that check before calling the journey ready.

Keep the copied shell source and local changes under version control. Compare updates before replacing shared helpers, and rerun the affected checks when routing, permissions or layout change. Turn repeatable failures into focused automated tests; keep a manual keyboard and visual pass as well.

Design Reference

The original Shadcnblocks layout brings grouped navigation, a breadcrumb header and an account menu into one application frame. Use it to compare the placement of controls and the balance between navigation and page content. When adapting the Kamod version, start with your own navigation hierarchy and route names, then use the Typed Navigation Example and callback reference above to connect destinations and account actions to your app.

This block adapts the original sidebar, breadcrumb header and account menu using Kamod's Preact components and theme tokens. Your application supplies its routing and account actions.

Map the layout to your own pages with the Typed Navigation Example.

Use the reference to compare the layout and interactions. To add this version to your app, use the source in this page's Code tab and follow the Kamod Setup Instructions above.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Bring a Complete Layout into Your App to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.