List
The de-facto user interface in Raycast. Ideal to present similar data such as to-dos or files.
Our List component provides great user experience out of the box:
  • Use built-in filtering for best performance.
  • Group-related items in sections with titles and subtitles.
  • Show loading indicator for longer operations.
  • Use the search query for typeahead experiences, optionally throttled.

Search Bar

The search bar allows users to interact quickly with list items. By default, List.Items are displayed if the user's input can be (fuzzy) matched to the item's title or keywords.

Custom filtering

Sometimes, you may not want to rely on Raycast's filtering, but use/implement your own. If that's the case, you can set the List's enableFiltering prop to false, and the items displayed will be independent of the search bar's text. Note that enableFiltering is also implicitly set to false if an onSearchTextChange listener is specified. If you want to specify a change listener and still take advantage of Raycast's built-in filtering, you can explicitly set enableFiltering to true.
1
import { useEffect, useState } from "react";
2
import { Action, ActionPanel, List } from "@raycast/api";
3
4
const items = [
5
"Augustiner Helles",
6
"Camden Hells",
7
"Leffe Blonde",
8
"Sierra Nevada IPA",
9
];
10
11
export default function Command() {
12
const [searchText, setSearchText] = useState("");
13
const [filteredList, filterList] = useState(items);
14
15
useEffect(() => {
16
filterList(items.filter((item) => item.includes(searchText)));
17
}, [searchText]);
18
19
return (
20
<List
21
enableFiltering={false}
22
onSearchTextChange={setSearchText}
23
navigationTitle="Search Beers"
24
searchBarPlaceholder="Search your favorite beer"
25
>
26
{filteredList.map((item) => (
27
<List.Item
28
key={item}
29
title={item}
30
actions={
31
<ActionPanel>
32
<Action
33
title="Select"
34
onAction={() => console.log(`${item} selected`)}
35
/>
36
</ActionPanel>
37
}
38
/>
39
))}
40
</List>
41
);
42
}
Copied!
Other times, you may want the content of the search bar to be updated by the extension, for example, you may store a list of the user's previous searches and, on the next visit, allow them to "continue" where they left off.
To do so, you can use the searchText prop.
1
import { useEffect, useState } from "react";
2
import { Action, ActionPanel, List } from "@raycast/api";
3
4
const items = [
5
"Augustiner Helles",
6
"Camden Hells",
7
"Leffe Blonde",
8
"Sierra Nevada IPA",
9
];
10
11
export default function Command() {
12
const [searchText, setSearchText] = useState("");
13
14
return (
15
<List
16
searchText={searchText}
17
onSearchTextChange={setSearchText}
18
navigationTitle="Search Beers"
19
searchBarPlaceholder="Search your favorite beer"
20
>
21
{items.map((item) => (
22
<List.Item
23
key={item}
24
title={item}
25
actions={
26
<ActionPanel>
27
<Action title="Select" onAction={() => setSearchText(item)} />
28
</ActionPanel>
29
}
30
/>
31
))}
32
</List>
33
);
34
}
Copied!
Some extensions may benefit from giving users a second filtering dimension. A todo extension may allow users to use different groups, a newspaper-reading extension may want to allow quickly switching categories, etc.
This is where the searchBarAccessory prop is useful. Pass it a List.Dropdown component, and it will be displayed on the right-side of the search bar. Invoke it either by using the global shortcut P or by clicking on it.

Examples

