How to Build a Command Palette (⌘K) in Flutter (Full Code + Preview)

import 'package:flutter/material.dart';

/// Console — Command Palette (⌘K).
///
/// A full-screen dim overlay with a search field and grouped, navigable
/// action/screen rows (painted leading icon tiles), per-row keyboard-hint
/// chips, and a recent-actions list. Opens over any screen in the shell.
///
/// Self-contained per CONVENTIONS.md: pure Flutter, bundled static-weight
/// Inter, own dark theme + inline tokens, `SafeArea`, overflow-proof.
/// Navigation is via callbacks only.
class ConsoleNavCommandPaletteScreen extends StatelessWidget {
  const ConsoleNavCommandPaletteScreen({
    super.key,
    this.onDismiss,
    this.onSelect,
  });

  /// Fired when the dim backdrop / close affordance is tapped.
  final VoidCallback? onDismiss;

  /// Fired with the selected command/route id.
  final ValueChanged<String>? onSelect;

  static const String _font = 'Inter';
  static const Color _scrim = Color(0xCC05070A);
  static const Color _surface = Color(0xFF14171A);
  static const Color _surfaceAlt = Color(0xFF1C2024);
  static const Color _brand = Color(0xFF635BFF);
  static const Color _muted = Color(0xFF8A929E);
  static const Color _ink = Color(0xFFF4F6F8);
  static const Color _hairline = Color(0xFF242A30);
  static const Color _selection = Color(0xFF2A2540);

  static const List<_Group> _groups = <_Group>[
    _Group('Recent', <_Cmd>[
      _Cmd('recent-users', 'Users — All active', Icons.people_alt_rounded),
      _Cmd('recent-mrr', 'Revenue — MRR breakdown', Icons.payments_rounded),
    ]),
    _Group('Navigate', <_Cmd>[
      _Cmd('overview', 'Go to Overview', Icons.grid_view_rounded, kbd: 'G O'),
      _Cmd('analytics', 'Go to Analytics', Icons.show_chart_rounded, kbd: 'G A'),
      _Cmd('events', 'Go to Events Explorer', Icons.bolt_rounded, kbd: 'G E'),
      _Cmd('settings', 'Go to Settings', Icons.settings_rounded, kbd: 'G S'),
    ]),
    _Group('Actions', <_Cmd>[
      _Cmd('new-report', 'Create report', Icons.add_chart_rounded, kbd: 'C R'),
      _Cmd('new-funnel', 'Create funnel', Icons.filter_alt_rounded),
      _Cmd('invite', 'Invite teammate', Icons.person_add_alt_rounded),
      _Cmd('export', 'Export current view', Icons.file_download_outlined),
    ]),
  ];

  @override
  Widget build(BuildContext context) {
    return Theme(
      data: ThemeData.dark(useMaterial3: true),
      child: Scaffold(
        backgroundColor: _scrim,
        body: GestureDetector(
          behavior: HitTestBehavior.opaque,
          onTap: onDismiss,
          child: SafeArea(
            child: Center(
              child: GestureDetector(
                onTap: () {},
                child: Padding(
                  padding: const EdgeInsets.all(20),
                  child: ConstrainedBox(
                    constraints: const BoxConstraints(maxWidth: 620),
                    child: _Panel(onSelect: onSelect, onDismiss: onDismiss),
                  ),
                ),
              ),
            ),
          ),
        ),
      ),
    );
  }
}

class _Panel extends StatelessWidget {
  const _Panel({this.onSelect, this.onDismiss});
  final ValueChanged<String>? onSelect;
  final VoidCallback? onDismiss;

  @override
  Widget build(BuildContext context) {
    return Container(
      decoration: BoxDecoration(
        color: ConsoleNavCommandPaletteScreen._surface,
        borderRadius: BorderRadius.circular(14),
        border: Border.all(color: ConsoleNavCommandPaletteScreen._hairline),
        boxShadow: <BoxShadow>[
          BoxShadow(
            color: Colors.black.withValues(alpha: 0.5),
            blurRadius: 40,
            offset: const Offset(0, 20),
          ),
        ],
      ),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: <Widget>[
          _SearchRow(onDismiss: onDismiss),
          const Divider(
            height: 1,
            thickness: 1,
            color: ConsoleNavCommandPaletteScreen._hairline,
          ),
          Flexible(
            child: ListView(
              shrinkWrap: true,
              padding: const EdgeInsets.symmetric(vertical: 8),
              children: <Widget>[
                for (final _Group g in ConsoleNavCommandPaletteScreen._groups)
                  ...<Widget>[
                    _GroupHeader(g.label),
                    for (int i = 0; i < g.cmds.length; i++)
                      _CmdRow(
                        cmd: g.cmds[i],
                        selected: g.label == 'Recent' && i == 0,
                        onTap: () => onSelect?.call(g.cmds[i].id),
                      ),
                  ],
              ],
            ),
          ),
          const Divider(
            height: 1,
            thickness: 1,
            color: ConsoleNavCommandPaletteScreen._hairline,
          ),
          const _FooterHints(),
        ],
      ),
    );
  }
}

