Command

Command provides a keyboard-accessible command palette for quick actions and navigation. The free version supports local/static commands, filtering, grouping, keyboard navigation, and selection events.

Overview

The Command component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

This component provides a reusable, accessible primitive for command use cases within the Byteion design system.

Mental model

Think of this component as a building block. Compose it with other Byteion primitives to build complex interfaces.

When to use

Use this component when you need a standardized, accessible UI element for its intended purpose.

When not to use

Avoid using this component when a simpler native HTML element would suffice.

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { useState } from 'react';
import { Command, type CommandItem } from '@byteion/react';

const items: CommandItem[] = [
  { id: 'new-file', label: 'New file', description: 'Create a blank document' },
  { id: 'invite', label: 'Invite teammate', description: 'Send a workspace invitation' },
  { id: 'theme', label: 'Toggle theme', description: 'Switch between light and dark mode' },
  { id: 'settings', label: 'Open settings', description: 'Manage workspace preferences' },
];

export default function CommandDemo() {
  const [selected, setSelected] = useState('');

  return (
    <div className="w-full max-w-lg p-6">
      <Command
        items={items}
        triggerLabel="Open command"
        placeholder="Search commands..."
        onSelect={(item) => setSelected(item.label)}
      />
      {selected ? (
        <p className="mt-4 text-sm text-muted-foreground">Selected: {selected}</p>
      ) : null}
    </div>
  );
}

<script setup lang="ts">
import { ref } from 'vue';
import { Command, type CommandItem } from '@byteion/vue';

const selected = ref('');

const items: CommandItem[] = [
  { id: 'new-file', label: 'New file', description: 'Create a blank document' },
  { id: 'invite', label: 'Invite teammate', description: 'Send a workspace invitation' },
  { id: 'theme', label: 'Toggle theme', description: 'Switch between light and dark mode' },
  { id: 'settings', label: 'Open settings', description: 'Manage workspace preferences' },
];
</script>

<template>
  <div class="w-full max-w-lg p-6">
    <Command
      :items="items"
      trigger-label="Open command"
      placeholder="Search commands..."
      @select="(item) => { selected = item.label }"
    />
    <p v-if="selected" class="mt-4 text-sm text-muted-foreground">
      Selected: {{ selected }}
    </p>
  </div>
</template>

Variants

Each variant communicates a different meaning. Choose based on priority, not aesthetics.

Single default variant.

Sizes

Size should match the importance and context of the component.

md — md size.

States

This component reacts seamlessly to the following interaction and data states:

closed — Component is collapsed or hidden.
open — Component is expanded or visible.
empty — empty state.

Anatomy

This component is a single self-contained element. Compose it with other Byteion primitives for complex layouts.

Usage guidelines

Follow the design system tokens.
Maintain consistent spacing.

Do and Don't

Do

Follow accessibility guidelines.
Maintain visual hierarchy.

Don't

Do not hardcode colors.
Do not nest interactive elements.

Accessibility

This component follows standard ARIA patterns for its role. Keyboard interaction matches the native HTML element behavior.

Role:dialog listbox combobox

ARIA Attributes

aria-haspopup
aria-expanded
aria-controls
aria-modal
aria-labelledby
aria-activedescendant

Keyboard Navigation

Ctrl+K
Cmd+K
Escape
ArrowDown
ArrowUp
Home
End
Enter

Customization

Override visual appearance by modifying variables.css or Tailwind utility classes.

Compose with React cva()

Use the exportedcva() +cn() utilities to compose your own variant on top of the Byteion tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myCommand = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myCommand>;

Compose with Vue cva()

Use the exportedcva() +cn() utilities inside standard Vue setup blocks.

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myCommand = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myCommand({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

HTML / JS events

bi:command:search
bi:command:select
byteion:command-select

React callbacks

onOpenChange(open: boolean) => void
onSelect(item: CommandItem) => void

Vue emits

update:open[open: boolean]
select[item: CommandItem]

Remote / AJAX

This component does not implement Byteion JS remote loading. Use normal HTML form submission, framework state, or your application data layer around it.

API Reference

No custom data attributes required. Uses standard HTML attributes.

HTML Data Attributes

No custom data attributes required.

React Props · CommandProps

Extracted directly fromreact/src/components/Command.tsx.

export interface CommandProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
  items?: CommandItem[];
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  onSelect?: (item: CommandItem) => void;
  placeholder?: string;
  shortcut?: boolean;
  emptyText?: string;
  disabled?: boolean;
  triggerLabel?: string;
}

Vue Props · CommandProps

Extracted directly fromvue/src/components/Command.vue.

export interface CommandProps {
  items?: CommandItem[];
  open?: boolean;
  defaultOpen?: boolean;
  placeholder?: string;
  shortcut?: boolean;
  emptyText?: string;
  disabled?: boolean;
  triggerLabel?: string;
}

Developer tips

Best practice: Always compose this component with Byteion primitives for consistent theming.

Common mistakes

Avoid hardcoded neutral colors, placeholder-only labels, duplicated primary actions, and missing keyboard states. Keep this component on Byteion tokens so dashboard, admin, POS, ERP, ecommerce back-office, Laravel, React, and Vue starter-kit screens can be rebranded without rewriting markup.

Production usage tips

Use the canonical HTML as the source of truth, keep React and Vue wrappers aligned with the documented variants, test dark mode and branded themes before release, and wire interactive behavior through data-bi-* attributes instead of styling hooks.

Premium examples

Advanced patterns available in Byteion Pro:

Advanced patterns available in Pro include enhanced animations and integration with data layers.

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced data-tables built with this component.

Explore Pro Components