List.tsx
ListWithSections.tsx
ListWithActions.tsx
ListWithDetail.tsx
ListWithEmptyView.tsx
1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Item title="Item 1" />
7
<List.Item title="Item 2" subtitle="Optional subtitle" />
8
</List>
9
);
10
}
Copied!
1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Section title="Section 1">
7
<List.Item title="Item 1" />
8
</List.Section>
9
<List.Section title="Section 2" subtitle="Optional subtitle">
10
<List.Item title="Item 1" />
11
</List.Section>
12
</List>
13
);
14
}
Copied!
1
import { ActionPanel, Action, List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Item
7
title="Item 1"
8
actions={
9
<ActionPanel>
10
<Action.CopyToClipboard content="👋" />
11
</ActionPanel>
12
}
13
/>
14
</List>
15
);
16
}
Copied!
1
import { ActionPanel, List } from "@raycast/api";
2
import { usePokemons } from './utils'
3
4
export default function Command() {
5
const [showingDetail, setShowingDetail] = useState(true);
6
7
const pokemons = usePokemons();
8
9
return (
10
<List isLoading={!pokemons} isShowingDetail={showingDetail}>
11
{pokemons &&
12
pokemons.map((pokemon) => {
13
const props: Partial<List.Item.Props> = showingDetail
14
? {
15
detail: (
16
<List.Item.Detail
17
markdown={`![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/${
18
pokemon.id
19
}.png)\n\n${pokemon.types.join(" ")}`}
20
/>
21
),
22
}
23
: { accessories: [ { text: pokemon.types.join(" ") } ] };
24
return (
25
<List.Item
26
key={pokemon.id}
27
title={pokemon.name}
28
subtitle={`#${pokemon.id}`}
29
{...props}
30
actions={
31
<ActionPanel>
32
<Action.OpenInBrowser url={`https://www.pokemon.com/us/pokedex/${pokemon.name}`} />
33
<Action title="Toggle Detail" onAction={() => setShowingDetail(!showingDetail)} />
34
</ActionPanel>
35
}
36
/>
37
);
38
})}
39
</List>
40
}
Copied!
1
import { useState } from "react";
2
import { List } from "@raycast/api";
3
4
export default function CommandWithCustomEmptyView() {
5
const [state, setState] = useState({ searchText: "", items: [] });
6
7
useEffect(() => {
8
// perform an API call that eventually populates `items`.
9
}, [state.searchText]);
10
11
return (
12
<List
13
onSearchTextChange={(newValue) =>
14
setState((previous) => ({ ...previous, searchText: newValue }))
15
}
16
>
17
{state.searchText === "" && state.items.length === 0 ? (
18
<List.EmptyView
19
icon={{ source: "https://placekitten.com/500/500" }}
20
title="Type something to get started"
21
/>
22
) : (
23
state.items.map((item) => <List.Item key={item} title={item} />)
24
)}
25
</List>
26
);
27
}
Copied!

API Reference

List

Displays List.Section or List.Item.
The list uses built-in filtering by indexing the title of list items and additionally keywords.

Example

1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List
6
navigationTitle="Search Beers"
7
searchBarPlaceholder="Search your favorite beer"
8
>
9
<List.Item title="Augustiner Helles" />
10
<List.Item title="Camden Hells" />
11
<List.Item title="Leffe Blonde" />
12
<List.Item title="Sierra Nevada IPA" />
13
</List>
14
);
15
}
Copied!

Props

Prop
Description
Type
Default
actions
A reference to an ActionPanel.
React.ReactNode
-
children
List sections or items. If List.Item elements are specified, a default section is automatically created.
React.ReactNode
-
enableFiltering
Toggles Raycast filtering. When true, Raycast will use the query in the search bar to filter list items. When false, the extension needs to take care of the filtering.
boolean
false when onSearchTextChange is specified, true otherwise.
isLoading
Indicates whether a loading bar should be shown or hidden below the search bar
boolean
false
isShowingDetail
Whether the List should have an area on the right side of the items to show additional details about the selected item.
boolean
-
navigationTitle
The main title for that view displayed in Raycast
string
Command title
searchBarAccessory
List.Dropdown that will be shown in the right-hand-side of the search bar.
ReactElement<List.Dropdown.Props, string>
-
searchBarPlaceholder
Placeholder text that will be shown in the search bar.
string
"Search value..."
searchText
The text that will be displayed in the search bar.
string
-
selectedItemId
Selects the item with the specified id.
string
-
throttle
Defines whether the List.Props.onSearchTextChange will be triggered on every keyboard press or with a delay for throttling the events. Recommended to set to true when using custom filtering logic with asynchronous operations (e.g. network requests).
boolean
false
onSearchTextChange
Callback triggered when the search bar text changes.
(text: string) => void
-
onSelectionChange
Callback triggered when the item selection in the list changes.
(id: string) => void
-

List.Dropdown

A dropdown menu that will be shown in the right-hand-side of the search bar.

Example

1
import { List } from "@raycast/api";
2
3
function DrinkDropdown(props: DrinkDropdownProps) {
4
const { isLoading = false, drinkTypes, onDrinkTypeChange } = props;
5
return (
6
<List.Dropdown
7
tooltip="Select Drink Type"
8
storeValue={true}
9
onChange={(newValue) => {
10
onDrinkTypeChange(newValue);
11
}}
12
>
13
<List.Dropdown.Section title="Alcoholic Beverages">
14
{drinkTypes.map((drinkType) => (
15
<List.Dropdown.Item
16
key={drinkType.id}
17
title={drinkType.name}
18
value={drinkType.id}
19
/>
20
))}
21
</List.Dropdown.Section>
22
</List.Dropdown>
23
);
24
}
25
26
export default function Command() {
27
const drinkTypes = [
28
{ id: 1, name: "Beer" },
29
{ id: 2, name: "Wine" },
30
];
31
const onDrinkTypeChange = (newValue) => {
32
console.log(newValue);
33
};
34
return (
35
<List
36
navigationTitle="Search Beers"
37
searchBarPlaceholder="Search your favorite drink"
38
searchBarAccessory={
39
<DrinkDropdown
40
drinkTypes={drinkTypes}
41
onDrinkTypeChange={onDrinkTypeChange}
42
/>
43
}
44
>
45
<List.Item title="Augustiner Helles" />
46
<List.Item title="Camden Hells" />
47
<List.Item title="Leffe Blonde" />
48
<List.Item title="Sierra Nevada IPA" />
49
</List>
50
);
51
}
Copied!

