# Command search

> One search across every app the workspace has booked: a modal combobox with one result group per app, opened from the top bar, Ctrl/⌘+K or /.

- Group: Core
- Status: beta
- Aliases: search, command palette, cmd-k, global search
- HTML page: https://design.ipmnx.com/components/command/
- Spec: https://design.ipmnx.com/design/#nx-command

## Preview

**Results with an unavailable app** Static mock of the open card (no overlay, de-roled). One app timed out, so it is named as unavailable instead of counting as no results.

```html
<div class="nx-modal__card nx-command" style="position:relative;
    width:min(560px,100%)">
  <div class="nx-command__bar">
    <svg class="nx-command__icon" width="18" height="18"
        viewBox="0 0 24 24" fill="none" stroke="currentColor"
        stroke-width="2" aria-hidden="true">
      <circle cx="11" cy="11" r="8"/>
      <path d="m21 21-4.3-4.3"/>
    </svg>
    <span class="nx-command__input" style="display:flex;
        align-items:center">acme</span>
    <span class="nx-iconbtn nx-command__close" aria-hidden="true">
      <svg width="18" height="18" viewBox="0 0 24 24" fill="none"
          stroke="currentColor" stroke-width="2">
        <path d="M18 6 6 18"/>
        <path d="m6 6 12 12"/>
      </svg>
    </span>
  </div>
  <div class="nx-command__status">Results for “acme”: 2</div>
  <div class="nx-command__notes">
    <p class="nx-command__note"
        data-coverage="timeout">fileNX is unavailable right now.</p>
  </div>
  <div class="nx-command__list">
    <div class="nx-command__group">
      <div class="nx-command__heading">firmNX</div>
      <div class="nx-command__option"
          style="background:var(--nx-accent-50)">
        <span class="nx-command__option-text">
          <span class="nx-command__title">Acme SARL</span>
        </span>
      </div>
      <div class="nx-command__option">
        <span class="nx-command__option-text">
          <span class="nx-command__title">Q3 VAT return</span>
          <span class="nx-command__path">Acme SARL</span>
        </span>
      </div>
    </div>
  </div>
</div>
```

```tsx
<NxGlobalSearch
  product="firmnx"
  workspaceId={workspaceId}
  locale={locale}
  linkComponent={Link}
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `product` | `string` | `undefined` |   | The host's roster id ("firmnx"); its results are listed first. |
| `workspaceId` | `string` | `undefined` |   | The NX customer id the host verified. Sent as ?workspaceId=; an answer for another workspace is an error. Also keys the recent searches. |
| `source` | `(query, signal) => Promise<NxSuiteSearchResponse>` | `nxSuiteSearchSource(workspaceId)` |   | Where results come from. The default asks the product's own GET /api/suite/search (same origin, no-store, 10 s). |
| `minQueryLength` | `number` | `2` |   | Below it nothing is asked; recent searches are offered instead. |
| `debounceMs` | `number` | `250` |   | Typing pause before a request. |
| `shortcuts` | `{ k?: boolean; slash?: boolean }` | `{ k: true, slash: true }` |   | Ctrl/⌘+K from anywhere; / outside fields and editable regions. |
| `labels` | `Partial<NxGlobalSearchLabels>` | `NX_SEARCH_COPY[locale]` |   | Override single strings; every UI_LANGUAGES entry ships complete copy. |
| `locale` | `string` | `"en"` |   | UI locale; its base language picks the copy ("de-DE" reads de), numbers use ar for darija. |
| `linkComponent` | `ElementType` | `undefined` |   | The host router's link, used only for same-origin results outside /api/. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-command-trigger` | Field-looking desktop trigger (with .nx-search-desktop); the phone opener is .nx-iconbtn.nx-search-mobile-trigger |
| `.nx-command-modal / .nx-command` | In-place modal aligned to the top; the card is 640px wide, full screen below 768px |
| `.nx-command__option` | 44px result row; [aria-selected=true] on --nx-accent-50 |
| `.nx-command__note` | Coverage note outside the listbox; warning tone for data-coverage failed / timeout |
| `.nx-command__sep` | ChevronRight between breadcrumb segments, mirrored in RTL |

## Accessibility

- The dialog (role="dialog" aria-modal="true") is named by a visually hidden h2; the input is a combobox (aria-expanded, aria-controls, aria-autocomplete="list") that owns a listbox of role="group" sections labelled by their app.
- Focus stays in the input. aria-activedescendant names the active option; the first option is active after every new result list, the arrows wrap, Enter follows the active option, Escape closes and returns focus to the opener.
- The status line (role="status") gives the count, loading, no results only when every app answered, or the failure; coverage notes and Try again / Clear recent searches sit outside the listbox.
- Icons are aria-hidden; titles and breadcrumb segments are isolated in `<bdi>` for RTL; phones get a 16px input and 44px targets.

## Do / Don't

- Do: Do pass the host's verified workspace (workspaceId) and its router link.
- Don't render a product failure as no results.

## Related

- [Modal](https://design.ipmnx.com/components/modal.md)
- [Field](https://design.ipmnx.com/components/field.md)

---

Source: registry.js (NX Design System)
