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

Options to open, copy, paste, or show a URL in a toastGrouped options

Copy

Copied

{
  "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/"
        }
      }
    ]
  }
}

Copy

Copied

{
  "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.

Copy

Copied

{
  "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).

List view with groups in a custom orderList view with custom titles for groups

Copy

Copied

{
  "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/"
        }
      }
    ]
  }
}

Copy

Copied

{
  "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/"
        }
      }
    ]
  }
}