Props

Prop
Description
Type
Default
tooltip*
Tooltip displayed when hovering the dropdown.
string
-
children
List sections or items. If List.Dropdown.Item elements are specified, a default section is automatically created.
React.ReactNode
-
defaultValue
The default value of the dropdown. Keep in mind that defaultValue will be configured once per component lifecycle. This means that if a user changes the value, defaultValue won't be configured on re-rendering.
string
-
id
ID of the dropdown.
string
-
placeholder
Placeholder text that will be shown in the dropdown search field.
string
"Search..."
storeValue
Indicates whether the value of the dropdown should be persisted after selection, and restored next time the dropdown is rendered.
boolean
-
value
The currently value of the dropdown.
string
-
onChange
Callback triggered when the list item selection changes.
(newValue: string) => void
-

List.Dropdown.Item

A dropdown item in a List.Dropdown

Example

1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List searchBarAccessory={
6
<List.Dropdown tooltip="Dropdown With Items">
7
<List.Dropdown.Item title="One" value="one" />
8
<List.Dropdown.Item title="Two" value="two" />
9
<List.Dropdown.Item title="Three" value="three" />
10
</List.Dropdown>
11
}>
12
<List.Item title="Item in the Main List">
13
</List>
14
);
15
}
Copied!

Props

Prop
Description
Type
Default
title*
The title displayed for the item.
string
-
value*
Value of the dropdown item. Make sure to assign each unique value for each item.
string
-
icon
An optional icon displayed for the item.
-

List.Dropdown.Section

Visually separated group of dropdown items.
Use sections to group related menu items together.

Example

1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List searchBarAccessory={
6
<List.Dropdown tooltip="Dropdown With Sections">
7
<List.Dropdown.Section title="First Section">
8
<List.Dropdown.Item title="One" value="one" />
9
</List.Dropdown.Section>
10
<List.Dropdown.Section title="Second Section">
11
<List.Dropdown.Item title="Two" value="two" />
12
</List.Dropdown.Section>
13
</List.Dropdown>
14
}>
15
<List.Item title="Item in the Main List">
16
</List>
17
);
18
}
Copied!

Props

Prop
Description
Type
Default
children
The item elements of the section.
React.ReactNode
-
title
Title displayed above the section
string
-

List.EmptyView

A view to display when there aren't any items available. Use to greet users with a friendly message if the extension requires user input before it can show any list items e.g. when searching for a package, an article etc.
Raycast provides a default EmptyView that will be displayed if the List component either has no children, or if it has children, but none of them match the query in the search bar. This too can be overridden by passing an empty view alongside the other List.Items.
Note that the EmptyView is never displayed if the List's isLoading property is true and the search bar is empty.
List EmptyView illustration

Example

1
import { useState } from "react";
2
import { List } from "@raycast/api";
3
4
export default function CommandWithCustomEmptyView() {
5
const [state, setState] = useState({ searchText: "", items: [] });
6
7
useEffect(() => {
8
// perform an API call that eventually populates `items`.
9
}, [state.searchText]);
10
11
return (
12
<List
13
onSearchTextChange={(newValue) =>
14
setState((previous) => ({ ...previous, searchText: newValue }))
15
}
16
>
17
{state.searchText === "" && state.items.length === 0 ? (
18
<List.EmptyView
19
icon={{ source: "https://placekitten.com/500/500" }}
20
title="Type something to get started"
21
/>
22
) : (
23
state.items.map((item) => <List.Item key={item} title={item} />)
24
)}
25
</List>
26
);
27
}
Copied!

Props

Prop
Description
Type
Default
actions
A reference to an ActionPanel.
React.ReactNode
-
description
An optional description for why the empty view is shown.
string
-
icon
An icon displayed in the center of the EmptyView.
-
title
The main title displayed for the Empty View.
string
-

List.Item

