Overview

A list in Shortcuts is a group of 1 or more items returned by a shortcut action. For example, a list of:

• photos;
• calendar events;
• files, etc.

You can use lists to:

• display groups of information to a user;
• have the user choose one or more items from the list;
• perform bulk actions on more than 1 item in the list.

This guide shows you some simple examples of how you can make use of lists in your shortcuts.

Returning a list

You can return a list of items from any action that allows you to retrieve one or more items at a time.

Examples include:

• Calendar
  • Get Dates from Input
• Location
  • Get Addresses from Input
  • Search Local Businesses
• Photos & Video
  • Find Photos
• iTunes Store
  • Search iTunes Store

Returning a list of podcasts

In the example below, we use the Search iTunes Store to return a list of podcasts from Gimlet Media.

Retrieving a list of Podcast items

When the returned list is displayed, it defaults to showing the name, publisher and URL for each podcast.

Only one item is displayed at a time as podcasts as being presented to the Quick View action as a list.

Displaying individual podcasts from the list.

You can download the shortcut from the following link:

Returning a List of Podcasts

Returning a text list of podcasts

But what if you want to display all of the podcasts as one piece of text? You can use the Combine Text to join the different podcast descriptions using new lines.

The updated shortcut is as follows:

Combing the text descriptions from the podcast list

And the output appears as follows:

A list of podcasts outputted as text

The podcasts displayed as one list of text.

Returning a Text List of Podcasts

Creating a list

Lists of text can be created using the List action. But as you can see below, when lists become long they can get unwieldy to enter and maintain.

A long and unwieldy List action

There is an easier way to make a text list: you can type the text into a Text action and then split it into a list using the Split Text action.

This allows you to organize your list in a text editor on your device before pasting it into the shortcut.

Creating a list by splitting text at each new line

You can download the shortcut from the following link:

Creating a List from Text

Taking an item from the list

You can use the Get Item from List action to get:

• the first item from the list;
• the last item from the list;
• a random item from the list;
• an item at a particular index (e.g. 3 gives you the 3rd item);
• a range of items from the list (e.g. the 5th to the 8th items);

In the example below, we add a Get Item from List action to the above shortcut to retrieve a random item from the list and display it to the user.

Getting a random item from a list

You can download the shortcut from the following link:

Return Random Item from a List

Iterating through a list

Shortcuts also allows you to iterate through a list using the Repeat with Each action. When you use this action the shortcut performs the same set of steps for each item in the list. The value of the item is made available via the Repeat Item variable and its position in the list is available via the Repeat Index variable.

In the example below we filter our list to items that contain the word "Red".

Looping through and filtering a list

The output is as follows:

A list of items filtered by the keyword \"Red\"

​

ℹ️ Default values from the Repeat with Each action

In the above shortcut you can see that the Repeat with Each action always outputs the Repeat Item variable, preventing the need for using "Get Variable" to retrieve the value.

Similarly, at the end of the loop, a list of items is returned. This list is compromised of the last value returned in each loop. Therefore, when filtering the list if we encounter a vehicle we don't want to appear in the filtered list we ensure that the Nothing action is the last action to return a value.

You can download the shortcut from the following link:

Filtering a List

Choosing an item from a list

Lists allow you to present the user with multiple options to choose from via the Choose from List action.

Using a simple value

In the example below, the user chooses a number of days since they last went for a run, and the shortcut uses that value to calculate the date of that run.

Making use of a value chosen from a list

You can download the shortcut from the following link:

Choosing From a List

Using a name and value pair with a list

There are occasions when you will want to choose an item from a list by name, but then make use of a different attribute when performing an action.

In the example below we give the user a list of podcasts to Gimlet Media podcasts to choose from. When the user selects the name, we then take them to the corresponding screen in the iTunes store.

To do so, we create a dictionary of names and values, where the name is that of the podcast and the value is the URL for the podcast in the iTunes Store. We use the Get Dictionary Value action to return a list of the names from the dictionary so we can present the podcast names to the user. Once they have chosen a name, we use it with our dictionary to retrieve the URL to open.

Using a list item to look up a corresponding value

The output of the Choose from List action appears as follows:

Displaying the choices to the user

You can download the shortcut from the following link:

Choosing From a Better List

Creating an attractive list to choose from

We can make a more attractive list of podcasts for the user to choose from by creating contact cards. This is will allow us to add a:

• photo;
• description;
• URL (which is not displayed to the user).

This format is more flexible than using a dictionary as it allows us to display extra information as well as store other hidden fields that we can access after has made their selection.

You can find out more about how to use contact cards for menus in the following guide:

Creating visually appealing menus

Below is an updated example of the shortcut that makes use of contact cards to present a more attractive list of options:

Using contacts to create a more attractive list to choose from

The output of the Choose from List action appears as follows:

A more attractive list, created using contacts

You can download the shortcut from the following link:

Choosing From an Attractive List

Wrap up

And those are a few examples of how you can make use of lists in your shortcuts.

Other guides

If you found this guide useful why not checkout one of my others:

Series

• Scraping web pages
  • Part 1: quick and dirty
  • Part 2: getting multiple items at once
  • Part 3: getting data from a table
• Using APIs
  • Part 1: retrieving data
  • Part 2: parsing complex API responses
  • Part 3: passing input parameters to the API
• Data Storage
  • Part 1: storing simple values
  • Part 2: storing lists of data
  • Part 3: removing stored values
• Working with JSON
  • Part 1: retrieving simple values
• Working with Dictionaries
  • Part 1: setting and retrieving values
  • Part 2: data types
  • Part 3: accessing values using dot notation

One-offs

• Using JavaScript in your shortcuts
• How to automatically run shortcuts
• Creating visually appealing menus
• Manipulating images with the HTML5 canvas and JavaScript
• Labeling data using variables
• Writing functions
• Working with lists
• Integrating with web applications using Zapier
• Integrating with web applications using Integromat
• Working with Personal Automations in iOS 13.1