basecoat/docs/src/components/command.njk

---
layout: layouts/page.njk
title: Command
description: Fast, composable command menu for quick navigation and actions.
toc:
  - label: Usage
    id: usage
  - label: Examples
    id: examples
    children:
      - label: Dialog
        id: example-dialog
---

{% from "macros/code_preview.njk" import code_preview %}
{% from "macros/code_block.njk" import code_block %}
{% from "command.njk" import command, command_dialog %}

{% macro command_items(suggestions_id="suggestions", settings_id="settings") %}
<div role="group" aria-labelledby="{{ suggestions_id }}">
  <span role="heading" id="{{ suggestions_id }}">Suggestions</span>
  <div role="option" data-value="calendar" onclick="this.closest('dialog').close()">
    {% lucide "calendar" %}
    <span>Calendar</span>
  </div>
  <div role="option" data-value="search-emoji" onclick="this.closest('dialog').close()">
    {% lucide "smile" %}
    <span>Search Emoji</span>
  </div>
  <div role="option" data-value="calculator" aria-disabled="true">
    {% lucide "calculator" %}
    <span>Calculator</span>
  </div>
</div>
<hr role="separator" />
<div role="group" aria-labelledby="{{ settings_id }}">
  <span role="heading" id="{{ settings_id }}">Settings</span>
  <div role="option" data-value="profile" onclick="this.closest('dialog').close()">
    {% lucide "user" %}
    <span>Profile</span>
    <kbd class="ml-auto text-muted-foreground bg-transparent tracking-widest">⌘P</kbd>
  </div>
  <div role="option" data-value="billing" onclick="this.closest('dialog').close()">
    {% lucide "credit-card" %}
    <span>Billing</span>
    <kbd class="ml-auto text-muted-foreground bg-transparent tracking-widest">⌘B</kbd>
  </div>
  <div role="option" data-value="settings" onclick="this.closest('dialog').close()">
    {% lucide "settings" %}
    <span>Settings</span>
    <kbd class="ml-auto text-muted-foreground bg-transparent tracking-widest">⌘S</kbd>
  </div>
</div>
{% endmacro %}

{% set code_standalone %}
{% call command(
  id="demo-command-standalone",
  main_attrs={ "class": "rounded-lg border shadow-md" }
) %}
{{ command_items("suggestions", "settings") }}
{% endcall %}
{% endset %}

{{ code_preview("command-standalone", code_standalone | prettyHtml, class=" w-full max-w-[450px]") }}

<h2 id="usage"><a href="#usage">Usage</a></h2>

{{ code_block(code_standalone | prettyHtml, "html") }}

<h2 id="examples"><a href="#examples">Examples</a></h2>

<h3 id="example-dialog"><a href="#example-dialog">Dialog</a></h3>

<section class="prose">
  <p>Press <kbd>⌘</kbd><kbd>J</kbd></p>
</section>

{% set code_dialog %}
<button
  type="button"
  class="btn-outline"
  onclick="document.getElementById('demo-command-dialog').showModal()"
>
  Open command menu
  <kbd>⌘ J</kbd>
</button>

{% call command_dialog(id="demo-command-dialog") %}
{{ command_items("cmd-suggestions", "cmd-settings") }}
{% endcall %}

<script>
  document.addEventListener('keydown', (e) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'j') {
      e.preventDefault();
      const dialog = document.getElementById('demo-command-dialog');
      if (dialog.open) {
        dialog.close();
      } else {
        dialog.showModal();
        dialog.querySelector('header input')?.focus();
      }
    }
  });

  const cmdDialog = document.getElementById('demo-command-dialog');
  cmdDialog?.addEventListener('command:select', (e) => {
    console.log('Selected command:', e.detail.value);
    cmdDialog.close();
  });
</script>
{% endset %}

{{ code_preview("command-dialog", code_dialog | prettyHtml) }}

<section class="prose">
  <p>To show the command menu in a dialog, use the <code>command_dialog</code> macro.</p>
</section>

{{ code_block(code_dialog | prettyHtml, "html") }}