# Context switcher

> The area's working context, always visible in the top bar; every page below implies it.

- Group: Navigation
- Status: stable
- Aliases: brand-switcher, workspace-switcher
- HTML page: https://design.ipmnx.com/components/context-switcher/
- Spec: https://design.ipmnx.com/design/#nx-context-switcher

## Preview

**Active brand** Lives in NxAppShell's context slot. The preview opens its menu; the code is the closed trigger.

```html
<div class="nx-dropdown nx-context">
  <button type="button" class="nx-dropdown__trigger"
      aria-haspopup="menu" aria-expanded="false"
      aria-label="Brand: IPM Facility">
    <span class="nx-context__chip">
      <span class="nx-context__dot" style="background:#2a78d6"
          aria-hidden="true"></span>
      <span class="nx-context__value">IPM Facility</span>
      <svg class="nx-context__caret" width="14" height="14"
          viewBox="0 0 24 24" fill="none" stroke="currentColor"
          stroke-width="2" stroke-linecap="round"
          stroke-linejoin="round" aria-hidden="true"
          focusable="false">
        <path d="m6 9 6 6 6-6" />
      </svg>
    </span>
  </button>
</div>
```

```tsx
<NxContextSwitcher
  label="Brand"
  heading="Choose brand"
  options={[
    {
      id: "1",
      label: "IPM Facility",
      color: "#2a78d6",
      active: true,
    },
    { id: "2", label: "IPM Academy", color: "#eda100" },
  ]}
  allLabel="All brands"
  manage={{ label: "Manage brands", href: "/marketing/brands" }}
  onSelect={setBrand}
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` |   | yes | What the context is; names the button ("Brand: IPM Facility"). |
| `options` | `NxContextOption[]` |   | yes | id, label, color?, active?, href? |
| `allLabel` | `string` | `undefined` |   | A "no context" option (id ""); omit when a context is required. |
| `manage` | `{ label; href }` | `undefined` |   | Link to the page that manages the options. |
| `onSelect` | `(id: string) => void` | `undefined` |   | Called with the chosen id; the host persists it. |
| `heading` | `string` | `undefined` |   | Optional label above the options in the open menu. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-context` | Pill trigger on .nx-dropdown |
| `.nx-context__dot` | Optional valid option colour |
| `.nx-shell__context` | NxAppShell slot after the app switcher |

## Accessibility

- Menu button (NxDropdownMenu): aria-haspopup=menu, Escape/outside click close, focus returns to the trigger.
- The trigger's accessible name includes the active value; colour dots are aria-hidden and the label carries the meaning.

## Do / Don't

- Do: Persist the choice and imply it on every page below (filters, defaults, KPIs).
- Don't ask for the same context again in forms on those pages.

## Related

- [Dropdown menu](https://design.ipmnx.com/components/dropdown-menu.md)
- [Profile menu](https://design.ipmnx.com/components/profile-menu.md)
- [Page header](https://design.ipmnx.com/components/page-header.md)

---

Source: registry.js (NX Design System)
