> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# RemoteShell

The frame of one product inside `AppShell` — its navigation panel, breadcrumbs and content area, all driven by a single `NavConfig`. The URL is the state: the active item, the drill level and the breadcrumbs are matched from the pathname. When a router owns the URL, hand the shell the router’s pathname through `pathname` and take its navigations back through `onNavigate` — then links in the page, the host rail or `router.navigate` keep the menu in sync. Without `pathname` the shell reads `window.location` and only notices `popstate` and its own navigations.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/RemoteShell) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/navigation-remoteshell--overview)

```tsx
import { useNavigate, useRouterState } from '@tanstack/react-router';
import { RemoteShell, RemoteShellBreadcrumb, RemoteShellContent, RemoteShellPanel } from '@wallarm-org/design-system/RemoteShell';
import { edgeNavConfig } from '../AppShell/story-content';

export const Basic = () => {
  const navigate = useNavigate();
  const pathname = useRouterState({ select: state => state.location.pathname });

  return (
    <div className='h-screen bg-bg-page-bg'>
      <RemoteShell
        config={edgeNavConfig}
        basePath='/edge'
        pathname={pathname}
        onNavigate={to => navigate({ to })}
      >
        <RemoteShellPanel resizable />
        <RemoteShellBreadcrumb />
        <RemoteShellContent>
          <EdgePage />
        </RemoteShellContent>
      </RemoteShell>
    </div>
  );
};
```

## Usage

```tsx
import { RemoteShell, RemoteShellBreadcrumb, RemoteShellContent, RemoteShellPanel } from '@wallarm-org/design-system/RemoteShell';
```

## Props

| Prop           | Type                                                 | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config \*      | `NavConfig`                                          |         | Navigation config used to build nav state for sub-components.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| basePath       | `string \| undefined`                                |         | URL prefix stripped before matching and prepended when navigating (e.g. `"/edge"`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| pathname       | `string \| undefined`                                |         | Current pathname. When set, it is the single source of truth for the active nav item, drill level and breadcrumbs, and `window.location` is ignored. Pass it — **together with `onNavigate`** — whenever a router owns the URL: router navigations (links in page content, `router.navigate`, memory history, the host's rail) do not fire `popstate`, so without it the shell can go stale. Without `onNavigate` the shell's own navigations would only reach `window.history`, which a controlled shell ignores (a dev warning flags this). Either form is accepted: with the `basePath` prefix (what `onNavigate` receives) or without it — the prefix is stripped only when the pathname starts with a whole `basePath` segment. With TanStack Router, `useRouterState({ select: s => s.location.pathname })` is router-relative: it excludes the router's own `basepath`. So when the router has `basepath`: - omit `basePath` here — `pathname` and `onNavigate` are then both router-relative and `onNavigate={to => navigate({ to })}` is correct; or - keep `basePath` and strip it in `onNavigate` (`to => navigate({ to: to.slice(basePath.length) \|\| '/' })`), otherwise the router prefixes it a second time. Omit it to read `window.location.pathname` (updated on `popstate` and on the shell's own navigations). |
| onNavigate     | `((pathname: string) => void) \| undefined`          |         | Navigation handler for router integration (TanStack Router, React Router, Next.js, …). Receives the target pathname, prefixed with `basePath` when one is set. Without it the shell pushes to `window.history` itself.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| defaultChecked | `boolean \| undefined`                               |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| autoFocus      | `boolean \| undefined`                               |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| id             | `string \| undefined`                                |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| tabIndex       | `number \| undefined`                                |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| title          | `string \| undefined`                                |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| rel            | `string \| undefined`                                |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| data-testid    | `string \| undefined`                                |         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### RemoteShellBreadcrumb

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

### RemoteShellContent

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| isLoading      | `boolean \| undefined`                               |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

### RemoteShellPanel

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| resizable      | `boolean \| undefined`                               |         |             |
| isLoading      | `boolean \| undefined`                               |         |             |
| loaderCount    | `number \| undefined`                                | `6`     |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

## Explorer