command_palette

A Flutter widget that allows you to bring up a command palette, seen in programs like Visual Studio Code and Slack. Allowing you to provide users with a convenient way to perform all sorts of actions related to your app.

Features

Access the command palette via a keyboard shortcut, or programmatically.
Define a custom list of actions for the user and define the callbacks for each.
Use the default styling or build your own custom list items.
Use your own filtering logic
Use throughout your entire app, or just in certain sections!
Support for keyboardless apps too!

Getting started

To install run the following command:

flutter pub install command_palette

or add command_palette to your pubspec.yaml

Usage

Start by placing the Command Palette widget in your widget tree:

import 'package:command_palette/command_palette.dart';

//...
CommandPalette(
  actions: [
    CommandPaletteAction(
      label: "Goto Home Page",
      actionType: CommandPaletteActionType.single,
      onSelect: () {
        // go to home page, or perform some other sorta action
      }
    ),
    CommandPaletteAction(
      id: "change-theme",
      label: "Change Theme",
      actionType: CommandPaletteActionType.nested,
      description: "Change the color theme of the app",
      shortcut: ["ctrl", "t"],
      childrenActions: [
        CommandPaletteAction(
          label: "Light",
          actionType: CommandPaletteActionType.single,
          onSelect: () {
            setState(() {
              themeMode = ThemeMode.light;
            });
          },
        ),
        CommandPaletteAction(
          label: "Dark",
          actionType: CommandPaletteActionType.single,
          onSelect: () {
            setState(() {
              themeMode = ThemeMode.dark;
            });
          },
        ),
      ],
    ),
  ],
  child: Text("Use a keyboard shortcut to open the palette up!"),
)
//...

Opening Without a Keyboard

Want to allow devices that don't have a keyboard to open the palette, just use the handy InheritedWidget!

CommandPalette.of(context).open();

Creating a custom filter

One of the configuration options is filter, which allows you to define your own custom filtering logic. The return type of this function is List<CommandPaletteAction>. With that in mind there is one thing I'd like to make you aware of before implementing your own: There is a sub class of CommandPaletteAction called MatchedCommandPaletteAction. The only difference between this sub class and it's super class is it has a list of FilterMatches, which indicates the parts of the action label (this can be any string, but it's advisable to match against the label) that were matched against some part of the query. By using this subclass with the default builder, you can get enhanced sub-string high lighting.

Opening to a nested action

To open up a nested action directly (e.g. You want to have a "Set User" button, that will open the palette with the Set User nested action already selected), you can use the following method:

CommandPalette.of(context).openToAction(actionId);

Where actionId is a value which matches the id of a CommandPaletteAction. An id can be any object, primitives work best, but if you use a custom object, be sure to override the the == operator.

Additional information

Have a feature request, or some questions? Come on down to the discussions tab.

Find a bug or want to open a pull request? Feel free to do so, any and all contributions are welcome and appreciated!

Note about the version

While I feel confident that this package is ready to use in a real world app. I'm keeping the version below 1.0.0 for the time being incase there is any major changes I'd like to make before I settle down into something.

jpnurmi / command_palette