A item in the List.
This is one of the foundational UI components of Raycast. A list item represents a single entity. It can be a GitHub pull request, a file, or anything else. You most likely want to perform actions on this item, so make it clear to the user what this list item is about.

Example

1
import { Icon, List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Item
7
icon={Icon.Star}
8
title="Augustiner Helles"
9
subtitle="0,5 Liter"
10
accessories={[{ text: "Germany" }]}
11
/>
12
</List>
13
);
14
}
Copied!

Props

Prop
Description
Type
Default
title*
The main title displayed for that item, optionally with a tooltip.
string or { tooltip: string; value: string }
-
accessories
An optional array of List.Item.Accessory items displayed on the right side in a List.Item.
-
actions
An ActionPanel that will be updated for the selected list item.
React.ReactNode
-
detail
The List.Item.Detail to be rendered in the right side area when the parent List is showing details and the item is selected.
React.ReactNode
-
icon
An optional icon displayed for the list item.
Image.ImageLike or { tooltip: string; value: Image.ImageLike }
-
id
ID of the item. This string is passed to the onSelectionChange handler of the List when the item is selected. Make sure to assign each item a unique ID or a UUID will be auto generated.
string
-
keywords
An optional property used for providing additional indexable strings for search. When filtering the list in Raycast through the search bar, the keywords will be searched in addition to the title.
string[]
-
subtitle
An optional subtitle displayed next to the main title, optionally with a tooltip.
string or { tooltip: string; value: string }
-

List.Item.Detail

A Detail view that will be shown in the right-hand-side of the List.
When shown, it is recommended not to show any accessories on the List.Item and instead bring those additional information in the List.Item.Detail view.
List-detail illustration

Example

1
import { Icon, List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List isShowingDetail>
6
<List.Item
7
title="Pikachu"
8
subtitle="Electric"
9
detail={
10
<List.Item.Detail markdown="![Illustration](https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png)" />
11
}
12
/>
13
</List>
14
);
15
}
Copied!

Props

Prop
Description
Type
Default
isLoading
Indicates whether a loading bar should be shown or hidden above the detail
boolean
false
markdown
The CommonMark string to be rendered in the right side area when the parent List is showing details and the item is selected.
string
-
metadata
The List.Item.Detail.Metadata to be rendered in the bottom side of the List.Item.Detail
React.ReactNode
-

List.Item.Detail.Metadata

A Metadata view that will be shown in the bottom side of the List.Item.Detail.
Use it to display additional structured data about the content of the List.Item.

Example

Metadata + Markdown
Metadata Standalone
List Detail-metadata illustration
1
import { List } from "@raycast/api";
2
3
export default function Metadata() {
4
const markdown = `
5
![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/001.png)
6
There is a plant seed on its back right from the day this Pokémon is born. The seed slowly grows larger.
7
`;
8
return (
9
<List isShowingDetail>
10
<List.Item
11
title="Bulbasaur"
12
detail={
13
<List.Item.Detail
14
markdown={markdown}
15
metadata={
16
<List.Item.Detail.Metadata>
17
<List.Item.Detail.Metadata.Label title="Types" />
18
<List.Item.Detail.Metadata.Label
19
title="Grass"
20
icon="pokemon_types/grass.svg"
21
/>
22
<List.Item.Detail.Metadata.Separator />
23
<List.Item.Detail.Metadata.Label
24
title="Poison"
25
icon="pokemon_types/poison.svg"
26
/>
27
<List.Item.Detail.Metadata.Separator />
28
<List.Item.Detail.Metadata.Label title="Chracteristics" />
29
<List.Item.Detail.Metadata.Label title="Height" text="70cm" />
30
<List.Item.Detail.Metadata.Separator />
31
<List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
32
<List.Item.Detail.Metadata.Separator />
33
<List.Item.Detail.Metadata.Label title="Abilities" />
34
<List.Item.Detail.Metadata.Label
35
title="Chlorophyll"
36
text="Main Series"
37
/>
38
<List.Item.Detail.Metadata.Separator />
39
<List.Item.Detail.Metadata.Label
40
title="Overgrow"
41
text="Main Series"
42
/>
43
<List.Item.Detail.Metadata.Separator />
44
</List.Item.Detail.Metadata>
45
}
46
/>
47
}
48
/>
49
</List>
50
);
51
}
Copied!
List Detail-metadata illustration
1
import { List } from "@raycast/api";
2
3
export default function Metadata() {
4
return (
5
<List isShowingDetail>
6
<List.Item
7
title="Bulbasaur"
8
detail={
9
<List.Item.Detail
10
metadata={
11
<List.Item.Detail.Metadata>
12
<List.Item.Detail.Metadata.Label title="Types" />
13
<List.Item.Detail.Metadata.Label
14
title="Grass"
15
icon="pokemon_types/grass.svg"
16
/>
17
<List.Item.Detail.Metadata.Separator />
18
<List.Item.Detail.Metadata.Label
19
title="Poison"
20
icon="pokemon_types/poison.svg"
21
/>
22
<List.Item.Detail.Metadata.Separator />
23
<List.Item.Detail.Metadata.Label title="Chracteristics" />
24
<List.Item.Detail.Metadata.Label title="Height" text="70cm" />
25
<List.Item.Detail.Metadata.Separator />
26
<List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
27
<List.Item.Detail.Metadata.Separator />
28
<List.Item.Detail.Metadata.Label title="Abilities" />
29
<List.Item.Detail.Metadata.Label
30
title="Chlorophyll"
31
text="Main Series"
32
/>
33
<List.Item.Detail.Metadata.Separator />
34
<List.Item.Detail.Metadata.Label
35
title="Overgrow"
36
text="Main Series"
37
/>
38
<List.Item.Detail.Metadata.Separator />
39
</List.Item.Detail.Metadata>
40
}
41
/>
42
}
43
/>
44
</List>
45
);
46
}
Copied!

