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 filteringprop to false, and the items displayed will be independent of the search bar's text. Note that filtering 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 filtering to true.
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.
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 searchBarAccessoryprop 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.
Pagination
Pagination requires version 1.69.0 or higher of the @raycast/api package.
Lists have built-in support for pagination. To opt in to pagination, you need to pass it a pagination prop, which is an object providing 3 pieces of information:
onLoadMore - will be called by Raycast when the user reaches the end of the list, either using the keyboard or the mouse. When it gets called, the extension is expected to perform an async operation which eventually can result in items being appended to the end of the list.
hasMore - indicates to Raycast whether it should call onLoadMore when the user reaches the end of the list.
pageSize - indicates how many placeholder items Raycast should add to the end of the list when it calls onLoadMore. Once onLoadMore finishes executing, the placeholder items will be replaced by the newly-added list items.
Note that extensions have access to a limited amount of memory. As your extension paginates, its memory usage will increase. Paginating extensively could lead to the extension eventually running out of memory and crashing. To protect against the extension crashing due to memory exhaustion, Raycast monitors the extension's memory usage and employs heuristics to determine whether it's safe to paginate further. If it's deemed unsafe to continue paginating, onLoadMore will not be triggered when the user scrolls to the bottom, regardless of the hasMore value. Additionally, during development, a warning will be printed in the terminal.
For convenience, most of the hooks that we provide have built-in pagination support. Here's an example of how to add pagination support to a simple command using usePromise, and one "from scratch".
Pagination might not work properly if all list items are rendered and visible at once, as onLoadMore won't be triggered. This typically happens when an API returns 10 results by default, all fitting within the Raycast window. To fix this, try displaying more items, like 20.
A reference to an ActionPanel. It will only be shown when there aren't any children.
React.ReactNode
-
children
List sections or items. If List.Item elements are specified, a default section is automatically created.
React.ReactNode
-
filtering
Toggles Raycast filtering. When true, Raycast will use the query in the search bar to filter the items. When false, the extension needs to take care of the filtering.
boolean or { keepSectionOrder: 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.
Placeholder text that will be shown in the search bar.
string
"Search…"
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 onSearchTextChange handler 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.
Dropdown sections or items. If 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
-
filtering
Toggles Raycast filtering. When true, Raycast will use the query in the search bar to filter the items. When false, the extension needs to take care of the filtering.
boolean or { keepSectionOrder: boolean }
false when onSearchTextChange is specified, true otherwise.
id
ID of the dropdown.
string
-
isLoading
Indicates whether a loading indicator should be shown or hidden next to the search bar
boolean
false
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
-
throttle
Defines whether the onSearchTextChange handler 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
value
The currently value of the dropdown.
string
-
onChange
Callback triggered when the dropdown selection changes.
(newValue: string) => void
-
onSearchTextChange
Callback triggered when the search bar text changes.
An optional property used for providing additional indexable strings for search. When filtering the items in Raycast, the keywords will be searched in addition to the title.
string[]
The title of its section if any
List.Dropdown.Section
Visually separated group of dropdown items.
Use sections to group related menu items together.
Example
import { List } from"@raycast/api";exportdefaultfunctionCommand() {return (<List searchBarAccessory={ <List.Dropdown tooltip="Dropdown With Sections"> <List.Dropdown.Section title="First Section"> <List.Dropdown.Item title="One" value="one"/> </List.Dropdown.Section> <List.Dropdown.Section title="Second Section"> <List.Dropdown.Item title="Two" value="two"/> </List.Dropdown.Section> </List.Dropdown> }><List.Item title="Item in the Main List"/></List> );}
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.
Example
import { useEffect, useState } from"react";import { List } from"@raycast/api";exportdefaultfunctionCommandWithCustomEmptyView() {const [state,setState] =useState({ searchText:"", items: [] });useEffect(() => {// perform an API call that eventually populates `items`. }, [state.searchText]);return (<List onSearchTextChange={(newValue) => setState((previous) => ({ ...previous, searchText:newValue }))}> {state.searchText === "" && state.items.length === 0 ? ( <List.EmptyView icon={{ source:"https://placekitten.com/500/500" }} title="Type something to get started"/> ) : ( state.items.map((item) => <List.Itemkey={item} title={item} />) )}</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.
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[]
-
quickLook
Optional information to preview files with Quick Look. Toggle the preview with Action.ToggleQuickLook.
{ name?: string; path: 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.