command_palette 0.7.6 copy "command_palette: ^0.7.6" to clipboard
command_palette: ^0.7.6 copied to clipboard

Flutter implementation of a Command Palette. Can be brought up via a keyboard shortcut.

command_palette #

pub package flutter_tests codecov style: flutter lints License: MIT
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.

A gif showing a demo of the command palette. Showcasing filtering, sub-options, and text highlighting

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.

20
likes
150
pub points
67%
popularity

Publisher

verified publishertylernorbury.com

Flutter implementation of a Command Palette. Can be brought up via a keyboard shortcut.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (license)

Dependencies

flutter, substring_highlight, woozy_search

More

Packages that depend on command_palette