Props

Prop
Description
Type
Default
children*
The Detail.Metadata.Items of the Metadata view.
React.ReactNode
-

List.Item.Detail.Metadata.Label

A title with, optionally, an icon and/or text to its right.
List Detail-metadata-label illustration

Example

1
import { List } from "@raycast/api";
2
3
export default function Metadata() {
4
return (
5
<List isShowingDetail>
6
<List.Item
7
title="Bulbasaur"
8
detail={
9
<List.Item.Detail
10
metadata={
11
<List.Item.Detail.Metadata>
12
<List.Item.Detail.Metadata.Label
13
title="Type"
14
icon="pokemon_types/grass.svg"
15
text="Grass"
16
/>
17
</List.Item.Detail.Metadata>
18
}
19
/>
20
}
21
/>
22
</List>
23
);
24
}
Copied!

Props

Prop
Description
Type
Default
title*
The title of the item.
string
-
icon
An icon to illustrate the value of the item.
-
text
The text value of the item.
string
-

List.Item.Detail.Metadata.Separator

A metadata item that shows a separator line. Use it for grouping and visually separating metadata items.
List Detail-metadata-separator illustration

Example

1
import { List } from "@raycast/api";
2
3
export default function Metadata() {
4
return (
5
<List isShowingDetail>
6
<List.Item
7
title="Bulbasaur"
8
detail={
9
<List.Item.Detail
10
metadata={
11
<List.Item.Detail.Metadata>
12
<List.Item.Detail.Metadata.Label
13
title="Type"
14
icon="pokemon_types/grass.svg"
15
text="Grass"
16
/>
17
<List.Item.Detail.Metadata.Separator />
18
<List.Item.Detail.Metadata.Label
19
title="Type"
20
icon="pokemon_types/poison.svg"
21
text="Poison"
22
/>
23
</List.Item.Detail.Metadata>
24
}
25
/>
26
}
27
/>
28
</List>
29
);
30
}
Copied!

List.Section

A group of related List.Item.
Sections are a great way to structure your list. For example, group GitHub issues with the same status and order them by priority. This way, the user can quickly access what is most relevant.

Example

1
import { List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Section title="Lager">
7
<List.Item title="Camden Hells" />
8
</List.Section>
9
<List.Section title="IPA">
10
<List.Item title="Sierra Nevada IPA" />
11
</List.Section>
12
</List>
13
);
14
}
Copied!

Props

Prop
Description
Type
Default
children
The List.Item elements of the section.
React.ReactNode
-
subtitle
An optional subtitle displayed next to the title of the section.
string
-
title
Title displayed above the section.
string
-

Types

List.Item.Accessory

An interface describing an accessory view in a List.Item.
List.Item accessories illustration

Properties

Property
Description
Type
icon
An optional Image.ImageLike that will be used as the icon.
text
An optional text that will be used as the label.
string
tooltip
An optional tooltip shown when the accessory is hovered.
string

Example

1
import { Icon, List } from "@raycast/api";
2
3
export default function Command() {
4
return (
5
<List>
6
<List.Item
7
title="An Item with Accessories"
8
accessories={[
9
{ text: `An Accessory Text`, icon: Icon.Hammer },
10
{ icon: Icon.Person, tooltip: "A person" },
11
{ text: "Just Do It!" },
12
]}
13
/>
14
</List>