MagicCommand

MagicCommand is a flexible collection of components intended to build command palette style menus, such as Spotlight, Raycast and the like.

Preview

or press ⌘+K / ⌃+K

Code

<template>
  <magic-command-provider id="magic-command-demo" class="flex flex-col gap-6">
    <magic-command-trigger view-id="initial-default-view" as-child>
      <m-button>Open Menu</m-button>
    </magic-command-trigger>

    <div class="type-surface-body-sm text-surface-subtle">
      <span>or press ⌘+K / ⌃+K</span>
    </div>

    <magic-command-modal :options="{ focusTrap: false }">
      <m-menu-box class="h-[30rem] w-[40rem]">
        <magic-command-renderer />
      </m-menu-box>
    </magic-command-modal>

    <default-view id="initial-default-view" />
  </magic-command-provider>
</template>

<script lang="ts" setup>
import { MButton, MMenuBox } from '@maas/mirror/vue'
import DefaultView from './components/DefaultView.vue'
</script>

Overview

• Overview
• Anatomy
• Installation
• Peer Dependencies
• API Reference
• Examples

Anatomy

<template>
  <magic-command-provider id="your-command-id">
    <!-- modal -->
    <magic-command-modal>
      <magic-command-renderer />
    </magic-command-modal>

    <!-- drawer -->
    <magic-command-drawer>
      <magic-command-renderer />
    </magic-command-drawer>

    <!-- initial view -->
    <magic-command-view :initial="true" id="your-view-id">
      <magic-command-trigger>Open Menu</magic-command-trigger>

      <magic-command-content>
        <magic-command-item>
          <!-- your content -->
        </magic-command-item>

        <!-- nested view -->
        <magic-command-item>
          <magic-command-view>
            <magic-command-trigger>Open View</magic-command-trigger>
            <magic-command-content>
              <!-- your content -->
            </magic-command-content>
          </magic-command-view>
        </magic-command-item>
      </magic-command-content>
    </magic-command-view>

    <!-- optional -->
    <magic-command-trigger view-id="your-view-id">
      Open Menu
    </magic-command-trigger>
  </magic-command-provider>
</template>

<script setup>
const { open, close } = useMagicCommand('your-command-id')
</script>

Installation

CLI

Add @maas/vue-equipment to your dependencies.

pnpm

pnpm install @maas/vue-equipment

npm

npm install @maas/vue-equipment

yarn

yarn add @maas/vue-equipment

bun

bun install @maas/vue-equipment

Vue

If you are using Vue, import and add MagicCommandPlugin to your app.

import { createApp } from 'vue'
import { MagicCommandPlugin } from '@maas/vue-equipment/plugins'

const app = createApp({})

app.use(MagicCommandPlugin)

Nuxt

The command palette is available as a Nuxt module. In your Nuxt config file add @maas/vue-equipment/nuxt to your modules and add MagicCommand to the plugins in your configuration.

export default defineNuxtConfig({
  modules: ['@maas/vue-equipment/nuxt'],
  vueEquipment: {
    plugins: ['MagicCommand'],
  },
})

Composable

In order to interact with the command palette from anywhere within your app, we provide a useMagicCommand composable. Import it directly when needed.

import { useMagicCommand } from '@maas/vue-equipment/plugins'

const { selectView } = useMagicCommand('your-command-id')

function handleClick() {
  selectView('your-view-id')
}

TIP

If you have installed the command palette as a Nuxt module, the composable will be auto-imported and is automatically available in your Nuxt app.

Peer Dependencies

If you haven’t installed the required peer dependencies automatically, you’ll need to install the following packages manually.

Package
@nuxt/kit
@maas/vue-primitive
@vueuse/core
defu

Installation

pnpm

pnpm install @nuxt/kit @maas/vue-primitive @vueuse/core defu

npm

npm install @nuxt/kit @maas/vue-primitive @vueuse/core defu

yarn

yarn add @nuxt/kit @maas/vue-primitive @vueuse/core defu

bun

bun install @nuxt/kit @maas/vue-primitive @vueuse/core defu

API Reference

MagicCommandProvider

The MagicCommandProvider wraps the command palette and configures all child components according to the provided options.

Props

Prop	Type	Required
id	MaybeRef<string>	true
asChild	boolean	false
options	MagicMenuOptions	false

Options

To customize the command palette, override the necessary options. Any custom options will be merged with the default options.

Option	Type	Default
debug	boolean	false
transition.content	string	magic-command-content
keyListener.open	string[] | false	['Cmd+k', 'Ctrl+k']
keyListener.close	string[] | false	['Escape']
keyListener.next	string[] | false	['ArrowDown']
keyListener.prev	string[] | false	['ArrowUp']
keyListener.enter	string[] | false	['Enter']
loop	boolean	false

MagicCommandView

Props

Prop	Type	Required
id	MaybeRef<string>	false
initial	boolean	false

MagicCommandDrawer

Props

Prop	Type	Required
Options	MagicCommandDrawerOptions	false

MagicCommandModal

Props

Prop	Type	Required
Options	MagicCommandModalOptions	false

MagicCommandRenderer

CSS Variables

Variable	Default
--magic-command-renderer-width	100%
--magic-command-renderer-height	100%

MagicCommandItem

Props

Prop	Type	Required
id	string	false
disabled	boolean	false

CSS Variables

Variable	Default
--magic-command-item-cursor	default

MagicCommandTrigger

Props

Prop	Type	Required
viewId	string	false
disabled	boolean	false
active	boolean	false
trigger	Interaction[]	false
Action	Action	false
asChild	boolean	false

Variable	Default
--magic-command-trigger-cursor	pointer

CSS Variables

Variable	Default
--magic-command-trigger-cursor	pointer

Examples

Modal

Preview

Code

<template>
  <magic-command-provider
    id="magic-command-modal-demo"
    :options="{ keyListener: { open: false } }"
  >
    <magic-command-trigger view-id="initial-modal-view" as-child>
      <m-button>Open Menu</m-button>
    </magic-command-trigger>

    <magic-command-modal :options="{ focusTrap: false }">
      <m-menu-box class="h-[30rem] w-[40rem]">
        <magic-command-renderer />
      </m-menu-box>
    </magic-command-modal>

    <default-view id="initial-modal-view" />
  </magic-command-provider>
</template>

<script lang="ts" setup>
import { MButton, MMenuBox } from '@maas/mirror/vue'
import DefaultView from './components/DefaultView.vue'
</script>

Drawer

Preview

Code

<template>
  <magic-command-provider
    id="magic-command-drawer-demo"
    :options="{ keyListener: { open: false } }"
  >
    <magic-command-trigger view-id="initial-drawer-view" as-child>
      <m-button>Open Menu</m-button>
    </magic-command-trigger>

    <magic-command-drawer :options="{ focusTrap: false }">
      <div
        class="h-full w-full p-2 pb-[calc(var(--magic-drawer-drag-overshoot)+0.5rem)]"
      >
        <m-menu-box class="h-full w-full">
          <magic-command-renderer />
        </m-menu-box>
      </div>
    </magic-command-drawer>

    <default-view id="initial-drawer-view" />
  </magic-command-provider>
</template>

<script lang="ts" setup>
import { MButton, MMenuBox } from '@maas/mirror/vue'
import DefaultView from './components/DefaultView.vue'
</script>

<style>
[data-id='magic-command-drawer-demo'] {
  --magic-drawer-width: 40rem;
  --magic-drawer-height: 30rem;
}
</style>