class _SearchRow extends StatelessWidget {
  const _SearchRow({this.onDismiss});
  final VoidCallback? onDismiss;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.fromLTRB(16, 14, 12, 14),
      child: Row(
        children: <Widget>[
          const Icon(
            Icons.search_rounded,
            size: 20,
            color: ConsoleNavCommandPaletteScreen._muted,
          ),
          const SizedBox(width: 12),
          const Expanded(
            child: Text(
              'Type a command or search…',
              style: TextStyle(
                fontFamily: ConsoleNavCommandPaletteScreen._font,
                fontSize: 15,
                fontWeight: FontWeight.w400,
                color: ConsoleNavCommandPaletteScreen._muted,
              ),
            ),
          ),
          InkWell(
            onTap: onDismiss,
            borderRadius: BorderRadius.circular(6),
            child: const _KbdChip('ESC'),
          ),
        ],
      ),
    );
  }
}

class _GroupHeader extends StatelessWidget {
  const _GroupHeader(this.text);
  final String text;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.fromLTRB(16, 10, 16, 6),
      child: Text(
        text.toUpperCase(),
        style: const TextStyle(
          fontFamily: ConsoleNavCommandPaletteScreen._font,
          fontSize: 10.5,
          fontWeight: FontWeight.w600,
          letterSpacing: 1.1,
          color: ConsoleNavCommandPaletteScreen._muted,
        ),
      ),
    );
  }
}

class _CmdRow extends StatelessWidget {
  const _CmdRow({required this.cmd, required this.selected, required this.onTap});
  final _Cmd cmd;
  final bool selected;
  final VoidCallback onTap;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 1),
      child: InkWell(
        borderRadius: BorderRadius.circular(9),
        onTap: onTap,
        child: Container(
          height: 46,
          padding: const EdgeInsets.symmetric(horizontal: 10),
          decoration: BoxDecoration(
            color: selected
                ? ConsoleNavCommandPaletteScreen._selection
                : Colors.transparent,
            borderRadius: BorderRadius.circular(9),
          ),
          child: Row(
            children: <Widget>[
              Container(
                width: 30,
                height: 30,
                decoration: BoxDecoration(
                  color: ConsoleNavCommandPaletteScreen._surfaceAlt,
                  borderRadius: BorderRadius.circular(8),
                  border: Border.all(
                    color: ConsoleNavCommandPaletteScreen._hairline,
                  ),
                ),
                child: Icon(
                  cmd.icon,
                  size: 17,
                  color: selected
                      ? ConsoleNavCommandPaletteScreen._brand
                      : ConsoleNavCommandPaletteScreen._muted,
                ),
              ),
              const SizedBox(width: 12),
              Expanded(
                child: Text(
                  cmd.label,
                  maxLines: 1,
                  overflow: TextOverflow.ellipsis,
                  style: const TextStyle(
                    fontFamily: ConsoleNavCommandPaletteScreen._font,
                    fontSize: 14,
                    fontWeight: FontWeight.w500,
                    color: ConsoleNavCommandPaletteScreen._ink,
                  ),
                ),
              ),
              if (cmd.kbd != null) _KbdChip(cmd.kbd!),
              if (selected)
                const Padding(
                  padding: EdgeInsets.only(left: 8),
                  child: Icon(
                    Icons.keyboard_return_rounded,
                    size: 16,
                    color: ConsoleNavCommandPaletteScreen._muted,
                  ),
                ),
            ],
          ),
        ),
      ),
    );
  }
}

class _FooterHints extends StatelessWidget {
  const _FooterHints();

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 11),
      child: Wrap(
        spacing: 8,
        runSpacing: 8,
        crossAxisAlignment: WrapCrossAlignment.center,
        alignment: WrapAlignment.start,
        children: const <Widget>[
          _HintCluster(keys: <String>['↑', '↓'], label: 'navigate'),
          _HintCluster(keys: <String>['↵'], label: 'select'),
          _HintCluster(keys: <String>['esc'], label: 'close'),
        ],
      ),
    );
  }
}

class _HintCluster extends StatelessWidget {
  const _HintCluster({required this.keys, required this.label});
  final List<String> keys;
  final String label;

  @override
  Widget build(BuildContext context) {
    return Row(
      mainAxisSize: MainAxisSize.min,
      children: <Widget>[
        for (int i = 0; i < keys.length; i++) ...<Widget>[
          _KbdChip(keys[i]),
          if (i != keys.length - 1) const SizedBox(width: 4),
        ],
        const SizedBox(width: 7),
        Text(
          label,
          style: const TextStyle(
            fontFamily: ConsoleNavCommandPaletteScreen._font,
            fontSize: 12,
            color: ConsoleNavCommandPaletteScreen._muted,
          ),
        ),
      ],
    );
  }
}

class _KbdChip extends StatelessWidget {
  const _KbdChip(this.text);
  final String text;

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 7, vertical: 3),
      decoration: BoxDecoration(
        color: ConsoleNavCommandPaletteScreen._surfaceAlt,
        borderRadius: BorderRadius.circular(5),
        border: Border.all(color: ConsoleNavCommandPaletteScreen._hairline),
      ),
      child: Text(
        text,
        style: const TextStyle(
          fontFamily: ConsoleNavCommandPaletteScreen._font,
          fontSize: 11,
          fontWeight: FontWeight.w600,
          color: ConsoleNavCommandPaletteScreen._muted,
        ),
      ),
    );
  }
}

class _Group {
  const _Group(this.label, this.cmds);
  final String label;
  final List<_Cmd> cmds;
}

class _Cmd {
  const _Cmd(this.id, this.label, this.icon, {this.kbd});
  final String id;
  final String label;
  final IconData icon;
  final String? kbd;
}