Grid
Last updated
Last updated
The Grid
component is provided as an alternative to the List component when the defining characteristic of an item is an image.
Because its API tries to stick as closely to List's as possible, changing a view from List to Grid should be as simple as:
making sure you're using at least version 1.36.0 of the @raycast/api
package
updating your imports from import { List } from '@raycast/api'
to import { Grid } from '@raycast/api'
;
removing the isShowingDetail
prop from the top-level List
component, along with all List.Items' detail
prop
renaming all List.Items' hicon
prop to content
finally, replacing all usages of List
with Grid
.
The search bar allows users to interact quickly with grid items. By default, Grid.Items are displayed if the user's input can be (fuzzy) matched to the item's title
or keywords
.
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 Grid
's filtering
prop 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.
To do so, you can use the searchText
prop.
Some extensions may benefit from giving users a second filtering dimension. A media file management extension may allow users to view only videos or only images, an image-searching extension may allow switching ssearch engines, etc.
This is where the searchBarAccessory
prop is useful. Pass it a Grid.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 requires version 1.69.0 or higher of the @raycast/api
package.
Grid
s 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 grid, 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 grid.
hasMore
- indicates to Raycast whether it should call onLoadMore
when the user reaches the end of the grid.
pageSize
- indicates how many placeholder items Raycast should add to the end of the grid when it calls onLoadMore
. Once onLoadMore
finishes executing, the placeholder items will be replaced by the newly-added grid 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 grid 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.
Displays Grid.Sections or Grid.Items.
The grid uses built-in filtering by indexing the title & keywords of its items.
actions
React.ReactNode
-
aspectRatio
"1"
or "3/2"
or "2/3"
or "4/3"
or "3/4"
or "16/9"
or "9/16"
-
children
React.ReactNode
-
columns
Column count for the grid's sections. Minimum value is 1, maximum value is 8.
number
5
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.
fit
-
inset
-
isLoading
Indicates whether a loading bar should be shown or hidden below the search bar
boolean
false
navigationTitle
The main title for that view displayed in Raycast
string
Command title
pagination
Configuration for pagination
{ hasMore: boolean; pageSize: number; onLoadMore: () => void }
-
searchBarAccessory
-
searchBarPlaceholder
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 grid changes.
(id: string) => void
-
A dropdown menu that will be shown in the right-hand-side of the search bar.
tooltip*
Tooltip displayed when hovering the dropdown.
string
-
children
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.
(text: string) => void
-
A dropdown item in a Grid.Dropdown
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.
-
keywords
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
Visually separated group of dropdown items.
Use sections to group related menu items together.
children
The item elements of the section.
React.ReactNode
-
title
Title displayed above the section
string
-
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 items e.g. when searching for an image, a gif etc.
Raycast provides a default EmptyView
that will be displayed if the Grid 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 Grid.Item
s.
Note that the EmptyView
is never displayed if the Grid
's isLoading
property is true and the search bar is empty.
actions
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
-
A item in the Grid.
This is one of the foundational UI components of Raycast. A grid item represents a single entity. It can be an image, an emoji, a GIF etc. You most likely want to perform actions on this item, so make it clear to the user what this item is about.
content*
An image or color, optionally with a tooltip, representing the content of the grid item.
-
accessory
-
actions
React.ReactNode
-
id
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
{ name?: string; path: string }
-
subtitle
An optional subtitle displayed below the title.
string
-
title
An optional title displayed below the content.
string
-
A group of related Grid.Item.
Sections are a great way to structure your grid. For example, you can group photos taken in the same place or in the same day. This way, the user can quickly access what is most relevant.
Sections can specify their own columns
, fit
, aspectRatio
and inset
props, separate from what is defined on the main Grid component.
aspectRatio
"1"
or "3/2"
or "2/3"
or "4/3"
or "3/4"
or "16/9"
or "9/16"
-
children
React.ReactNode
-
columns
Column count for the section. Minimum value is 1, maximum value is 8.
number
5
fit
-
inset
-
subtitle
An optional subtitle displayed next to the title of the section.
string
-
title
Title displayed above the section.
string
-
An interface describing an accessory view in a Grid.Item
.
An enum representing the amount of space there should be between a Grid Item's content and its borders. The absolute value depends on the value of Grid's or Grid.Section's columns
prop.
Small
Small insets
Medium
Medium insets
Large
Large insets
An enum representing the size of the Grid's child Grid.Items.
Small
Fits 8 items per row.
Medium
Fits 5 items per row.
Large
Fits 3 items per row.
An enum representing how Grid.Item's content should be fit.
Contain
The content will be contained within the grid cell, with vertical/horizontal bars if its aspect ratio differs from the cell's.
Fill
The content will be scaled proportionally so that it fill the entire cell; parts of the content could end up being cropped out.
A reference to an . It will only be shown when there aren't any children.
Aspect ratio for the elements. Defaults to 1.
Grid sections or items. If elements are specified, a default section is automatically created.
Fit for the element content. Defaults to "contain"
Indicates how much space there should be between a s' content and its borders. The absolute value depends on the value of the itemSize
prop.
that will be shown in the right-hand-side of the search bar.
ReactElement<
, string>
A reference to an .
or { color:
}
or { tooltip: string; value:
or { color:
} }
An optional item displayed underneath a .
An that will be updated for the selected grid item.
ID of the item. This string is passed to the onSelectionChange
handler of the when the item is selected. Make sure to assign each item a unique ID or a UUID will be auto generated.
Optional information to preview files with Quick Look. Toggle the preview ith .
Aspect ratio for the elements. Defaults to 1.
The elements of the section.
Fit for the element content. Defaults to "contain"
Inset for the element content. Defaults to "none".