CommandPalette class

A searchable, grouped list displayed in a modal overlay.

Modeled after VS Code's command palette / Ctrl+P picker. Supports:

  • Bayesian scoring with match types (exact > prefix > word-start > substring > fuzzy)
  • Incremental scoring for query-as-you-type performance
  • Conformal rank confidence (stable/marginal/unstable)
  • Searchable tags that boost match scores
  • Grouped items with section headers
  • Keyboard navigation (up/down arrows, enter to select, esc to dismiss)
  • Mouse click selection
  • Fully themeable via CommandPaletteThemeData
CommandPalette(
  open: _showPalette,
  title: 'Commands',
  items: [
    CommandPaletteItem(label: 'Open File', shortcut: 'ctrl+o', group: 'File', tags: ['open', 'load']),
    CommandPaletteItem(label: 'Save', shortcut: 'ctrl+s', group: 'File', tags: ['write', 'persist']),
    CommandPaletteItem(label: 'Find', shortcut: 'ctrl+f', group: 'Edit', tags: ['search']),
  ],
  onDismiss: () { setState(() => _showPalette = false); return null; },
  child: myAppContent,
)
Inheritance

Constructors

CommandPalette({required Widget child, required List<CommandPaletteItem> items, bool open = false, String? title, String? hint, CmdCallback? onDismiss, ValueCmdCallback<CommandPaletteItem>? onSelect, Color? background, Color? selectedBackground, Color? selectedForeground, Border? border, Color? borderColor, int? width, int? maxHeight, double backdropOpacity = 0.6, Key? key})

Properties

accessibilityLabel → String?
Optional accessibility label.
no setterinherited
accessibilityRole → String
Optional accessibility role.
no setterinherited
backdropOpacity → double
Opacity used to dim the background while open.
final
background → Color?
Background color override.
final
border → Border?
Border style override.
final
borderColor → Color?
Border color override.
final
child → Widget
Background content shown behind the palette.
final
children → List<Widget>
Child widgets that receive forwarded messages.
no setterinherited
debugRenderObjectPassthrough → bool
Whether this widget is intentionally transparent to render-object layouts.
no setterinherited
degradationSignal → WidgetDegradationSignal
Signal that controls this widget's render budget behavior.
no setterinherited
focusable → bool
Whether this widget can receive keyboard focus.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
hint → String?
Placeholder hint text for the search input.
final
id → String
Unique identifier for this widget.
no setterinherited
items → List<CommandPaletteItem>
Available items to display and filter.
final
key → Key?
Key for preserving widget identity.
finalinherited
maxHeight → int?
Maximum height of the palette in rows.
final
onDismiss → CmdCallback?
Called when the palette should be dismissed (esc key or backdrop tap).
final
onSelect → ValueCmdCallback<CommandPaletteItem>?
Called when an item is selected. Receives the selected item.
final
open → bool
Whether the palette is visible.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
selectedBackground → Color?
Background color for the selected item.
final
selectedForeground → Color?
Foreground color for the selected item.
final
theme → Theme
Access the current theme.
no setterinherited
title → String?
Optional title shown at the top of the palette.
final
width → int?
Width of the palette in columns.
final

Methods

buildCachedView<T>(T builder(), Object? cacheKey) → T
Returns a cached view if the cache key matches.
inherited
createState() → State<CommandPalette>
Creates the mutable State associated with this widget.
override
handleInit() → Cmd?
Override this instead of init for widget-specific initialization.
inherited
handleIntercept(Msg msg) → (Widget, Cmd?)
Override this to handle messages before they reach children.
inherited
handleUpdate(Msg msg) → (Widget, Cmd?)
Override this to handle messages specific to this widget.
inherited
init() → Cmd?
Called once when the widget is first mounted.
inherited
invalidateCachedView() → void
Clears any cached view for this widget.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
shouldRenderAt(DegradationLevel degradationLevel, {required bool subtreeHasFocusedWidget}) → bool
Whether this widget should participate in the current render when degradationLevel is active.
inherited
toString() → String
A string representation of this object.
inherited
update(Msg msg) → (Model, Cmd?)
Handles messages by forwarding to children then calling handleUpdate.
inherited
view() → Object
Renders the widget to a string or View.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

matchItems(List<CommandPaletteItem> items, String query) → List<CommandPaletteMatch>
Returns ranked matches for query with deterministic scoring and explainable evidence.