List View

Use a List view to display a list of options to the user when they run a command.

Parameters

The following parameters are used in a List view

type: Defines the type of view. For list view: "List".
options: An array of ListOption objects.
groups: Optional. An array of Group objects (or strings). Can be used to define the order in which they appear and customize how they are displayed.
ranking: Optional. The default value is true, i.e the default ranking will be used. If you wish to return different options as the user types in the Command Bar, set ranking to false. Your command will run with a special parameter keywords that you can use to decide what options to return back.

Examples

{
  "view": {
    "type": "list",
    "options": [
      {
        "title": "Open Google",
        "action": {
          "type": "open-url",
          "url": "https://www.google.com/"
        }
      },
      {
        "title": "Copy Google URL",
        "action": {
          "type": "copy",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Paste Google URL",
        "action": {
          "type": "paste",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Show Google URL",
        "action": {
          "type": "show-toast",
          "message": "https://www.google.com/"
        }
      }
    ]
  }
}

{
  "view": {
    "type": "list",
    "groups": ["Clipboard", "Browser", "Misc"],
    "options": [
      {
        "title": "Open Google",
        "group": "Browser",
        "action": {
          "type": "open-url",
          "url": "https://www.google.com/"
        }
      },
      {
        "title": "Copy Google URL",
        "group": "Clipboard",
        "action": {
          "type": "copy",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Paste Google URL",
        "group": "Clipboard",
        "action": {
          "type": "paste",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Show Google URL",
        "group": "Misc",
        "action": {
          "type": "show-toast",
          "message": "https://www.google.com/"
        }
      }
    ]
  }
}

ListOption Objects

ListOption objects define the options that are displayed in the List View.

Parameters include:

title: The title of the option.
action: Add an Action when the user presses enter or clicks on the option.
moveAction: Optional. Add an Action when the user presses tab on the option.
icon: Optional. Set an icon for the option.
subtitle: Optional. Display a subtitle for the option.
group: Optional. Add the option to a specific group.

{
  "view": {
    "type": "list",
    "options": [
      {
        "title": "Copy Home Number",
        "subtitle": [
          "Mobile",
          "Emergencies"
        ],
        "group": "Phone Numbers",
        "icon": "🏠",
        "action": {
          "type": "copy",
          "value": "+44123456789"
        }
      },
      {
        "title": "Copy Work Number",
        "subtitle": [
          "Stationary",
          "9-5"
        ],
        "group": "Phone Numbers",
        "icon": "💼",
        "action": {
          "type": "copy",
          "value": "+44987654321"
        }
      }
    ]
  }
}

Group objects

Display options in the List View in groups.

Each Group can be a string or an object. Provide Group as an object if you want to customize its appearance (e.g. change its title).

{
  "view": {
    "type": "list",
    "groups": [
      "misc",
      "browser",
      "clipboard"
    ],
    "options": [
      {
        "title": "Open Google",
        "group": "browser",
        "action": {
          "type": "open-url",
          "url": "https://www.google.com/"
        }
      },
      {
        "title": "Copy Google URL",
        "group": "clipboard",
        "action": {
          "type": "copy",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Paste Google URL",
        "group": "clipboard",
        "action": {
          "type": "paste",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Show Google URL",
        "group": "misc",
        "action": {
          "type": "show-toast",
          "message": "https://www.google.com/"
        }
      }
    ]
  }
}

{
  "view": {
    "type": "list",
    "groups": [
      {
        "id": "misc",
        "title": "Miscellaneous"
      },
      "browser",
      "clipboard"
    ],
    "options": [
      {
        "title": "Open Google",
        "group": "browser",
        "action": {
          "type": "open-url",
          "url": "https://www.google.com/"
        }
      },
      {
        "title": "Copy Google URL",
        "group": "clipboard",
        "action": {
          "type": "copy",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Paste Google URL",
        "group": "clipboard",
        "action": {
          "type": "paste",
          "value": "https://www.google.com/"
        }
      },
      {
        "title": "Show Google URL",
        "group": "misc",
        "action": {
          "type": "show-toast",
          "message": "https://www.google.com/"
        }
      }
    ]
  }
}