Formatting & Display Guide

TanStack Hotkeys provides several utilities for formatting hotkey strings into human-readable display text. These utilities handle platform differences automatically, so your UI shows the right symbols and labels for each operating system.

formatForDisplay

The primary formatting function. Returns a platform-aware string using symbols on macOS and text labels on Windows/Linux.

tsx

import { formatForDisplay } from '@tanstack/solid-hotkeys'

// On macOS:
formatForDisplay('Mod+S')         // "⌘S"
formatForDisplay('Mod+Shift+Z')   // "⇧⌘Z"
formatForDisplay('Control+Alt+D') // "⌃⌥D"

// On Windows/Linux:
formatForDisplay('Mod+S')         // "Ctrl+S"
formatForDisplay('Mod+Shift+Z')   // "Ctrl+Shift+Z"
formatForDisplay('Control+Alt+D') // "Ctrl+Alt+D"

Options

formatForDisplay('Mod+S', {
  platform: 'mac',     // Override platform detection ('mac' | 'windows' | 'linux')
})

formatWithLabels

Returns human-readable text labels (e.g., "Cmd" instead of the symbol).

tsx

import { formatWithLabels } from '@tanstack/solid-hotkeys'

formatWithLabels('Mod+S')         // "Cmd+S" (Mac) / "Ctrl+S" (Windows)
formatWithLabels('Mod+Shift+Z')   // "Cmd+Shift+Z" (Mac) / "Ctrl+Shift+Z" (Windows)

formatKeyForDebuggingDisplay

Returns a rich label for devtools and debugging.

tsx

import { formatKeyForDebuggingDisplay } from '@tanstack/solid-hotkeys'

formatKeyForDebuggingDisplay('Meta')    // "⌘ Mod (Cmd)" (Mac)
formatKeyForDebuggingDisplay('Shift')   // "⇧ Shift"
formatKeyForDebuggingDisplay('Control') // "⌃ Control"

Using Formatted Hotkeys in Solid

Keyboard Shortcut Badges

tsx

import { formatForDisplay } from '@tanstack/solid-hotkeys'

function ShortcutBadge(props: { hotkey: string }) {
  return <kbd class="shortcut-badge">{formatForDisplay(props.hotkey)}</kbd>
}

tsx

import { createHotkey, formatForDisplay } from '@tanstack/solid-hotkeys'

function MenuItem(props: {
  label: string
  hotkey: string
  onAction: () => void
}) {
  createHotkey(props.hotkey, () => props.onAction())

  return (
    <div class="menu-item">
      <span>{props.label}</span>
      <span class="menu-shortcut">{formatForDisplay(props.hotkey)}</span>
    </div>
  )
}

Command Palette Items

tsx

import { formatForDisplay } from '@tanstack/solid-hotkeys'
import type { Hotkey } from '@tanstack/solid-hotkeys'

interface Command {
  id: string
  label: string
  hotkey?: Hotkey
  action: () => void
}

function CommandPaletteItem(props: { command: Command }) {
  return (
    <div class="command-item" onClick={props.command.action}>
      <span>{props.command.label}</span>
      <Show when={props.command.hotkey}>
        <kbd>{formatForDisplay(props.command.hotkey!)}</kbd>
      </Show>
    </div>
  )
}

Platform Symbols Reference

Modifier	Mac Symbol	Windows/Linux Label
Meta (Cmd)	⌘	Win / Super
Control	⌃	Ctrl
Alt/Option	⌥	Alt
Shift	⇧	Shift

Parsing and Normalization

parseHotkey

import { parseHotkey } from '@tanstack/solid-hotkeys'

const parsed = parseHotkey('Mod+Shift+S')
// { key: 'S', ctrl: false, shift: true, alt: false, meta: true, modifiers: [...] }

normalizeHotkey

import { normalizeHotkey } from '@tanstack/solid-hotkeys'

normalizeHotkey('Cmd+S')          // 'Meta+S' (on Mac)
normalizeHotkey('Ctrl+Shift+s')   // 'Control+Shift+S'

Validation

import { validateHotkey } from '@tanstack/solid-hotkeys'

const result = validateHotkey('Alt+A')
// { valid: true, warnings: [...], errors: [] }

const result2 = validateHotkey('InvalidKey+S')
// { valid: false, warnings: [], errors: ['Unknown key: InvalidKey'] }