# AI

The AI API provides developers with seamless access to AI functionality without requiring API keys, configuration, or extra dependencies.

{% hint style="info" %}

Some users might not have access to this API. If a user doesn't have access to Raycast Pro, they will be asked if they want to get access when your extension calls the AI API. If the user doesn't wish to get access, the API call will throw an error.

You can check if a user has access to the API using `environment.canAccess(AI)`.

{% endhint %}

## API Reference

### AI.ask

Ask AI anything you want. Use this in “no-view” Commands, effects, or callbacks. In a React component, you might want to use the useAI util hook instead.

#### Signature

```typescript
async function ask(prompt: string, options?: AskOptions): Promise<string> & EventEmitter;
```

#### Example

{% tabs %}
{% tab title="Basic Usage" %}

```typescript
import { AI, Clipboard } from "@raycast/api";

export default async function command() {
  const answer = await AI.ask("Suggest 5 jazz songs");

  await Clipboard.copy(answer);
}
```

{% endtab %}
{% tab title="Error handling" %}

```typescript
import { AI, showToast, Toast } from "@raycast/api";

export default async function command() {
  try {
    await AI.ask("Suggest 5 jazz songs");
  } catch (error) {
    // Handle error here, eg: by showing a Toast
    await showToast({
      style: Toast.Style.Failure,
      title: "Failed to generate answer",
    });
  }
}
```

{% endtab %}
{% tab title="Stream answer" %}

```typescript
import { AI, getSelectedFinderItems, showHUD } from "@raycast/api";
import fs from "fs";

export default async function main() {
  let allData = "";
  const [file] = await getSelectedFinderItems();

  const answer = AI.ask("Suggest 5 jazz songs");

  // Listen to "data" event to stream the answer
  answer.on("data", async (data) => {
    allData += data;
    await fs.promises.writeFile(`${file.path}`, allData.trim(), "utf-8");
  });

  await answer;

  await showHUD("Done!");
}
```

{% endtab %}
{% tab title="User Feedback" %}

```typescript
import { AI, getSelectedFinderItems, showHUD } from "@raycast/api";
import fs from "fs";

export default async function main() {
  let allData = "";
  const [file] = await getSelectedFinderItems();

  // If you're doing something that happens in the background
  // Consider showing a HUD or a Toast as the first step
  // To give users feedback about what's happening
  await showHUD("Generating answer...");

  const answer = await AI.ask("Suggest 5 jazz songs");

  await fs.promises.writeFile(`${file.path}`, allData.trim(), "utf-8");

  // Then, when everythig is done, notify the user again
  await showHUD("Done!");
}
```

{% endtab %}
{% tab title="Check for access" %}

```typescript
import { AI, getSelectedFinderItems, showHUD, environment } from "@raycast/api";
import fs from "fs";

export default async function main() {
  if (environment.canAccess(AI)) {
    const answer = await AI.ask("Suggest 5 jazz songs");
    await Clipboard.copy(answer);
  } else {
    await showHUD("You don't have access :(");
  }
}
```

{% endtab %}
{% endtabs %}

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| prompt<mark style="color:red;">*</mark> | The prompt to ask the AI. | <code>string</code> |
| options | Options to control which and how the AI model should behave.  | <code>AI.AskOptions</code> |

#### Return

A Promise that resolves with a prompt completion.

## Types

### AI.Creativity

Concrete tasks, such as fixing grammar, require less creativity while open-ended questions, such as generating ideas, require more.

```typescript
type Creativity = "none" | "low" | "medium" | "high" | "maximum" | number;
```

If a number is passed, it needs to be in the range 0-2. For larger values, 2 will be used. For lower values, 0 will be used.

### AI.Model

The AI model to use to answer to the prompt. Defaults to `AI.Model["OpenAI_GPT3.5-turbo"]`.

#### Enumeration members

| Model                           | Description                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OpenAI_GPT4                     | GPT-4 is the model with broad general knowledge, allowing it to follow complex instructions and solve difficult problems. This model is the previous generation, use GPT-4o for better results.  |
| OpenAI_GPT4-turbo               | GPT-4 Turbo is an evolution of the GPT-4 model with a larger context. This model is the previous generation, use gpt-4o for better results.                                                      |
| OpenAI_GPT4o                    | GPT-4o is the most advanced and fastest model from OpenAI, making it a great choice for complex everyday problems and deeper conversations.                                                      |
| OpenAI_GPT4o-mini               | GPT-4o mini is a highly intelligent and fast model that is ideal for a variety of everyday tasks.                                                                                                |
| Anthropic_Claude_Haiku          | Claude 3.5 Haiku is Anthropic's fastest model, with a large context window that makes it ideal for analyzing code, documents, or large amounts of text.                                          |
| Anthropic_Claude_Sonnet         | Claude 3.5 Sonnet from Anthropic has enhanced intelligence with increased speed. It excels at complex tasks like visual reasoning or workflow orchestrations.                                    |
| Anthropic_Claude_Opus           | Claude 3 Opus is Anthropic's intelligent model designed to solve highly complex tasks. It stands out for its remarkable fluency.                                                                 |
| Perplexity_Llama3.1_Sonar_Small | Perplexity's Llama 3.1 Sonar Small is built for speed. It quickly gives you helpful answers using the latest internet knowledge while minimizing hallucinations.                                 |
| Perplexity_Llama3.1_Sonar_Large | Perplexity's advanced model. Can handle complex questions. It considers current web knowledge to provide well-reasoned, in-depth answers.                                                        |
| Perplexity_Llama3.1_Sonar_Huge  | Perplexity's most advanced model. Offers performance that is on par with state of the art models today.                                                                                          |
| Llama3.3_70B                    | Llama 3.3 70B is an open-source model from Meta, state-of-the-art in areas like reasoning, math, and general knowledge.                                                                          |
| Llama3.1_8B                     | Llama 3.1 8B is an open-source model from Meta, optimized for instruction following and high-speed performance. Powered by Groq.                                                                 |
| Llama3_70B                      | Llama 3 70B from Meta is a highly capable open-source LLM that can serve as a tool for various text-related tasks. Powered by Groq.                                                              |
| Llama3.1_405B                   | Llama 3.1 405B is Meta's flagship open-source model, offering unparalleled capabilities in general knowledge, steerability, math, tool use, and multilingual translation. Powered by together.ai |
| MixtraL_8x7B                    | Mixtral 8x7B from Mistral is an open-source model that demonstrates high performance in generating code and text at an impressive speed. Powered by Groq.                                        |
| Mistral_Nemo                    | Mistral Nemo is a small model built in collaboration with NVIDIA, and released under the Apache 2.0 license.                                                                                     |
| Mistral_Large2                  | Mistral Large is Mistral's flagship model, capable of code generation, mathematics, and reasoning, with stronger multilingual support.                                                           |

If a model isn't available to the user, Raycast will fallback to a similar one:

- `AI.Model.Anthropic_Claude_Opus` and `AI.Model.Anthropic_Claude_Sonnet` -> `AI.Model.Anthropic_Claude_Haiku`
- `AI.Model.OpenAI_GPT4` and `AI.Model["OpenAI_GPT4-turbo"]` -> `AI.Model["OpenAI_GPT4o-mini"]`
- `AI.Model["Perplexity_Llama3.1_Sonar_Large"]` and `AI.Model["Perplexity_Llama3.1_Sonar_Huge"]` -> `AI.Model["Perplexity_Llama3.1_Sonar_Small"]`
- `AI.Model.Mistral_Large2` -> `AI.Model.Mistral_Nemo`
- `AI.Model["Llama3.1_405B"]` -> `AI.Model["Llama3.3_70B"]`

### AI.AskOptions

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| creativity | Concrete tasks, such as fixing grammar, require less creativity while open-ended questions, such as generating ideas, require more. If a number is passed, it needs to be in the range 0-2. For larger values, 2 will be used. For lower values, 0 will be used. | <code>AI.Creativity</code> |
| model | The AI model to use to answer to the prompt. | <code>AI.Model</code> |
| signal | Abort signal to cancel the request. | <code>AbortSignal</code> |


# Browser Extension

The Browser Extension API provides developers with deeper integration into the user's Browser _via_ a [Browser Extension](https://raycast.com/browser-extension).

{% hint style="info" %}

Some users might not have installed the Browser Extension. If a user doesn't have the Browser Extension installed, they will be asked if they want to install it when your extension calls the Browser Extension API. If the user doesn't wish to install it, the API call will throw an error.

You can check if a user has the Browser Extension installed using `environment.canAccess(BrowserExtension)`.

{% endhint %}

## API Reference

### BrowserExtension.getContent

Get the content of an opened browser tab.

#### Signature

```typescript
async function getContent(options?: {
  cssSelector?: string;
  tabId?: number;
  format?: "html" | "text" | "markdown";
}): Promise<string>;
```

#### Example

{% tabs %}
{% tab title="Basic Usage" %}

```typescript
import { BrowserExtension, Clipboard } from "@raycast/api";

export default async function command() {
  const markdown = await BrowserExtension.getContent({ format: "markdown" });

  await Clipboard.copy(markdown);
}
```

{% endtab %}
{% tab title="CSS Selector" %}

```typescript
import { BrowserExtension, Clipboard } from "@raycast/api";

export default async function command() {
  const title = await BrowserExtension.getContent({ format: "text", cssSelector: "title" });

  await Clipboard.copy(title);
}
```

{% endtab %}
{% endtabs %}

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Options to control which content to get. | <code>Object</code> |
| options.cssSelector | Only returns the content of the element that matches the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors). | <code>string</code> |
| options.format | The format of the content. | <code>"html"</code> or <code>"text"</code> or <code>"markdown"</code> |
| options.tabId | The ID of the tab to get the content from. If not specified, the content of the active tab of the focused window is returned. | <code>number</code> |

#### Return

A Promise that resolves with the content of the tab.

### BrowserExtension.getTabs

Get the list of open browser tabs.

#### Signature

```typescript
async function getTabs(): Promise<Tab[]>;
```

#### Example

```typescript
import { BrowserExtension } from "@raycast/api";

export default async function command() {
  const tabs = await BrowserExtension.getTabs();
  console.log(tabs);
}
```

#### Return

A Promise that resolves with the list of tabs.

## Types

### BrowserExtension.Tab

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| active<mark style="color:red;">*</mark> | Whether the tab is active in its window. There can only be one active tab per window but if there are multiple browser windows, there can be multiple active tabs. | <code>boolean</code> |
| id<mark style="color:red;">*</mark> | The ID of the tab. Tab IDs are unique within a browser session. | <code>number</code> |
| url<mark style="color:red;">*</mark> | The URL the tab is displaying. | <code>string</code> |
| favicon | The URL of the tab's [favicon](https://developer.mozilla.org/en-US/docs/Glossary/Favicon). It may also be `undefined` if the tab is loading. | <code>string</code> |
| title | The title of the tab. It may also be `undefined` if the tab is loading. | <code>string</code> |


# Caching

Caching abstraction that stores data on disk and supports LRU (least recently used) access. Since extensions can only consume up to a max. heap memory size, the cache only maintains a lightweight index in memory and stores the actual data in separate files on disk in the extension's support directory.

## API Reference

### Cache

The `Cache` class provides CRUD-style methods (get, set, remove) to update and retrieve data synchronously based on a key. The data must be a string and it is up to the client to decide which serialization format to use.
A typical use case would be to use `JSON.stringify` and `JSON.parse`.

By default, the cache is shared between the commands of an extension. Use Cache.Options.

#### Signature

```typescript
constructor(options: Cache.Options): Cache
```

#### Example

```typescript
import { List, Cache } from "@raycast/api";

type Item = { id: string; title: string };
const cache = new Cache();
cache.set("items", JSON.stringify([{ id: "1", title: "Item 1" }]));

export default function Command() {
  const cached = cache.get("items");
  const items: Item[] = cached ? JSON.parse(cached) : [];

  return (
    <List>
      {items.map((item) => (
        <List.Item key={item.id} title={item.title} />
      ))}
    </List>
  );
}
```

#### Properties

| Property                                  | Description                                              | Type                 |
| :---------------------------------------- | :------------------------------------------------------- | :------------------- |
| isEmpty<mark style="color:red;">\*</mark> | Returns `true` if the cache is empty, `false` otherwise. | <code>boolean</code> |

#### Methods

| Method                                                                                       |
| :------------------------------------------------------------------------------------------- |
| <code>get(key: string): string \| undefined</code>                             |
| <code>has(key: string): boolean</code>                                         |
| <code>set(key: string, data: string): void</code>                              |
| <code>remove(key: string): boolean</code>                                   |
| <code>clear(options = { notifySubscribers: true }): void</code>              |
| <code>subscribe(subscriber: Cache.Subscriber): Cache.Subscription</code> |

### Cache#get

Returns the data for the given key. If there is no data for the key, `undefined` is returned.
If you want to just check for the existence of a key, use has.

#### Signature

```typescript
get(key: string): string | undefined
```

#### Parameters

| Name                                  | Description                 | Type                |
| :------------------------------------ | :-------------------------- | :------------------ |
| key<mark style="color:red;">\*</mark> | The key of the Cache entry. | <code>string</code> |

### Cache#has

Returns `true` if data for the key exists, `false` otherwise.
You can use this method to check for entries without affecting the LRU access.

#### Signature

```typescript
has(key: string): boolean
```

#### Parameters

| Name                                  | Description                 | Type                |
| :------------------------------------ | :-------------------------- | :------------------ |
| key<mark style="color:red;">\*</mark> | The key of the Cache entry. | <code>string</code> |

### Cache#set

Sets the data for the given key.
If the data exceeds the configured `capacity`, the least recently used entries are removed.
This also notifies registered subscribers (see subscribe.

#### Signature

```typescript
set(key: string, data: string)
```

#### Parameters

| Name                                   | Description                              | Type                |
| :------------------------------------- | :--------------------------------------- | :------------------ |
| key<mark style="color:red;">\*</mark>  | The key of the Cache entry.              | <code>string</code> |
| data<mark style="color:red;">\*</mark> | The stringified data of the Cache entry. | <code>string</code> |

### Cache#remove

Removes the data for the given key.
This also notifies registered subscribers (see subscribe.
Returns `true` if data for the key was removed, `false` otherwise.

#### Signature

```typescript
remove(key: string): boolean
```

### Cache#clear

Clears all stored data.
This also notifies registered subscribers (see subscribe unless the `notifySubscribers` option is set to `false`.

#### Signature

```typescript
clear((options = { notifySubscribers: true }));
```

#### Parameters

| Name    | Description                                                                                                                | Type                |
| :------ | :------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| options | Options with a `notifySubscribers` property. The default is `true`; set to `false` to disable notification of subscribers. | <code>object</code> |

### Cache#subscribe

Registers a new subscriber that gets notified when cache data is set or removed.
Returns a function that can be called to remove the subscriber.

#### Signature

```typescript
subscribe(subscriber: Cache.Subscriber): Cache.Subscription
```

#### Parameters

| Name       | Description                                                                                                                                                                                               | Type                                               |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| subscriber | A function that is called when the Cache is updated. The function receives two values: the `key` of the Cache entry that was updated or `undefined` when the Cache is cleared, and the associated `data`. | <code>Cache.Subscriber</code> |

## Types

### Cache.Options

The options for creating a new Cache.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| capacity | The capacity in bytes. If the stored data exceeds the capacity, the least recently used data is removed. The default capacity is 10 MB. | <code>number</code> |
| namespace | If set, the Cache will be namespaced via a subdirectory. This can be useful to separate the caches for individual commands of an extension. By default, the cache is shared between the commands of an extension. | <code>string</code> |

### Cache.Subscriber

Function type used as parameter for subscribe.

```typescript
type Subscriber = (key: string | undefined, data: string | undefined) => void;
```

### Cache.Subscription

Function type returned from subscribe.

```typescript
type Subscription = () => void;
```


# Clipboard

Use the Clipboard APIs to work with content from your clipboard. You can write contents to the clipboard through `Clipboard.copy` function inserts text at the current cursor position in your frontmost app.

The action `Action.CopyToClipboard` can be used to insert text in your frontmost app.

## API Reference

### Clipboard.copy

Copies text or a file to the clipboard.

#### Signature

```typescript
async function copy(content: string | number | Content, options?: CopyOptions): Promise<void>;
```

#### Example

```typescript
import { Clipboard } from "@raycast/api";

export default async function Command() {
  // copy some text
  await Clipboard.copy("https://raycast.com");

  const textContent: Clipboard.Content = {
    text: "https://raycast.com",
  };
  await Clipboard.copy(textContent);

  // copy a file
  const file = "/path/to/file.pdf";
  try {
    const fileContent: Clipboard.Content = { file };
    await Clipboard.copy(fileContent);
  } catch (error) {
    console.log(`Could not copy file '${file}'. Reason: ${error}`);
  }

  // copy confidential data
  await Clipboard.copy("my-secret-password", { concealed: true });
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| content<mark style="color:red;">*</mark> | The content to copy to the clipboard. | <code>string</code> or <code>number</code> or <code>Clipboard.Content</code> |
| options | Options for the copy operation. | <code>Clipboard.CopyOptions</code> |

#### Return

A Promise that resolves when the content is copied to the clipboard.

### Clipboard.paste

Pastes text or a file to the current selection of the frontmost application.

#### Signature

```typescript
async function paste(content: string | Content): Promise<void>;
```

#### Example

```typescript
import { Clipboard } from "@raycast/api";

export default async function Command() {
  await Clipboard.paste("I really like Raycast's API");
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| content<mark style="color:red;">*</mark> | The content to insert at the cursor. | <code>string</code> or <code>number</code> or <code>Clipboard.Content</code> |

#### Return

A Promise that resolves when the content is pasted.

### Clipboard.clear

Clears the current clipboard contents.

#### Signature

```typescript
async function clear(): Promise<void>;
```

#### Example

```typescript
import { Clipboard } from "@raycast/api";

export default async function Command() {
  await Clipboard.clear();
}
```

#### Return

A Promise that resolves when the clipboard is cleared.

### Clipboard.read

Reads the clipboard content as plain text, file name, or HTML.

#### Signature

```typescript
async function read(options?: { offset?: number }): Promise<ReadContent>;
```

#### Example

```typescript
import { Clipboard } from "@raycast/api";

export default async () => {
  const { text, file, html } = await Clipboard.read();
  console.log(text);
  console.log(file);
  console.log(html);
};
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Options for the read operation. | <code>Object</code> |
| options.offset | Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5. | <code>number</code> |

#### Return

A promise that resolves when the clipboard content was read as plain text, file name, or HTML.

### Clipboard.readText

Reads the clipboard as plain text.

#### Signature

```typescript
async function readText(options?: { offset?: number }): Promise<string | undefined>;
```

#### Example

```typescript
import { Clipboard } from "@raycast/api";

export default async function Command() {
  const text = await Clipboard.readText();
  console.log(text);
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Options for the readText operation. | <code>Object</code> |
| options.offset | Specify an offset to access the Clipboard History. Minimum value is 0, maximum value is 5. | <code>number</code> |

#### Return

A promise that resolves once the clipboard content is read as plain text.

## Types

### Clipboard.Content

Type of content that is copied and pasted to and from the Clipboard

```typescript
type Content =
  | {
      text: string;
    }
  | {
      file: PathLike;
    }
  | {
      html: string;
      text?: string; // The alternative text representation of the content.
    };
```

### Clipboard.ReadContent

Type of content that is read from the Clipboard

```typescript
type Content =
  | {
      text: string;
    }
  | {
      file?: string;
    }
  | {
      html?: string;
    };
```

### Clipboard.CopyOptions

Type of options passed to `Clipboard.copy`.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| concealed | Indicates whether the content be treated as confidential. If `true`, it will not be recorded in the Clipboard History. | <code>boolean</code> |


# Command-related Utilities

This set of utilities to work with Raycast commands.

## API Reference

### launchCommand

Launches another command. If the command does not exist, or if it's not enabled, an error will be thrown.
If the command is part of another extension, the user will be presented with a permission alert.
Use this method if your command needs to open another command based on user interaction,
or when an immediate background refresh should be triggered, for example when a command needs to update an associated menu-bar command.

#### Signature

```typescript
export async function launchCommand(options: LaunchOptions): Promise<void>;
```

#### Example

```typescript
import { launchCommand, LaunchType } from "@raycast/api";

export default async function Command() {
  await launchCommand({ name: "list", type: LaunchType.UserInitiated, context: { foo: "bar" } });
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options<mark style="color:red;">*</mark> | Options to launch a command within the same extension or in another extension. | <code>LaunchOptions</code> |

#### Return

A Promise that resolves when the command has been launched. (Note that this does not indicate that the launched command has finished executing.)

### updateCommandMetadata

Update the values of properties declared in the manifest of the current command. Note that currently only `subtitle` is supported. Pass `null` to clear the custom subtitle.

{% hint style="info" %}
The actual manifest file is not modified, so the update applies as long as the command remains installed.
{% endhint %}

#### Signature

```typescript
export async function updateCommandMetadata(metadata: { subtitle?: string | null }): Promise<void>;
```

#### Example

```typescript
import { updateCommandMetadata } from "@raycast/api";

async function fetchUnreadNotificationCount() {
  return 10;
}

export default async function Command() {
  const count = await fetchUnreadNotificationCount();
  await updateCommandMetadata({ subtitle: `Unread Notifications: ${count}` });
}
```

#### Return

A Promise that resolves when the command's metadata have been updated.

## Types

### LaunchContext

Represents the passed context object of programmatic command launches.

### LaunchOptions

A parameter object used to decide which command should be launched and what data (arguments, context) it should receive.

#### IntraExtensionLaunchOptions

The options that can be used when launching a command from the same extension.

| Property | Description | Type |
| :--- | :--- | :--- |
| name<mark style="color:red;">*</mark> | Command name as defined in the extension's manifest | <code>string</code> |
| type<mark style="color:red;">*</mark> | LaunchType.UserInitiated</code> |
| arguments | Optional object for the argument properties and values as defined in the extension's manifest, for example: `{ "argument1": "value1" }` | <code>Arguments</code> or <code>null</code> |
| context | Arbitrary object for custom data that should be passed to the command and accessible as LaunchProps</code> or <code>null</code> |
| fallbackText | Optional string to send as fallback text to the command | <code>string</code> or <code>null</code> |

#### InterExtensionLaunchOptions

The options that can be used when launching a command from a different extension.

| Property | Description | Type |
| :--- | :--- | :--- |
| extensionName<mark style="color:red;">*</mark> | When launching command from a different extension, the extension name (as defined in the extension's manifest) is necessary | <code>string</code> |
| name<mark style="color:red;">*</mark> | Command name as defined in the extension's manifest | <code>string</code> |
| ownerOrAuthorName<mark style="color:red;">*</mark> | When launching command from a different extension, the owner or author (as defined in the extension's manifest) is necessary | <code>string</code> |
| type<mark style="color:red;">*</mark> | LaunchType.UserInitiated</code> |
| arguments | Optional object for the argument properties and values as defined in the extension's manifest, for example: `{ "argument1": "value1" }` | <code>Arguments</code> or <code>null</code> |
| context | Arbitrary object for custom data that should be passed to the command and accessible as LaunchProps</code> or <code>null</code> |
| fallbackText | Optional string to send as fallback text to the command | <code>string</code> or <code>null</code> |


# Environment

The Environment APIs are useful to get context about the setup in which your command runs. You can get information about the extension and command itself as well as Raycast. Furthermore, a few paths are injected and are helpful to construct file paths that are related to the command's assets.

## API Reference

### environment

Contains environment values such as the Raycast version, extension info, and paths.

#### Example

```typescript
import { environment } from "@raycast/api";

export default async function Command() {
  console.log(`Raycast version: ${environment.raycastVersion}`);
  console.log(`Owner or Author name: ${environment.ownerOrAuthorName}`);
  console.log(`Extension name: ${environment.extensionName}`);
  console.log(`Command name: ${environment.commandName}`);
  console.log(`Command mode: ${environment.commandMode}`);
  console.log(`Assets path: ${environment.assetsPath}`);
  console.log(`Support path: ${environment.supportPath}`);
  console.log(`Is development mode: ${environment.isDevelopment}`);
  console.log(`Appearance: ${environment.appearance}`);
  console.log(`Text size: ${environment.textSize}`);
  console.log(`LaunchType: ${environment.launchType}`);
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| appearance<mark style="color:red;">*</mark> | The appearance used by the Raycast application. | <code>"light"</code> or <code>"dark"</code> |
| assetsPath<mark style="color:red;">*</mark> | The absolute path to the assets directory of the extension. | <code>string</code> |
| commandMode<mark style="color:red;">*</mark> | The mode of the launched command, as specified in package.json | <code>"no-view"</code> or <code>"view"</code> or <code>"menu-bar"</code> |
| commandName<mark style="color:red;">*</mark> | The name of the launched command, as specified in package.json | <code>string</code> |
| extensionName<mark style="color:red;">*</mark> | The name of the extension, as specified in package.json | <code>string</code> |
| isDevelopment<mark style="color:red;">*</mark> | Indicates whether the command is a development command (vs. an installed command from the Store). | <code>boolean</code> |
| launchType<mark style="color:red;">*</mark> | The type of launch for the command (user initiated or background). | <code>LaunchType</code> |
| ownerOrAuthorName<mark style="color:red;">*</mark> | The name of the extension owner (if any) or author, as specified in package.json | <code>string</code> |
| raycastVersion<mark style="color:red;">*</mark> | The version of the main Raycast app | <code>string</code> |
| supportPath<mark style="color:red;">*</mark> | The absolute path for the support directory of an extension. Use it to read and write files related to your extension or command. | <code>string</code> |
| textSize<mark style="color:red;">*</mark> | The text size used by the Raycast application. | <code>"medium"</code> or <code>"large"</code> |
| canAccess<mark style="color:red;">*</mark> | Returns whether the user has access to the given API. | <code>(api: unknown) => boolean</code> |

### environment.canAccess

Checks whether the user can access a specific API or not.

#### Signature

```typescript
function canAccess(api: any): bool;
```

#### Example

```typescript
import { AI, showHUD, environment } from "@raycast/api";
import fs from "fs";

export default async function main() {
  if (environment.canAccess(AI)) {
    const answer = await AI.ask("Suggest 5 jazz songs");
    await Clipboard.copy(answer);
  } else {
    await showHUD("You don't have access :(");
  }
}
```

#### Return

A Boolean indicating whether the user running the command has access to the API.

### getSelectedFinderItems

Gets the selected items from Finder.

#### Signature

```typescript
async function getSelectedFinderItems(): Promise<FileSystemItem[]>;
```

#### Example

```typescript
import { getSelectedFinderItems, showToast, Toast } from "@raycast/api";

export default async function Command() {
  try {
    const selectedItems = await getSelectedFinderItems();
    console.log(selectedItems);
  } catch (error) {
    await showToast({
      style: Toast.Style.Failure,
      title: "Cannot copy file path",
      message: String(error),
    });
  }
}
```

#### Return

A Promise that resolves with the selected file system items. If Finder is not the frontmost application, the promise will be rejected.

### getSelectedText

Gets the selected text of the frontmost application.

#### Signature

```typescript
async function getSelectedText(): Promise<string>;
```

#### Example

```typescript
import { getSelectedText, Clipboard, showToast, Toast } from "@raycast/api";

export default async function Command() {
  try {
    const selectedText = await getSelectedText();
    const transformedText = selectedText.toUpperCase();
    await Clipboard.paste(transformedText);
  } catch (error) {
    await showToast({
      style: Toast.Style.Failure,
      title: "Cannot transform text",
      message: String(error),
    });
  }
}
```

#### Return

A Promise that resolves with the selected text. If no text is selected in the frontmost application, the promise will be rejected.

## Types

### FileSystemItem

Holds data about a File System item. Use the getSelectedFinderItems method to retrieve values.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> | The path to the item | <code>string</code> |

### LaunchType

Indicates the type of command launch. Use this to detect whether the command has been launched from the background.

#### Enumeration members

| Name          | Description                                                |
| :------------ | :--------------------------------------------------------- |
| UserInitiated | A regular launch through user interaction                  |
| Background    | Scheduled through an interval and launched from background |


# Feedback

Raycast has several ways to provide feedback to the user:

- Toast _- when an asynchronous operation is happening or when an error is thrown_
- HUD _- to confirm an action worked after closing Raycast_
- Alert _- to ask for confirmation before taking an action_




# Alert

When the user takes an important action (for example when irreversibly deleting something), you can ask for confirmation by using `confirmAlert`.



## API Reference

### confirmAlert

Creates and shows a confirmation Alert with the given options.

#### Signature

```typescript
async function confirmAlert(options: Alert.Options): Promise<boolean>;
```

#### Example

```typescript
import { confirmAlert } from "@raycast/api";

export default async function Command() {
  if (await confirmAlert({ title: "Are you sure?" })) {
    console.log("confirmed");
    // do something
  } else {
    console.log("canceled");
  }
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options<mark style="color:red;">*</mark> | The options used to create the Alert. | <code>Alert.Options</code> |

#### Return

A Promise that resolves to a boolean when the user triggers one of the actions.
It will be `true` for the primary Action, `false` for the dismiss Action.

## Types

### Alert.Options

The options to create an Alert.

#### Example

```typescript
import { Alert, confirmAlert } from "@raycast/api";

export default async function Command() {
  const options: Alert.Options = {
    title: "Finished cooking",
    message: "Delicious pasta for lunch",
    primaryAction: {
      title: "Do something",
      onAction: () => {
        // while you can register a handler for an action, it's more elegant
        // to use the `if (await confirmAlert(...)) { ... }` pattern
        console.log("The alert action has been triggered");
      },
    },
  };
  await confirmAlert(options);
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of an alert. Displayed below the icon. | <code>string</code> |
| dismissAction | The Action to dismiss the alert. There usually shouldn't be any side effects when the user takes this action. | <code>Alert.ActionOptions</code> |
| icon | The icon of an alert to illustrate the action. Displayed on the top. | <code>Image.ImageLike</code> |
| message | An additional message for an Alert. Useful to show more information, e.g. a confirmation message for a destructive action. | <code>string</code> |
| primaryAction | The primary Action the user can take. | <code>Alert.ActionOptions</code> |
| rememberUserChoice | If set to true, the Alert will also display a `Do not show this message again` checkbox. When checked, the answer is persisted and directly returned to the extension the next time the alert should be shown, without the user actually seeing the alert. | <code>boolean</code> |

### Alert.ActionOptions

The options to create an Alert Action.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of the action. | <code>string</code> |
| style | The style of the action. | <code>Alert.ActionStyle</code> |
| onAction | A callback called when the action is triggered. | <code>() => void</code> |

### Alert.ActionStyle

Defines the visual style of an Action of the Alert.

Use Alert.ActionStyle.Default for confirmations of a positive action.
Use Alert.ActionStyle.Destructive.

#### Enumeration members

| Name        | Value                                                    |
| :---------- | :------------------------------------------------------- |
| Default     |      |
| Destructive |  |
| Cancel      |       |


# HUD

When the user takes an action that has the side effect of closing Raycast (for example when copying something in the Clipboard, you can use a HUD to confirm that the action worked properly.



## API Reference

### showHUD

A HUD will automatically hide the main window and show a compact message at the bottom of the screen.

#### Signature

```typescript
async function showHUD(
  title: string,
  options?: { clearRootSearch?: boolean; popToRootType?: PopToRootType }
): Promise<void>;
```

#### Example

```typescript
import { showHUD } from "@raycast/api";

export default async function Command() {
  await showHUD("Hey there 👋");
}
```

`showHUD` closes the main window when called, so you can use the same options as `closeMainWindow`:

```typescript
import { PopToRootType, showHUD } from "@raycast/api";

export default async function Command() {
  await showHUD("Hey there 👋", { clearRootSearch: true, popToRootType: PopToRootType.Immediate });
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title that will be displayed in the HUD. | <code>string</code> |
| options | Can be used to control the behaviour after closing the main window. | <code>Object</code> |
| options.clearRootSearch | Clears the text in the root search bar and scrolls to the top | <code>boolean</code> |
| options.popToRootType | Defines the pop to root behavior (PopToRootType</code> |

#### Return

A Promise that resolves when the HUD is shown.


# Toast

When an asynchronous operation is happening or when an error is thrown, it's usually a good idea to keep the user informed about it. Toasts are made for that.

Additionally, Toasts can have some actions associated to the action they are about. For example, you could provide a way to cancel an asynchronous operation, undo an action, or copy the stack trace of an error.



## API Reference

### showToast

Creates and shows a Toast with the given options.

#### Signature

```typescript
async function showToast(options: Toast.Options): Promise<Toast>;
```

#### Example

```typescript
import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const success = false;

  if (success) {
    await showToast({ title: "Dinner is ready", message: "Pizza margherita" });
  } else {
    await showToast({
      style: Toast.Style.Failure,
      title: "Dinner isn't ready",
      message: "Pizza dropped on the floor",
    });
  }
}
```

When showing an animated Toast, you can later on update it:

```typescript
import { showToast, Toast } from "@raycast/api";
import { setTimeout } from "timers/promises";

export default async function Command() {
  const toast = await showToast({
    style: Toast.Style.Animated,
    title: "Uploading image",
  });

  try {
    // upload the image
    await setTimeout(1000);

    toast.style = Toast.Style.Success;
    toast.title = "Uploaded image";
  } catch (err) {
    toast.style = Toast.Style.Failure;
    toast.title = "Failed to upload image";
    if (err instanceof Error) {
      toast.message = err.message;
    }
  }
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options<mark style="color:red;">*</mark> | The options to customize the Toast. | <code>Alert.Options</code> |

#### Return

A Promise that resolves with the shown Toast. The Toast can be used to change or hide it.

## Types

### Toast

A Toast with a certain style, title, and message.

Use showToast to create and show a Toast.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| message<mark style="color:red;">*</mark> | An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset. | <code>string</code> |
| primaryAction<mark style="color:red;">*</mark> | The primary Action the user can take when hovering on the Toast. | <code>Alert.ActionOptions</code> |
| secondaryAction<mark style="color:red;">*</mark> | The secondary Action the user can take when hovering on the Toast. | <code>Alert.ActionOptions</code> |
| style<mark style="color:red;">*</mark> | The style of a Toast. | <code>Action.Style</code> |
| title<mark style="color:red;">*</mark> | The title of a Toast. Displayed on the top. | <code>string</code> |

#### Methods

| Name | Type                                | Description      |
| :--- | :---------------------------------- | :--------------- |
| hide | <code>() => Promise&lt;void></code> | Hides the Toast. |
| show | <code>() => Promise&lt;void></code> | Shows the Toast. |

### Toast.Options

The options to create a Toast.

#### Example

```typescript
import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const options: Toast.Options = {
    style: Toast.Style.Success,
    title: "Finished cooking",
    message: "Delicious pasta for lunch",
    primaryAction: {
      title: "Do something",
      onAction: (toast) => {
        console.log("The toast action has been triggered");
        toast.hide();
      },
    },
  };
  await showToast(options);
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of a Toast. Displayed on the top. | <code>string</code> |
| message | An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset. | <code>string</code> |
| primaryAction | The primary Action the user can take when hovering on the Toast. | <code>Alert.ActionOptions</code> |
| secondaryAction | The secondary Action the user can take when hovering on the Toast. | <code>Alert.ActionOptions</code> |
| style | The style of a Toast. | <code>Action.Style</code> |

### Toast.Style

Defines the visual style of the Toast.

Use Toast.Style.Success for displaying errors.
Use Toast.Style.Animated when your Toast should be shown until a process is completed.
You can hide it later by using Toast.hide or update the properties of an existing Toast.

#### Enumeration members

| Name     | Value                                          |
| :------- | :--------------------------------------------- |
| Animated |  |
| Success  |   |
| Failure  |   |

### Toast.ActionOptions

The options to create a Toast Action.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of the action. | <code>string</code> |
| onAction<mark style="color:red;">*</mark> | A callback called when the action is triggered. | <code>(toast: Toast => void</code> |
| shortcut | The keyboard shortcut for the action. | <code>Keyboard.Shortcut</code> |


# Keyboard

The Keyboard APIs are useful to make your actions accessible via the keyboard shortcuts. Shortcuts help users to use your command without touching the mouse.

## Types

### Keyboard.Shortcut

A keyboard shortcut is defined by one or more modifier keys (command, control, etc.) and a single key equivalent (a character or special key).

See KeyModifier for supported values.

#### Example

```typescript
import { Action, ActionPanel, Detail, Keyboard } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Let's play some games 👾"
      actions={
        <ActionPanel title="Game controls">
          <Action title="Up" shortcut={{ modifiers: ["opt"], key: "arrowUp" }} onAction={() => console.log("Go up")} />
          <Action
            title="Down"
            shortcut={{ modifiers: ["opt"], key: "arrowDown" }}
            onAction={() => console.log("Go down")}
          />
          <Action
            title="Left"
            shortcut={{ modifiers: ["opt"], key: "arrowLeft" }}
            onAction={() => console.log("Go left")}
          />
          <Action
            title="Right"
            shortcut={{ modifiers: ["opt"], key: "arrowRight" }}
            onAction={() => console.log("Go right")}
          />
          <Action title="Open" shortcut={Keyboard.Shortcut.Common.Open} onAction={() => console.log("Open")} />
        </ActionPanel>
      }
    />
  );
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| key<mark style="color:red;">*</mark> | The key of the keyboard shortcut. | <code>Keyboard.KeyEquivalent</code> |
| modifiers<mark style="color:red;">*</mark> | The modifier keys of the keyboard shortcut. | <code>Keyboard.KeyModifier[]</code> |

### Keyboard.Shortcut.Common

A collection of shortcuts that are commonly used throughout Raycast. Using them should help provide a more consistent experience and preserve muscle memory.

| Name            | Shortcut  |
| --------------- | --------- |
| Copy            | ⌘ + ⇧ + C |
| CopyDeeplink    | ⌘ + ⇧ + C |
| CopyName        | ⌘ + ⇧ + . |
| CopyPath        | ⌘ + ⇧ + , |
| Duplicate       | ⌘ + D     |
| Edit            | ⌘ + E     |
| MoveDown        | ⌘ + ⇧ + ↓ |
| MoveUp          | ⌘ + ⇧ + ↑ |
| New             | ⌘ + N     |
| Open            | ⌘ + O     |
| OpenWith        | ⌘ + ⇧ + O |
| Pin             | ⌘ + ⇧ + P |
| Refresh         | ⌘ + R     |
| Remove          | ⌃ + X     |
| RemoveAll       | ⌃ + ⇧ + X |
| ToggleQuickLook | ⌘ + Y     |

### Keyboard.KeyEquivalent

```typescript
KeyEquivalent: "a" |
  "b" |
  "c" |
  "d" |
  "e" |
  "f" |
  "g" |
  "h" |
  "i" |
  "j" |
  "k" |
  "l" |
  "m" |
  "n" |
  "o" |
  "p" |
  "q" |
  "r" |
  "s" |
  "t" |
  "u" |
  "v" |
  "w" |
  "x" |
  "y" |
  "z" |
  "0" |
  "1" |
  "2" |
  "3" |
  "4" |
  "5" |
  "6" |
  "7" |
  "8" |
  "9" |
  "." |
  "," |
  ";" |
  "=" |
  "+" |
  "-" |
  "[" |
  "]" |
  "{" |
  "}" |
  "«" |
  "»" |
  "(" |
  ")" |
  "/" |
  "\\" |
  "'" |
  "`" |
  "§" |
  "^" |
  "@" |
  "$" |
  "return" |
  "delete" |
  "deleteForward" |
  "tab" |
  "arrowUp" |
  "arrowDown" |
  "arrowLeft" |
  "arrowRight" |
  "pageUp" |
  "pageDown" |
  "home" |
  "end" |
  "space" |
  "escape" |
  "enter" |
  "backspace";
```

KeyEquivalent of a Shortcut

### Keyboard.KeyModifier

```typescript
KeyModifier: "cmd" | "ctrl" | "opt" | "shift";
```

Modifier of a Shortcut


# Menu Bar Commands

The `MenuBarExtra` component can be used to create commands which populate the [extras](https://developer.apple.com/design/human-interface-guidelines/components/system-experiences/the-menu-bar#menu-bar-commands) section of macOS' menu bar.

## Getting Started

If you don't have an extension yet, follow the getting started guide and then return to this page.
Now that your extension is ready, let's open its `package.json` file and add a new entry to its `commands` array, ensuring its `mode` property is set to `menu-bar`. For this guide, let's add the following:

```JSON
{
  "name": "github-pull-requests",
  "title": "Pull Requests",
  "subtitle": "GitHub",
  "description": "See your GitHub pull requests at a glance",
  "mode": "menu-bar"
},
```

{% hint style="info" %}
Check out the command properties entry in the manifest file documentation for more detailed information on each of those properties.
{% endhint %}

Create `github-pull-requests.tsx` in your extensions `src/` folder and add the following:

```typescript
import { MenuBarExtra } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon="https://github.githubassets.com/favicons/favicon.png" tooltip="Your Pull Requests">
      <MenuBarExtra.Item title="Seen" />
      <MenuBarExtra.Item
        title="Example Seen Pull Request"
        onAction={() => {
          console.log("seen pull request clicked");
        }}
      />
      <MenuBarExtra.Item title="Unseen" />
      <MenuBarExtra.Item
        title="Example Unseen Pull Request"
        onAction={() => {
          console.log("unseen pull request clicked");
        }}
      />
    </MenuBarExtra>
  );
}
```

If your development server is running, the command should appear in your root search, and running the command should result in the `GitHub` icon appearing in your menu bar.



{% hint style="info" %}
macOS has the final say on whether a given menu bar extra is displayed. If you have a lot of items there, it is possible that the command we just ran doesn't show up. If that's the case, try to clear up some space in the menu bar, either by closing some of the items you don't need or by hiding them using [HiddenBar](https://github.com/dwarvesf/hidden), [Bartender](https://www.macbartender.com/), or similar apps.
{% endhint %}

Of course, our pull request command wouldn't be of that much use if we had to tell it to update itself every single time. To add background refresh to our command, we need to open the `package.json` file we modified earlier and add an `interval` key to the command configuration object:

```JSON
{
  "name": "github-pull-requests",
  "title": "Pull Requests",
  "subtitle": "GitHub",
  "description": "See your GitHub pull requests at a glance",
  "mode": "menu-bar",
  "interval": "5m"
}
```

Your root search should look similar to:



Running it once should activate it to:



## Lifecycle

Although `menu-bar` commands can result in items permanently showing up in the macOS menu bar, they are not long-lived processes. Instead, as with other commands, Raycast loads them into memory on demand, executes their code and then tries to unload them at the next convenient time.
There are five distinct events that can result in a `menu-bar`'s item being placed in the menu bar, so let's walk through each one.

### From the root search

Same as any other commands, `menu-bar` commands can be run directly from Raycast's root search. Eventually, they may result in a new item showing up in your menu bar (if you have enough room and if the command returns a `MenuBarExtra`), or in a previous item disappearing, if the command returns `null`. In this case, Raycast will load your command code, execute it, wait for the `MenuBarExtra`'s `isLoading` prop to switch to `false`, and unload the command.

{% hint style="danger" %}
If your command returns a `MenuBarExtra`, it _must_ either not set `isLoading` - in which case Raycast will render and immediately unload the command, or set it to `true` while it's performing an async task (such as an API call) and then set it to `false` once it's done. Same as above, Raycast will load the command code, execute it, wait for `MenuBarExtra`'s `isLoading` prop to switch to `false`, and then unload the command.
{% endhint %}

### At a set interval

If your `menu-bar` command also makes use of background refresh _and_ it has background refresh activated, Raycast will run the command at set intervals. In your command, you can use `environment.launchType` to check whether it is launched in the background or by the user.

{% hint style="info" %}
To ease testing, commands configured to run in the background have an extra action in development mode:

{% endhint %}

### When the user clicks the command's icon / title in the menu bar

One of the bigger differences to `view` or `no-view` commands is that `menu-bar` commands have an additional entry point: when the user clicks their item in the menu bar. If the item has a menu (i.e. `MenuBarExtra` provides at least one child), Raycast will load the command code, execute it and keep it in memory while the menu is open. When the menu closes (either by the user clicking outside, or by clicking a `MenuBarExtra.Item`), the command is then unloaded.

### When Raycast is restarted

This case assumes that your command has run at least once, resulting in an item being placed in the menu bar. If that's the case, quitting and starting Raycast again should put the same item in your menu bar. However, that item will be restored from Raycast's database - _not_ by loading and executing the command.

### When a menu bar command is re-enabled in preferences

This case should work the same as when Raycast is restarted.

## Best practices

- make generous use of the Cache API in order to provide quick feedback and ensure action handlers work as expected
- make sure you set `isLoading` to false when your command finishes executing
- avoid setting long titles in `MenuBarExtra`, `MenuBarExtra.Submenu` or `MenuBarExtra.Item`
- don't put identical `MenuBarExtra.Item`s at the same level (direct children of `MenuBarExtra` or in the same `Submenu`) as their `onAction` handlers will not be executed correctly

## API Reference

### MenuBarExtra

Adds an item to the menu bar, optionally with a menu attached in case its `children` prop is non-empty.

{% hint style="info" %}
`menu-bar` commands don't always need to return a `MenuBarExtra`. Sometimes it makes sense to remove an item from the menu bar, in which case you can write your command logic to return `null` instead.
{% endhint %}

#### Example

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

const data = {
  archivedBookmarks: [{ name: "Google Search", url: "www.google.com" }],
  newBookmarks: [{ name: "Raycast", url: "www.raycast.com" }],
};

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Section title="New">
        {data?.newBookmarks.map((bookmark) => (
          <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
        ))}
      </MenuBarExtra.Section>
      <MenuBarExtra.Section title="Archived">
        {data?.archivedBookmarks.map((bookmark) => (
          <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
        ))}
      </MenuBarExtra.Section>
    </MenuBarExtra>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either. | <code>React.ReactNode</code> | - |
| icon | The icon that is displayed in the menu bar. | <code>Image.ImageLike</code> | - |
| isLoading | Indicates to Raycast that it should not unload the command, as it is still executing. If you set make use of `isLoading`, you need to make sure you set it to `false` at the end of the task you are executing (such as an API call), so Raycast can then unload the command. | <code>boolean</code> | `false` |
| title | The string that is displayed in the menu bar. | <code>string</code> | - |
| tooltip | A tooltip to display when the cursor hovers the item in the menu bar. | <code>string</code> | - |

### MenuBarExtra.Item

An item in the MenuBarExtra.

#### Example

{% tabs %}

{% tab title="ItemWithTitle.tsx" %}

An item that only provides a `title` prop will be rendered as disabled. Use this to create section titles.

```typescript
import { Icon, MenuBarExtra } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Item title="Raycast.com" />
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% tab title="ItemWithTitleAndIcon.tsx" %}

Similarly, an item that provides a `title` and an `icon` prop will also be rendered as disabled.

```typescript
import { Icon, MenuBarExtra } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Item icon="raycast.png" title="Raycast.com" />
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% tab title="ItemWithAction.tsx" %}

An item that provides an `onAction` prop alongside `title` (and optionally `icon`) will _not_ be rendered as disabled. When users click this item in the menu bar, the action handler will be executed.

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Item icon="raycast.png" title="Raycast.com" onAction={() => open("https://raycast.com")} />
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% tab title="ItemWithAlternate.tsx" %}

If an item provides another `MenuBarEtra.Item` via its `alternate`, prop, the second item will be shown then the user presses the ⌥ (opt) key. There are a few limitation:

1. The `alternate` item may not have a custom shortcut. Instead, it will inherit its parent's shortcut, with the addition of ⌥ (opt) as a modifier.
2. The `alternate` item may not also specify an alternate.
3. A parent item that provides an `alternate` may not use ⌥ (opt) as a modifier.

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Item
        icon="raycast.png"
        title="Open Raycast Homepage"
        shortcut={{ key: "r", modifiers: ["cmd"] }}
        onAction={() => open("https://raycast.com")}
        alternate={
          <MenuBarExtra.Item
            icon="raycast.png"
            title="Open Raycast Store"
            onAction={() => open("https://raycast.com/store")}
          />
        }
      />
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The main title displayed for this item. | <code>string</code> | - |
| alternate | A MenuBarExtra.Item, string></code> | - |
| icon | An optional icon for this item. | <code>Image.ImageLike</code> | - |
| shortcut | A shortcut used to invoke this item when its parent menu is open. | <code>Keyboard.Shortcut</code> | - |
| subtitle | The subtitle displayed for this item. | <code>string</code> | - |
| tooltip | A tooltip to display when the cursor hovers the item. | <code>string</code> | - |
| onAction | An action handler called when the user clicks the item. | <code>(event: MenuBarExtra.ActionEvent => void</code> | - |

### MenuBarExtra.Submenu

`MenuBarExtra.Submenu`s reveal their items when people interact with them. They're a good way to group items that naturally belong together, but keep in mind that submenus add complexity to your interface - so use them sparingly!

#### Example

{% tabs %}

{% tab title="Bookmarks.tsx" %}

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Item icon="raycast.png" title="Raycast.com" onAction={() => open("https://raycast.com")} />
      <MenuBarExtra.Submenu icon="github.png" title="GitHub">
        <MenuBarExtra.Item title="Pull Requests" onAction={() => open("https://github.com/pulls")} />
        <MenuBarExtra.Item title="Issues" onAction={() => open("https://github.com/issues")} />
      </MenuBarExtra.Submenu>
      <MenuBarExtra.Submenu title="Disabled"></MenuBarExtra.Submenu>
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% tab title="DisabledSubmenu.tsx" %}

Submenus with no children will show up as disabled.

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Submenu title="Disabled"></MenuBarExtra.Submenu>
    </MenuBarExtra>
  );
}
```

{% endtab %}

{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The main title displayed for this submenu. | <code>string</code> | - |
| children | `MenuBarExtra.Item`s, `MenuBarExtra.Submenu`s, `MenuBarExtra.Separator` or a mix of either. | <code>React.ReactNode</code> | - |
| icon | An optional icon for this submenu. | <code>Image.ImageLike</code> | - |

### MenuBarExtra.Section

An item to group related menu items. It has an optional title and a separator is added automatically between sections.

#### Example

```typescript
import { Icon, MenuBarExtra, open } from "@raycast/api";

const data = {
  archivedBookmarks: [{ name: "Google Search", url: "www.google.com" }],
  newBookmarks: [{ name: "Raycast", url: "www.raycast.com" }],
};

export default function Command() {
  return (
    <MenuBarExtra icon={Icon.Bookmark}>
      <MenuBarExtra.Section title="New">
        {data?.newBookmarks.map((bookmark) => (
          <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
        ))}
      </MenuBarExtra.Section>
      <MenuBarExtra.Section title="Archived">
        {data?.archivedBookmarks.map((bookmark) => (
          <MenuBarExtra.Item key={bookmark.url} title={bookmark.name} onAction={() => open(bookmark.url)} />
        ))}
      </MenuBarExtra.Section>
    </MenuBarExtra>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | The item elements of the section. | <code>React.ReactNode</code> | - |
| title | Title displayed above the section | <code>string</code> | - |

## Types

### MenuBarExtra.ActionEvent

An interface describing Action events in callbacks.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| type<mark style="color:red;">*</mark> | A type of the action event | <code>"left-click"</code> or <code>"right-click"</code> |

#### Example

```typescript
import { MenuBarExtra } from "@raycast/api";

export default function Command() {
  return (
    <MenuBarExtra>
      <MenuBarExtra.Item
        title="Log Action Event Type"
        onAction={(event: MenuBarExtra.ActionEvent) => console.log("Action Event Type", event.type)}
      />
    </MenuBarExtra>
  );
}
```


# OAuth

## Prerequisites

A Raycast extension can use OAuth for authorizing access to a provider's resources on the user's behalf. Since Raycast is a desktop app and the extensions are considered "public", we only support the [PKCE flow](https://datatracker.ietf.org/doc/html/rfc7636) (Proof Key for Code Exchange, pronounced “pixy”). This flow is the official recommendation for native clients that cannot keep a client secret. With PKCE, the client dynamically creates a secret and uses the secret again during code exchange, ensuring that only the client that performed the initial request can exchange the code for the access token (”proof of possession”).

{% hint style="info" %}
Providers such as Google, Twitter, GitLab, Spotify, Zoom, Asana or Dropbox are all PKCE-ready.

However, if your provider doesn't support PKCE, you can use our [PKCE proxy](https://oauth.raycast.com). It allows extensions to securely use an OAuth flow without exposing any secret.
{% endhint %}

## OAuth Flow



The OAuth flow from an extension looks like this:

1. The extension initiates the OAuth flow and starts authorization
2. Raycast shows the OAuth overlay ("Connect to provider…")
3. The user opens the provider's consent page in the web browser
4. After the user consent, the provider redirects back to Raycast
5. Raycast opens the extension where authorization is completed

When the flow is complete, the extension has received an access token from the provider and can perform API calls.
The API provides functions for securely storing and retrieving token sets, so that an extension can check whether the user is already logged in and whether an expired access token needs to be refreshed. Raycast also automatically shows a logout preference.



## OAuth App

You first need to register a new OAuth app with your provider. This is usually done in the provider's developer portal. After registering, you will receive a client ID. You also need to configure a redirect URI, see the next section.

Note: Make sure to choose an app type that supports PKCE. Some providers still show you a client secret, which you don't need and should _not_ hardcode in the extension, or support PKCE only for certain types such as "desktop", "native" or "mobile" app types.

## Authorizing

An extension can initiate the OAuth flow and authorize by using the methods on OAuth.PKCEClient.

You can create a new client and configure it with a provider name, icon and description that will be shown in the OAuth overlay. You can also choose between different redirect methods; depending on which method you choose, you need to configure this value as redirect URI in your provider's registered OAuth app. (See the OAuth.RedirectMethod.

```typescript
import { OAuth } from "@raycast/api";

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "Twitter",
  providerIcon: "twitter-logo.png",
  description: "Connect your Twitter account…",
});
```

Next you create an authorization request with the authorization endpoint, client ID, and scope values. You receive all values from your provider's docs and when you register a new OAuth app.

The returned AuthorizationRequest if you need to.

```typescript
const authRequest = await client.authorizationRequest({
  endpoint: "https://twitter.com/i/oauth2/authorize",
  clientId: "YourClientId",
  scope: "tweet.read users.read follows.read",
});
```

To get the authorization code needed for the token exchange, you call authorize with the request from the previous step.
This call shows the Raycast OAuth overlay and provides the user with an option to open the consent page in the web browser.
The authorize promise is resolved after the redirect back to Raycast and into the extension:

```typescript
const { authorizationCode } = await client.authorize(authRequest);
```

{% hint style="info" %}
When in development mode, make sure not to trigger auto-reloading (e.g. by saving a file) while you're testing an active OAuth authorization and redirect. This would cause an OAuth state mismatch when you're redirected back into the extension since the client would be reinitialized on reload.
{% endhint %}

Now that you have received the authorization code, you can exchange this code for an access token using your provider's token endpoint. This token exchange (and the following API calls) can be done with your preferred Node HTTP client library. Example using `node-fetch`:

```typescript
async function fetchTokens(authRequest: OAuth.AuthorizationRequest, authCode: string): Promise<OAuth.TokenResponse> {
  const params = new URLSearchParams();
  params.append("client_id", "YourClientId");
  params.append("code", authCode);
  params.append("code_verifier", authRequest.codeVerifier);
  params.append("grant_type", "authorization_code");
  params.append("redirect_uri", authRequest.redirectURI);

  const response = await fetch("https://api.twitter.com/2/oauth2/token", {
    method: "POST",
    body: params,
  });
  if (!response.ok) {
    console.error("fetch tokens error:", await response.text());
    throw new Error(response.statusText);
  }
  return (await response.json()) as OAuth.TokenResponse;
}
```

## Token Storage

The PKCE client exposes methods for storing, retrieving and deleting token sets. A TokenSet:

```typescript
await client.setTokens(tokenResponse);
```

Once the token set is stored, Raycast will automatically show a logout preference for the extension. When the user logs out, the token set gets removed.

The TokenSet also enables you to check whether the user is logged in before starting the authorization flow:

```typescript
const tokenSet = await client.getTokens();
```

## Token Refresh

Since access tokens usually expire, an extension should provide a way to refresh the access token, otherwise users would be logged out or see errors.
Some providers require you to add an offline scope so that you get a refresh token. (Twitter, for example, needs the scope `offline.access` or it only returns an access token.)
A basic refresh flow could look like this:

```typescript
const tokenSet = await client.getTokens();
if (tokenSet?.accessToken) {
  if (tokenSet.refreshToken && tokenSet.isExpired()) {
    await client.setTokens(await refreshTokens(tokenSet.refreshToken));
  }
  return;
}
// authorize...
```

This code would run before starting the authorization flow. It checks the presence of a token set to see whether the user is logged in and then checks whether there is a refresh token and the token set is expired (through the convenience method `isExpired()` on the TokenSet. If it is expired, the token is refreshed and updated in the token set. Example using `node-fetch`:

```typescript
async function refreshTokens(refreshToken: string): Promise<OAuth.TokenResponse> {
  const params = new URLSearchParams();
  params.append("client_id", "YourClientId");
  params.append("refresh_token", refreshToken);
  params.append("grant_type", "refresh_token");

  const response = await fetch("https://api.twitter.com/2/oauth2/token", {
    method: "POST",
    body: params,
  });
  if (!response.ok) {
    console.error("refresh tokens error:", await response.text());
    throw new Error(response.statusText);
  }

  const tokenResponse = (await response.json()) as OAuth.TokenResponse;
  tokenResponse.refresh_token = tokenResponse.refresh_token ?? refreshToken;
  return tokenResponse;
}
```

## Examples

We've provided [OAuth example integrations for Google, Twitter, and Dropbox](https://github.com/raycast/extensions/tree/main/examples/api-examples) that demonstrate the entire flow shown above.

## API Reference

### OAuth.PKCEClient

Use OAuth.PKCEClient.Options to configure what's shown on the OAuth overlay.

#### Signature

```typescript
constructor(options: OAuth.PKCEClient.Options): OAuth.PKCEClient
```

#### Example

```typescript
import { OAuth } from "@raycast/api";

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "Twitter",
  providerIcon: "twitter-logo.png",
  description: "Connect your Twitter account…",
});
```

#### Methods

| Method                                                                                                                                           |
| :----------------------------------------------------------------------------------------------------------------------------------------------- |
| <code>authorizationRequest(options: AuthorizationRequestOptions): Promise<AuthorizationRequest></code> |
| <code>authorize(options: AuthorizationRequest \| AuthorizationOptions): Promise<AuthorizationResponse></code>     |
| <code>setTokens(options: TokenSetOptions \| TokenResponse): Promise<void></code>                                  |
| <code>getTokens(): Promise<TokenSet \| undefined></code>                                                          |
| <code>removeTokens(): Promise<void></code>                                                                     |

### OAuth.PKCEClient#authorizationRequest

Creates an authorization request for the provided authorization endpoint, client ID, and scopes. You need to first create the authorization request before calling authorize.

The generated code challenge for the PKCE request uses the S256 method.

#### Signature

```typescript
authorizationRequest(options: AuthorizationRequestOptions): Promise<AuthorizationRequest>;
```

#### Example

```typescript
const authRequest = await client.authorizationRequest({
  endpoint: "https://twitter.com/i/oauth2/authorize",
  clientId: "YourClientId",
  scope: "tweet.read users.read follows.read",
});
```

#### Parameters

| Name                                      | Type                                                                           | Description                                           |
| :---------------------------------------- | :----------------------------------------------------------------------------- | :---------------------------------------------------- |
| options<mark style="color:red;">\*</mark> | <code>AuthorizationRequestOptions</code> | The options used to create the authorization request. |

#### Return

A promise for an AuthorizationRequest.

### OAuth.PKCEClient#authorize

Starts the authorization and shows the OAuth overlay in Raycast. As parameter you can either directly use the returned request from authorizationRequest. Eventually the URL will be used to open the authorization page of the provider in the web browser.

#### Signature

```typescript
authorize(options: AuthorizationRequest | AuthorizationOptions): Promise<AuthorizationResponse>;
```

#### Example

```typescript
const { authorizationCode } = await client.authorize(authRequest);
```

#### Parameters

| Name                                      | Type                                                                                                                    | Description                    |
| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| options<mark style="color:red;">\*</mark> | <code>AuthorizationRequest</code> | The options used to authorize. |

#### Return

A promise for an AuthorizationResponse, which contains the authorization code needed for the token exchange. The promise is resolved when the user was redirected back from the provider's authorization page to the Raycast extension.

### OAuth.PKCEClient#setTokens

Securely stores a TokenSet.
At a minimum, you need to set the `accessToken`, and typically you also set `refreshToken` and `isExpired`.

Raycast automatically shows a logout preference for the extension when a token set was saved.

If you want to make use of the convenience `isExpired()` method, the property `expiresIn` must be configured.

#### Signature

```typescript
setTokens(options: TokenSetOptions | TokenResponse): Promise<void>;
```

#### Example

```typescript
await client.setTokens(tokenResponse);
```

#### Parameters

| Name                                      | Type                                                                                            | Description                              |
| :---------------------------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------- |
| options<mark style="color:red;">\*</mark> | <code>TokenSetOptions</code> | The options used to store the token set. |

#### Return

A promise that resolves when the token set has been stored.

### OAuth.PKCEClient#getTokens

Retrieves the stored TokenSet for the client. You can use this to initially check whether the authorization flow should be initiated or the user is already logged in and you might have to refresh the access token.

#### Signature

```typescript
getTokens(): Promise<TokenSet | undefined>;
```

#### Example

```typescript
const tokenSet = await client.getTokens();
```

#### Return

A promise that resolves when the token set has been retrieved.

### OAuth.PKCEClient#removeTokens

Removes the stored TokenSet for the client.
Raycast automatically shows a logout preference that removes the token set. Use this method only if you need to provide an additional logout option in your extension or you want to remove the token set because of a migration.

#### Signature

```typescript
removeTokens(): Promise<void>;
```

#### Example

```typescript
await client.removeTokens();
```

#### Return

A promise that resolves when the token set has been removed.

## Types

### OAuth.PKCEClient.Options

The options for creating a new PKCEClient.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| providerName<mark style="color:red;">*</mark> | The name of the provider, displayed in the OAuth overlay. | <code>string</code> |
| redirectMethod<mark style="color:red;">*</mark> | The redirect method for the OAuth flow. Make sure to set this to the correct method for the provider, see OAuth.RedirectMethod</code> |
| description | An optional description, shown in the OAuth overlay. You can use this to customize the message for the end user, for example for handling scope changes or other migrations. Raycast shows a default message if this is not configured. | <code>string</code> |
| providerIcon | An icon displayed in the OAuth overlay. Make sure to provide at least a size of 64x64 pixels. | <code>Image.ImageLike</code> |
| providerId | An optional ID for associating the client with a provider. Only set this if you use multiple different clients in your extension. | <code>string</code> |

### OAuth.RedirectMethod

Defines the supported redirect methods for the OAuth flow. You can choose between web and app-scheme redirect methods, depending on what the provider requires when setting up the OAuth app. For examples on what redirect URI you need to configure, see the docs for each method.

#### Enumeration members

| Name   | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web    | Use this type for a redirect back to the Raycast website, which will then open the extension. In the OAuth app, configure `https://raycast.com/redirect?packageName=Extension`<br>(This is a static redirect URL for all extensions.)<br>If the provider does not accept query parameters in redirect URLs, you can alternatively use `https://raycast.com/redirect/extension` and then customize the AuthorizationRequest via its `extraParameters` property. For example add: `extraParameters: { "redirect_uri": "https://raycast.com/redirect/extension" }` |
| App    | Use this type for an app-scheme based redirect that directly opens Raycast. In the OAuth app, configure `raycast://oauth?package_name=Extension`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| AppURI | Use this type for a URI-style app scheme that directly opens Raycast. In the OAuth app, configure `com.raycast:/oauth?package_name=Extension`<br>(Note the single slash – Google, for example, would require this flavor for an OAuth app where the Bundle ID is `com.raycast`)                                                                                                                                                                                                                                                                                                                |

### OAuth.AuthorizationRequestOptions

The options for an authorization request via authorizationRequest.

| Property | Description | Type |
| :--- | :--- | :--- |
| clientId<mark style="color:red;">*</mark> | The client ID of the configured OAuth app. | <code>string</code> |
| endpoint<mark style="color:red;">*</mark> | The URL to the authorization endpoint for the OAuth provider. | <code>string</code> |
| scope<mark style="color:red;">*</mark> | A space-delimited list of scopes for identifying the resources to access on the user's behalf. The scopes are typically shown to the user on the provider's consent screen in the browser. Note that some providers require the same scopes be configured in the registered OAuth app. | <code>string</code> |
| extraParameters | Optional additional parameters for the authorization request. Note that some providers require additional parameters, for example to obtain long-lived refresh tokens. | <code>Record&lt;string, string></code> |

### OAuth.AuthorizationRequestURLParams

Values of AuthorizationRequest.
The PKCE client automatically generates the values for you and returns them for authorizationRequest

| Property | Description | Type |
| :--- | :--- | :--- |
| codeChallenge<mark style="color:red;">*</mark> | The PKCE `code_challenge` value. | <code>string</code> |
| codeVerifier<mark style="color:red;">*</mark> | The PKCE `code_verifier` value. | <code>string</code> |
| redirectURI<mark style="color:red;">*</mark> | The OAuth `redirect_uri` value. | <code>string</code> |
| state<mark style="color:red;">*</mark> | The OAuth `state` value. | <code>string</code> |

### OAuth.AuthorizationRequest

The request returned by authorizationRequest.
Can be used as direct input to authorize.

| Property | Description | Type |
| :--- | :--- | :--- |
| codeChallenge<mark style="color:red;">*</mark> | The PKCE `code_challenge` value. | <code>string</code> |
| codeVerifier<mark style="color:red;">*</mark> | The PKCE `code_verifier` value. | <code>string</code> |
| redirectURI<mark style="color:red;">*</mark> | The OAuth `redirect_uri` value. | <code>string</code> |
| state<mark style="color:red;">*</mark> | The OAuth `state` value. | <code>string</code> |
| toURL<mark style="color:red;">*</mark> | Constructs the full authorization URL. | <code>() => string</code> |

#### Methods

| Name    | Type                      | Description                            |
| :------ | :------------------------ | :------------------------------------- |
| toURL() | <code>() => string</code> | Constructs the full authorization URL. |

### OAuth.AuthorizationOptions

Options for customizing authorize.
You can use values from AuthorizationRequest to build your own URL.

| Property | Description | Type |
| :--- | :--- | :--- |
| url<mark style="color:red;">*</mark> | The full authorization URL. | <code>string</code> |

### OAuth.AuthorizationResponse

The response returned by authorize, containing the authorization code after the provider redirect. You can then exchange the authorization code for an access token using the provider's token endpoint.

| Property | Description | Type |
| :--- | :--- | :--- |
| authorizationCode<mark style="color:red;">*</mark> | The authorization code from the OAuth provider. | <code>string</code> |

### OAuth.TokenSet

Describes the TokenSet created from an OAuth provider's token response. The `accessToken` is the only required parameter but typically OAuth providers also return a refresh token, an expires value, and the scope.
Securely store a token set via setTokens.

| Property | Description | Type |
| :--- | :--- | :--- |
| accessToken<mark style="color:red;">*</mark> | The access token returned by an OAuth token request. | <code>string</code> |
| updatedAt<mark style="color:red;">*</mark> | The date when the token set was stored via OAuth.PKCEClient.setTokens. | <code>Date</code> |
| isExpired<mark style="color:red;">*</mark> | A convenience method for checking whether the access token has expired. The method factors in some seconds of "buffer", so it returns true a couple of seconds before the actual expiration time. This requires the `expiresIn` parameter to be set. | <code>() => boolean</code> |
| expiresIn | An optional expires value (in seconds) returned by an OAuth token request. | <code>number</code> |
| idToken | An optional id token returned by an identity request (e.g. /me, Open ID Connect). | <code>string</code> |
| refreshToken | An optional refresh token returned by an OAuth token request. | <code>string</code> |
| scope | The optional space-delimited list of scopes returned by an OAuth token request. You can use this to compare the currently stored access scopes against new access scopes the extension might require in a future version, and then ask the user to re-authorize with new scopes. | <code>string</code> |

#### Methods

| Name        | Type                       | Description                                                                                                                                                                                                                                          |
| :---------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| isExpired() | <code>() => boolean</code> | A convenience method for checking whether the access token has expired. The method factors in some seconds of "buffer", so it returns true a couple of seconds before the actual expiration time. This requires the `expiresIn` parameter to be set. |

### OAuth.TokenSetOptions

Options for a TokenSet.

| Property | Description | Type |
| :--- | :--- | :--- |
| accessToken<mark style="color:red;">*</mark> | The access token returned by an OAuth token request. | <code>string</code> |
| expiresIn | An optional expires value (in seconds) returned by an OAuth token request. | <code>number</code> |
| idToken | An optional id token returned by an identity request (e.g. /me, Open ID Connect). | <code>string</code> |
| refreshToken | An optional refresh token returned by an OAuth token request. | <code>string</code> |
| scope | The optional scope value returned by an OAuth token request. | <code>string</code> |

### OAuth.TokenResponse

Defines the standard JSON response for an OAuth token request.
The response can be directly used to store a TokenSet.

| Property | Description | Type |
| :--- | :--- | :--- |
| access_token<mark style="color:red;">*</mark> | The `access_token` value returned by an OAuth token request. | <code>string</code> |
| expires_in | An optional `expires_in` value (in seconds) returned by an OAuth token request. | <code>number</code> |
| id_token | An optional `id_token` value returned by an identity request (e.g. /me, Open ID Connect). | <code>string</code> |
| refresh_token | An optional `refresh_token` value returned by an OAuth token request. | <code>string</code> |
| scope | The optional `scope` value returned by an OAuth token request. | <code>string</code> |


# Preferences

Use the Preferences API to make your extension configurable.

Preferences are configured in the manifest per command or shared in the context of an extension.

Required preferences need to be set by the user before a command opens. They are a great way to make sure that the user of your extension has everything set up properly.

## API Reference

### getPreferenceValues

A function to access the preference values that have been passed to the command.

Each preference name is mapped to its value, and the defined default values are used as fallback values.

#### Signature

```typescript
function getPreferenceValues(): { [preferenceName: string]: any };
```

#### Example

```typescript
import { getPreferenceValues } from "@raycast/api";

interface Preferences {
  name: string;
  bodyWeight?: string;
  bodyHeight?: string;
}

export default async function Command() {
  const preferences = getPreferenceValues<Preferences>();
  console.log(preferences);
}
```

#### Return

An object with the preference names as property key and the typed value as property value.

Depending on the type of the preference, the type of its value will be different.

| Preference type        | Value type                                             |
| :--------------------- | :----------------------------------------------------- |
| <code>textfield</code> | <code>string</code>                                    |
| <code>password</code>  | <code>string</code>                                    |
| <code>checkbox</code>  | <code>boolean</code>                                   |
| <code>dropdown</code>  | <code>string</code>                                    |
| <code>appPicker</code> | <code>Application</code> |
| <code>file</code>      | <code>string</code>                                    |
| <code>directory</code> | <code>string</code>                                    |

### openExtensionPreferences

Opens the extension's preferences screen.

#### Signature

```typescript
export declare function openExtensionPreferences(): Promise<void>;
```

#### Example

```typescript
import { ActionPanel, Action, Detail, openExtensionPreferences } from "@raycast/api";

export default function Command() {
  const markdown = "API key incorrect. Please update it in extension preferences and try again.";

  return (
    <Detail
      markdown={markdown}
      actions={
        <ActionPanel>
          <Action title="Open Extension Preferences" onAction={openExtensionPreferences} />
        </ActionPanel>
      }
    />
  );
}
```

#### Return

A Promise that resolves when the extensions preferences screen is opened.

### openCommandPreferences

Opens the command's preferences screen.

#### Signature

```typescript
export declare function openCommandPreferences(): Promise<void>;
```

#### Example

```typescript
import { ActionPanel, Action, Detail, openCommandPreferences } from "@raycast/api";

export default function Command() {
  const markdown = "API key incorrect. Please update it in command preferences and try again.";

  return (
    <Detail
      markdown={markdown}
      actions={
        <ActionPanel>
          <Action title="Open Extension Preferences" onAction={openCommandPreferences} />
        </ActionPanel>
      }
    />
  );
}
```

#### Return

A Promise that resolves when the command's preferences screen is opened.

## Types

### Preferences

A command receives the values of its preferences via the `getPreferenceValues` function. It is an object with the preferences' `name` as keys and their values as the property's values.

Depending on the type of the preference, the type of its value will be different.

| Preference type        | Value type                                             |
| :--------------------- | :----------------------------------------------------- |
| <code>textfield</code> | <code>string</code>                                    |
| <code>password</code>  | <code>string</code>                                    |
| <code>checkbox</code>  | <code>boolean</code>                                   |
| <code>dropdown</code>  | <code>string</code>                                    |
| <code>appPicker</code> | <code>Application</code> |
| <code>file</code>      | <code>string</code>                                    |
| <code>directory</code> | <code>string</code>                                    |

{% hint style="info" %}
Raycast provides a global TypeScript namespace called `Preferences` which contains the types of the preferences of all the commands of the extension.

For example, if a command named `show-todos` has some preferences, its `getPreferenceValues`'s return type can be specified with `getPreferenceValues<Preferences.ShowTodos>()`. This will make sure that the types used in the command stay in sync with the manifest.
{% endhint %}


# Storage

The storage APIs can be used to store data in Raycast's local encrypted database.

All commands in an extension have shared access to the stored data. Extensions can _not_ access the storage of other extensions.

Values can be managed through functions such as `LocalStorage.getItem`. A typical use case is storing user-related data, for example entered todos.

{% hint style="info" %}
The API is not meant to store large amounts of data. For this, use [Node's built-in APIs to write files](https://nodejs.org/en/learn/manipulating-files/writing-files-with-nodejs), e.g. to the extension's support directory.
{% endhint %}

## API Reference

### LocalStorage.getItem

Retrieve the stored value for the given key.

#### Signature

```typescript
async function getItem(key: string): Promise<Value | undefined>;
```

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

export default async function Command() {
  await LocalStorage.setItem("favorite-fruit", "apple");
  const item = await LocalStorage.getItem<string>("favorite-fruit");
  console.log(item);
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| key<mark style="color:red;">*</mark> | The key you want to retrieve the value of. | <code>string</code> |

#### Return

A Promise that resolves with the stored value for the given key. If the key does not exist, `undefined` is returned.

### LocalStorage.setItem

Stores a value for the given key.

#### Signature

```typescript
async function setItem(key: string, value: Value): Promise<void>;
```

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

export default async function Command() {
  await LocalStorage.setItem("favorite-fruit", "apple");
  const item = await LocalStorage.getItem<string>("favorite-fruit");
  console.log(item);
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| key<mark style="color:red;">*</mark> | The key you want to create or update the value of. | <code>string</code> |
| value<mark style="color:red;">*</mark> | The value you want to create or update for the given key. | <code>LocalStorage.Value</code> |

#### Return

A Promise that resolves when the value is stored.

### LocalStorage.removeItem

Removes the stored value for the given key.

#### Signature

```typescript
async function removeItem(key: string): Promise<void>;
```

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

export default async function Command() {
  await LocalStorage.setItem("favorite-fruit", "apple");
  console.log(await LocalStorage.getItem<string>("favorite-fruit"));
  await LocalStorage.removeItem("favorite-fruit");
  console.log(await LocalStorage.getItem<string>("favorite-fruit"));
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| key<mark style="color:red;">*</mark> | The key you want to remove the value of. | <code>string</code> |

#### Return

A Promise that resolves when the value is removed.

### LocalStorage.allItems

Retrieve all stored values in the local storage of an extension.

#### Signature

```typescript
async function allItems(): Promise<Values>;
```

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

interface Values {
  todo: string;
  priority: number;
}

export default async function Command() {
  const items = await LocalStorage.allItems<Values>();
  console.log(`Local storage item count: ${Object.entries(items).length}`);
}
```

#### Return

A Promise that resolves with an object containing all Values.

### LocalStorage.clear

Removes all stored values of an extension.

#### Signature

```typescript
async function clear(): Promise<void>;
```

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

export default async function Command() {
  await LocalStorage.clear();
}
```

#### Return

A Promise that resolves when all values are removed.

## Types

### LocalStorage.Values

Values of local storage items.

For type-safe values, you can define your own interface. Use the keys of the local storage items as the property names.

#### Properties

| Name          | Type             | Description                             |
| :------------ | :--------------- | :-------------------------------------- |
| [key: string] | <code>any</code> | The local storage value of a given key. |

### LocalStorage.Value

```typescript
Value: string | number | boolean;
```

Supported storage value types.

#### Example

```typescript
import { LocalStorage } from "@raycast/api";

export default async function Command() {
  // String
  await LocalStorage.setItem("favorite-fruit", "cherry");

  // Number
  await LocalStorage.setItem("fruit-basket-count", 3);

  // Boolean
  await LocalStorage.setItem("fruit-eaten-today", true);
}
```


# User Interface

Raycast uses React for its user interface declaration and renders the supported elements to our native UI. The API comes with a set of UI components that you can use to build your extensions. Think of it as a design system. The high-level components are the following:

- List to show multiple similar items, f.e. a list of your open todos.
- Grid similar to a List but with more legroom to show an image for each item, f.e. a collection of icons.
- Detail to present more information, f.e. the details of a GitHub pull request.
- Form to create new content, f.e. filing a bug report.

Each component can provide interaction via an ActionPanel. Shortcuts allow users to use Raycast without using their mouse.

## Rendering

To render a user interface, you need to do the following:

- Set the `mode` to `view` in the `package.json` manifest file
- Export a React component from your command entry file

As a general rule of thumb, you should render something as quickly as possible. This guarantees that your command feels responsive. If you don't have data available to show, you can set the `isLoading` prop to `true` on top-level components such as `<Detail>`. It shows a loading indicator at the top of Raycast.

Here is an example that shows a loading indicator for 2 seconds after the command got launched:

```typescript
import { List } from "@raycast/api";
import { useEffect, useState } from "react";

export default function Command() {
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    setTimeout(() => setIsLoading(false), 2000);
  }, []);

  return <List isLoading={isLoading}>{/* Render your data */}</List>;
}
```


# Action Panel



## API Reference

### ActionPanel

Exposes a list of actions that can be performed by the user.

Often items are context-aware, e.g., based on the selected list item. Actions can be grouped into semantic
sections and can have keyboard shortcuts assigned.

The first and second action become the primary and secondary action. They automatically get the default keyboard shortcuts assigned.
In List it's `⌘` `↵` for the primary and `⌘` `⇧` `↵` for the secondary.
Keep in mind that while you can specify an alternative shortcut for the primary and secondary actions, it won't be displayed in the Action Panel.

#### Example

```typescript
import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List navigationTitle="Open Pull Requests">
      <List.Item
        title="Docs: Update API Reference"
        subtitle="#1"
        actions={
          <ActionPanel title="#1 in raycast/extensions">
            <Action.OpenInBrowser url="https://github.com/raycast/extensions/pull/1" />
            <Action.CopyToClipboard
              title="Copy Pull Request URL"
              content="https://github.com/raycast/extensions/pull/1"
            />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | Sections or Actions. If Action</code> | - |
| title | The title displayed at the top of the panel | <code>string</code> | - |

### ActionPanel.Section

A group of visually separated items.

Use sections when the ActionPanel contains a lot of actions to help guide the user to related actions.
For example, create a section for all copy actions.

#### Example

```typescript
import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List navigationTitle="Open Pull Requests">
      <List.Item
        title="Docs: Update API Reference"
        subtitle="#1"
        actions={
          <ActionPanel title="#1 in raycast/extensions">
            <ActionPanel.Section title="Copy">
              <Action.CopyToClipboard title="Copy Pull Request Number" content="#1" />
              <Action.CopyToClipboard
                title="Copy Pull Request URL"
                content="https://github.com/raycast/extensions/pull/1"
              />
              <Action.CopyToClipboard title="Copy Pull Request Title" content="Docs: Update API Reference" />
            </ActionPanel.Section>
            <ActionPanel.Section title="Danger zone">
              <Action title="Close Pull Request" onAction={() => console.log("Close PR #1")} />
            </ActionPanel.Section>
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | The item elements of the section. | <code>ActionPanel.Section.Children</code> | - |
| title | Title displayed above the section | <code>string</code> | - |

### ActionPanel.Submenu

A very specific action that replaces the current ActionPanel with its children when selected.

This is handy when an action needs to select from a range of options. For example, to add a label to a GitHub pull request or an assignee to a todo.

#### Example

```typescript
import { Action, ActionPanel, Color, Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List navigationTitle="Open Pull Requests">
      <List.Item
        title="Docs: Update API Reference"
        subtitle="#1"
        actions={
          <ActionPanel title="#1 in raycast/extensions">
            <ActionPanel.Submenu title="Add Label">
              <Action
                icon={{ source: Icon.Circle, tintColor: Color.Red }}
                title="Bug"
                onAction={() => console.log("Add bug label")}
              />
              <Action
                icon={{ source: Icon.Circle, tintColor: Color.Yellow }}
                title="Enhancement"
                onAction={() => console.log("Add enhancement label")}
              />
              <Action
                icon={{ source: Icon.Circle, tintColor: Color.Blue }}
                title="Help Wanted"
                onAction={() => console.log("Add help wanted label")}
              />
            </ActionPanel.Submenu>
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title displayed for submenu. | <code>string</code> | - |
| autoFocus | Indicates whether the ActionPanel.Submenu should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens. | <code>boolean</code> | - |
| children | Items of the submenu. | <code>ActionPanel.Submenu.Children</code> | - |
| 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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| icon | The icon displayed for the submenu. | <code>Image.ImageLike</code> | - |
| isLoading | Indicates whether a loading indicator should be shown or hidden next to the search bar | <code>boolean</code> | `false` |
| shortcut | The keyboard shortcut for the submenu. | <code>Keyboard.Shortcut</code> | - |
| 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). | <code>boolean</code> | `false` |
| onOpen | Callback that is triggered when the Submenu is opened. | <code>() => void</code> | - |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |

## Types

### ActionPanel.Children

```typescript
ActionPanel.Children: ActionPanel.Section | ActionPanel.Section[] | ActionPanel.Section.Children | null
```

Supported children for the ActionPanel component.

### ActionPanel.Section.Children

```typescript
ActionPanel.Section.Children: Action | Action[] | ReactElement<ActionPanel.Submenu.Props> | ReactElement<ActionPanel.Submenu.Props>[] | null
```

Supported children for the ActionPanel.Section component.

### ActionPanel.Submenu.Children

```typescript
ActionPanel.Children: ActionPanel.Section | ActionPanel.Section[] | ActionPanel.Section.Children | null
```

Supported children for the ActionPanel.Submenu component.


# Actions

Our API includes a few built-in actions that can be used for common interactions, such as opening a link or copying some content to the clipboard. By using them, you make sure to follow our human interface guidelines. If you need something custom, use the `Action` component. All built-in actions are just abstractions on top of it.

## API Reference

### Action

A context-specific action that can be performed by the user.

Assign keyboard shortcuts to items to make it easier for users to perform frequently used actions.

#### Example

```typescript
import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List navigationTitle="Open Pull Requests">
      <List.Item
        title="Docs: Update API Reference"
        subtitle="#1"
        actions={
          <ActionPanel title="#1 in raycast/extensions">
            <Action.OpenInBrowser url="https://github.com/raycast/extensions/pull/1" />
            <Action.CopyToClipboard title="Copy Pull Request Number" content="#1" />
            <Action title="Close Pull Request" onAction={() => console.log("Close PR #1")} />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title displayed for the Action. | <code>string</code> | - |
| autoFocus | Indicates whether the Action should be focused automatically when the parent ActionPanel (or Actionpanel.Submenu) opens. | <code>boolean</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| style | Defines the visual style of the Action. | <code>Alert.ActionStyle |
| onAction | Callback that is triggered when the Action is selected. | <code>() => void</code> | - |

### Action.CopyToClipboard

Action that copies the content to the clipboard.

The main window is closed, and a HUD is shown after the content was copied to the clipboard.

#### Example

```typescript
import { ActionPanel, Action, Detail } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Press `⌘ + .` and share some love."
      actions={
        <ActionPanel>
          <Action.CopyToClipboard content="I ❤️ Raycast" shortcut={{ modifiers: ["cmd"], key: "." }} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| content<mark style="color:red;">*</mark> | The contents that will be copied to the clipboard. | <code>string</code> or <code>number</code> or <code>Clipboard.Content</code> | - |
| concealed | Indicates whether the content be treated as confidential. If `true`, it will not be recorded in the Clipboard History. | <code>boolean</code> | `false` |
| icon | A optional icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | `"Copy to Clipboard"` |
| onCopy | Callback when the content was copied to clipboard. | <code>(content: string \| number \| Clipboard.Content => void</code> | - |

### Action.Open

An action to open a file or folder with a specific application, just as if you had double-clicked the
file's icon.

The main window is closed after the file is opened.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Check out your extension code."
      actions={
        <ActionPanel>
          <Action.Open title="Open Folder" target={__dirname} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The file, folder or URL to open. | <code>string</code> | - |
| title<mark style="color:red;">*</mark> | The title for the Action. | <code>string</code> | - |
| application | The application name to use for opening the file. | <code>string</code> or <code>Application</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| onOpen | Callback when the file or folder was opened. | <code>(target: string) => void</code> | - |

### Action.OpenInBrowser

Action that opens a URL in the default browser.

The main window is closed after the URL is opened in the browser.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Join the gang!"
      actions={
        <ActionPanel>
          <Action.OpenInBrowser url="https://raycast.com/jobs" />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| url<mark style="color:red;">*</mark> | The URL to open. | <code>string</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The optional keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | `"Open in Browser"` |
| onOpen | Callback when the URL was opened in the browser. | <code>(url: string) => void</code> | - |

### Action.OpenWith

Action that opens a file or URL with a specific application.

The action opens a sub-menu with all applications that can open the file or URL.
The main window is closed after the item is opened in the specified application.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
import { homedir } from "os";

const DESKTOP_DIR = `${homedir()}/Desktop`;

export default function Command() {
  return (
    <Detail
      markdown="What do you want to use to open your desktop with?"
      actions={
        <ActionPanel>
          <Action.OpenWith path={DESKTOP_DIR} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> | The path to open. | <code>string</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | The title for the Action. | <code>string</code> | `"Open With"` |
| onOpen | Callback when the file or folder was opened. | <code>(path: string) => void</code> | - |

### Action.Paste

Action that pastes the content to the front-most applications.

The main window is closed after the content is pasted to the front-most application.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Let us know what you think about the Raycast API?"
      actions={
        <ActionPanel>
          <Action.Paste content="api@raycast.com" />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| content<mark style="color:red;">*</mark> | The contents that will be pasted to the frontmost application. | <code>string</code> or <code>number</code> or <code>Clipboard.Content</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | `"Paste in Active App"` |
| onPaste | Callback when the content was pasted into the front-most application. | <code>(content: string \| number \| Clipboard.Content => void</code> | - |

### Action.Push

Action that pushes a new view to the navigation stack.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

function Ping() {
  return (
    <Detail
      markdown="Ping"
      actions={
        <ActionPanel>
          <Action.Push title="Push Pong" target={<Pong />} />
        </ActionPanel>
      }
    />
  );
}

function Pong() {
  return <Detail markdown="Pong" />;
}

export default function Command() {
  return <Ping />;
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The target view that will be pushed to the navigation stack. | <code>React.ReactNode</code> | - |
| title<mark style="color:red;">*</mark> | The title displayed for the Action. | <code>string</code> | - |
| icon | The icon displayed for the Action. | <code>Image.ImageLike</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| onPop | Callback when the target view will be popped. | <code>() => void</code> | - |
| onPush | Callback when the target view was pushed. | <code>() => void</code> | - |

### Action.ShowInFinder

Action that shows a file or folder in the Finder.

The main window is closed after the file or folder is revealed in the Finder.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
import { homedir } from "os";

const DOWNLOADS_DIR = `${homedir()}/Downloads`;

export default function Command() {
  return (
    <Detail
      markdown="Are your downloads pilling up again?"
      actions={
        <ActionPanel>
          <Action.ShowInFinder path={DOWNLOADS_DIR} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> | The path to open. | <code>PathLike</code> | - |
| icon | A optional icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | `"Show in Finder"` |
| onShow | Callback when the file or folder was shown in the Finder. | <code>(path: PathLike => void</code> | - |

### Action.SubmitForm

Action that adds a submit handler for capturing form values.

#### Example

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Are you happy?" defaultValue={true} />
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| icon | The icon displayed for the Action. | <code>Image.ImageLike</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| style | Defines the visual style of the Action. | <code>Alert.ActionStyle |
| title | The title displayed for the Action. | <code>string</code> | `"Submit Form"` |
| onSubmit | Callback when the Form was submitted. The handler receives a the values object containing the user input. | <code>(input: Form.Values => boolean \| void \| Promise&lt;boolean \| void></code> | - |

### Action.Trash

Action that moves a file or folder to the Trash.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";
import { homedir } from "os";

const FILE = `${homedir()}/Downloads/get-rid-of-me.txt`;

export default function Command() {
  return (
    <Detail
      markdown="Some spring cleaning?"
      actions={
        <ActionPanel>
          <Action.Trash paths={FILE} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| paths<mark style="color:red;">*</mark> | The item or items to move to the trash. | <code>PathLike[]</code> | - |
| icon | A optional icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The optional keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | `"Move to Trash"` |
| onTrash | Callback when all items were moved to the trash. | <code>(paths: PathLike => void</code> | - |

### Action.CreateSnippet

Action that navigates to the the Create Snippet command with some or all of the fields prefilled.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Test out snippet creation"
      actions={
        <ActionPanel>
          <Action.CreateSnippet snippet={{ text: "DE75512108001245126199" }} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| snippet<mark style="color:red;">*</mark> |  | <code>Snippet</code> | - |
| icon | A optional icon displayed for the Action. See Image.ImageLike</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | - |

### Action.CreateQuicklink

Action that navigates to the the Create Quicklink command with some or all of the fields prefilled.

#### Example

```typescript
import { ActionPanel, Detail, Action } from "@raycast/api";

export default function Command() {
  return (
    <Detail
      markdown="Test out quicklink creation"
      actions={
        <ActionPanel>
          <Action.CreateQuicklink quicklink={{ link: "https://duckduckgo.com/?q={Query}" }} />
        </ActionPanel>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| quicklink<mark style="color:red;">*</mark> | The Quicklink</code> | - |
| icon | A optional icon displayed for the Action. See Image.ImageLike</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | An optional title for the Action. | <code>string</code> | - |

### Action.ToggleQuickLook

Action that toggles the Quick Look to preview a file.

#### Example

```typescript
import { ActionPanel, List, Action } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Preview me"
        quickLook={{ path: "~/Downloads/Raycast.dmg", name: "Some file" }}
        actions={
          <ActionPanel>
            <Action.ToggleQuickLook shortcut={{ modifiers: ["cmd"], key: "y" }} />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| icon | The icon displayed for the Action. | <code>Image.ImageLike |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| title | The title for the Action. | <code>string</code> | `"Quick Look"` |

### Action.PickDate

Action to pick a date.

#### Example

```typescript
import { ActionPanel, List, Action } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Todo"
        actions={
          <ActionPanel>
            <Action.PickDate title="Set Due Date…" />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | A title for the Action. | <code>string</code> | - |
| onChange<mark style="color:red;">*</mark> | Callback when the Date was picked | <code>(date: Date) => void</code> | - |
| icon | A optional icon displayed for the Action. | <code>Image.ImageLike |
| max | The maximum date (inclusive) allowed for selection. | <code>Date</code> | - |
| min | The minimum date (inclusive) allowed for selection. | <code>Date</code> | - |
| shortcut | The keyboard shortcut for the Action. | <code>Keyboard.Shortcut</code> | - |
| type | Indicates what types of date components can be picked | <code>Action.PickDate.Type</code> | - |

## Types

### Snippet

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| text<mark style="color:red;">*</mark> | The snippet contents. | <code>string</code> |
| keyword | The keyword to trigger the snippet. | <code>string</code> |
| name | The snippet name. | <code>string</code> |

### Quicklink

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| link<mark style="color:red;">*</mark> | The URL or file path, optionally including placeholders such as in "https://google.com/search?q=\{Query\}" | <code>string</code> |
| application | The application that the quicklink should be opened in. | <code>string</code> or <code>Application</code> |
| icon | The icon to display for the quicklink. | <code>Icon</code> |
| name | The quicklink name | <code>string</code> |

### Action.Style

Defines the visual style of the Action.

Use Action.Style.Regular for displaying a regular actions.
Use Action.Style.Destructive when your action has something that user should be careful about.
Use the confirmation Alert if the action is doing something that user cannot revert.

### Action.PickDate.Type

The types of date components the user can pick with an `Action.PickDate`.

#### Enumeration members

| Name     | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| DateTime | Hour and second can be picked in addition to year, month and day |
| Date     | Only year, month, and day can be picked                          |

### Action.PickDate.isFullDay

A method that determines if a given date represents a full day or a specific time.

```tsx
import { ActionPanel, List, Action } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Todo"
        actions={
          <ActionPanel>
            <Action.PickDate
              title="Set Due Date…"
              onChange={(date) => {
                if (Action.PickDate.isFullDay(values.reminderDate)) {
                  // the event is for a full day
                } else {
                  // the event is at a specific time
                }
              }}
            />
          </ActionPanel>
        }
      />
    </List>
  );
}
```


# Colors

Anywhere you can pass a color in a component prop, you can pass either:

- A standard Color
- A Dynamic Color
- A Raw Color

## API Reference

### Color

The standard colors. Use those colors for consistency.

The colors automatically adapt to the Raycast theme (light or dark).

#### Example

```typescript
import { Color, Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
      <List.Item title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
      <List.Item title="Magenta" icon={{ source: Icon.Circle, tintColor: Color.Magenta }} />
      <List.Item title="Orange" icon={{ source: Icon.Circle, tintColor: Color.Orange }} />
      <List.Item title="Purple" icon={{ source: Icon.Circle, tintColor: Color.Purple }} />
      <List.Item title="Red" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
      <List.Item title="Yellow" icon={{ source: Icon.Circle, tintColor: Color.Yellow }} />
      <List.Item title="PrimaryText" icon={{ source: Icon.Circle, tintColor: Color.PrimaryText }} />
      <List.Item title="SecondaryText" icon={{ source: Icon.Circle, tintColor: Color.SecondaryText }} />
    </List>
  );
}
```

#### Enumeration members

| Name          | Dark Theme                                                | Light Theme                                          |
| :------------ | :-------------------------------------------------------- | :--------------------------------------------------- |
| Blue          |            |
| Green         |           |
| Magenta       |         |
| Orange        |          |
| Purple        |          |
| Red           |             |
| Yellow        |          |
| PrimaryText   |    |
| SecondaryText |  |

## Types

### Color.ColorLike

```typescript
ColorLike: Color | Color.Dynamic | Color.Raw;
```

Union type for the supported color types.

When using a Raw Color. However, we recommend leaving color adjustment on, unless your extension depends on exact color reproduction.

#### Example

```typescript
import { Color, Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Built-in color" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
      <List.Item title="Raw color" icon={{ source: Icon.Circle, tintColor: "#FF0000" }} />
      <List.Item
        title="Dynamic color"
        icon={{
          source: Icon.Circle,
          tintColor: {
            light: "#FF01FF",
            dark: "#FFFF50",
            adjustContrast: true,
          },
        }}
      />
    </List>
  );
}
```

### Color.Dynamic

A dynamic color applies different colors depending on the active Raycast theme.

When using a Dynamic Color, it will be adjusted to achieve high contrast with the Raycast user interface. To disable color adjustment, you can set the `adjustContrast` property to `false`. However, we recommend leaving color adjustment on, unless your extension depends on exact color reproduction.

#### Example

```typescript
import { Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Dynamic Tint Color"
        icon={{
          source: Icon.Circle,
          tintColor: {
            light: "#FF01FF",
            dark: "#FFFF50",
            adjustContrast: false,
          },
        }}
      />
      <List.Item
        title="Dynamic Tint Color"
        icon={{
          source: Icon.Circle,
          tintColor: { light: "#FF01FF", dark: "#FFFF50" },
        }}
      />
    </List>
  );
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| dark<mark style="color:red;">*</mark> | The color which is used in dark theme. | <code>string</code> |
| light<mark style="color:red;">*</mark> | The color which is used in light theme. | <code>string</code> |
| adjustContrast | Enables dynamic contrast adjustment for light and dark theme color. | <code>boolean</code> |

### Color.Raw

A color can also be a simple string. You can use any of the following color formats:

- HEX, e.g `#FF0000`
- Short HEX, e.g. `#F00`
- RGBA, e.g. `rgb(255, 0, 0)`
- RGBA Percentage, e.g. `rgb(255, 0, 0, 1.0)`
- HSL, e.g. `hsla(200, 20%, 33%, 0.2)`
- Keywords, e.g. `red`


# Detail



## API Reference

### Detail

Renders a markdown ([CommonMark](https://commonmark.org)) string with an optional metadata panel.

Typically used as a standalone view or when navigating from a List.

#### Example

{% tabs %}
{% tab title="Render a markdown string" %}

```typescript
import { Detail } from "@raycast/api";

export default function Command() {
  return <Detail markdown="**Hello** _World_!" />;
}
```

{% endtab %}

{% tab title="Render an image from the assets directory" %}

```typescript
import { Detail } from "@raycast/api";

export default function Command() {
  return <Detail markdown={`!Image Title`} />;
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| actions | A reference to an ActionPanel. | <code>React.ReactNode</code> | - |
| isLoading | Indicates whether a loading bar should be shown or hidden below the search bar | <code>boolean</code> | `false` |
| markdown | The CommonMark string to be rendered. | <code>string</code> | - |
| metadata | The `Detail.Metadata` to be rendered in the right side area | <code>React.ReactNode</code> | - |
| navigationTitle | The main title for that view displayed in Raycast | <code>string</code> | Command title |

{% hint style="info" %}
You can specify custom image dimensions by adding a `raycast-width` and `raycast-height` query string to the markdown image. For example: `!Image Title`

You can also specify a tint color to apply to an markdown image by adding a `raycast-tint-color` query string. For example: `!Image Title`
{% endhint %}

{% hint style="info" %}
You can now render [LaTeX](https://www.latex-project.org) in the markdown. We support the following delimiters:

- Inline math: `\(...\)` and `\begin{math}...\end{math}`
- Display math: `\[...\]`, `$$...$$` and `\begin{equation}...\end{equation}`

{% endhint %}

### Detail.Metadata

A Metadata view that will be shown in the right-hand-side of the `Detail`.

Use it to display additional structured data about the main content shown in the `Detail` view.



#### Example

```typescript
import { Detail } from "@raycast/api";

// Define markdown here to prevent unwanted indentation.
const markdown = `
# Pikachu

![](https://assets.pokemon.com/assets/cms2/img/pokedex/full/025.png)

Pikachu that can generate powerful electricity have cheek sacs that are extra soft and super stretchy.
`;

export default function Main() {
  return (
    <Detail
      markdown={markdown}
      navigationTitle="Pikachu"
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.Label title="Height" text={`1' 04"`} />
          <Detail.Metadata.Label title="Weight" text="13.2 lbs" />
          <Detail.Metadata.TagList title="Type">
            <Detail.Metadata.TagList.Item text="Electric" color={"#eed535"} />
          </Detail.Metadata.TagList>
          <Detail.Metadata.Separator />
          <Detail.Metadata.Link title="Evolution" target="https://www.pokemon.com/us/pokedex/pikachu" text="Raichu" />
        </Detail.Metadata>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children<mark style="color:red;">*</mark> | The elements of the Metadata view. | <code>React.ReactNode</code> | - |

### Detail.Metadata.Label

A single value with an optional icon.



#### Example

```typescript
import { Detail } from "@raycast/api";

// Define markdown here to prevent unwanted indentation.
const markdown = `
# Pikachu

![](https://assets.pokemon.com/assets/cms2/img/pokedex/full/025.png)

Pikachu that can generate powerful electricity have cheek sacs that are extra soft and super stretchy.
`;

export default function Main() {
  return (
    <Detail
      markdown={markdown}
      navigationTitle="Pikachu"
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.Label title="Height" text={`1' 04"`} icon="weight.svg" />
        </Detail.Metadata>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of the item. | <code>string</code> | - |
| icon | An icon to illustrate the value of the item. | <code>Image.ImageLike</code> | - |
| text | The text value of the item. Specifying `color` will display the text in the provided color. Defaults to Color.SecondaryText; value: string }</code> | - |

### Detail.Metadata.Link

An item to display a link.



#### Example

```typescript
import { Detail } from "@raycast/api";

// Define markdown here to prevent unwanted indentation.
const markdown = `
# Pikachu

![](https://assets.pokemon.com/assets/cms2/img/pokedex/full/025.png)

Pikachu that can generate powerful electricity have cheek sacs that are extra soft and super stretchy.
`;

export default function Main() {
  return (
    <Detail
      markdown={markdown}
      navigationTitle="Pikachu"
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.Link title="Evolution" target="https://www.pokemon.com/us/pokedex/pikachu" text="Raichu" />
        </Detail.Metadata>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The target of the link. | <code>string</code> | - |
| text<mark style="color:red;">*</mark> | The text value of the item. | <code>string</code> | - |
| title<mark style="color:red;">*</mark> | The title shown above the item. | <code>string</code> | - |

### Detail.Metadata.TagList

A list of `Tags` displayed in a row.



#### Example

```typescript
import { Detail } from "@raycast/api";

// Define markdown here to prevent unwanted indentation.
const markdown = `
# Pikachu

![](https://assets.pokemon.com/assets/cms2/img/pokedex/full/025.png)

Pikachu that can generate powerful electricity have cheek sacs that are extra soft and super stretchy.
`;

export default function Main() {
  return (
    <Detail
      markdown={markdown}
      navigationTitle="Pikachu"
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.TagList title="Type">
            <Detail.Metadata.TagList.Item text="Electric" color={"#eed535"} />
          </Detail.Metadata.TagList>
        </Detail.Metadata>
      }
    />
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children<mark style="color:red;">*</mark> | The tags contained in the TagList. | <code>React.ReactNode</code> | - |
| title<mark style="color:red;">*</mark> | The title shown above the item. | <code>string</code> | - |

### Detail.Metadata.TagList.Item

A Tag in a `Detail.Metadata.TagList`.

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| color | Changes the text color to the provided color and sets a transparent background with the same color. | <code>Color.ColorLike</code> | - |
| icon | The optional icon tag icon. Required if the tag has no text. | <code>Image.ImageLike</code> | - |
| text | The optional tag text. Required if the tag has no icon. | <code>string</code> | - |
| onAction | Callback that is triggered when the item is clicked. | <code>() => void</code> | - |

### Detail.Metadata.Separator

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



```typescript
import { Detail } from "@raycast/api";

// Define markdown here to prevent unwanted indentation.
const markdown = `
# Pikachu

![](https://assets.pokemon.com/assets/cms2/img/pokedex/full/025.png)

Pikachu that can generate powerful electricity have cheek sacs that are extra soft and super stretchy.
`;

export default function Main() {
  return (
    <Detail
      markdown={markdown}
      navigationTitle="Pikachu"
      metadata={
        <Detail.Metadata>
          <Detail.Metadata.Label title="Height" text={`1' 04"`} />
          <Detail.Metadata.Separator />
          <Detail.Metadata.Label title="Weight" text="13.2 lbs" />
        </Detail.Metadata>
      }
    />
  );
}
```


# Form

Our `Form` component provides great user experience to collect some data from a user and submit it for extensions needs.



## Two Types of Items: Controlled vs. Uncontrolled

Items in React can be one of two types: controlled or uncontrolled.

An uncontrolled item is the simpler of the two. It's the closest to a plain HTML input. React puts it on the page, and Raycast keeps track of the rest. Uncontrolled inputs require less code, but make it harder to do certain things.

With a controlled item, YOU explicitly control the `value` that the item displays. You have to write code to respond to changes with defining `onChange` callback, store the current `value` somewhere, and pass that value back to the item to be displayed. It's a feedback loop with your code in the middle. It's more manual work to wire these up, but they offer the most control.

You can take look at these two styles below under each of the supported items.

## Validation

Before submitting data, it is important to ensure all required form controls are filled out, in the correct format.

In Raycast, validation can be fully controlled from the API. To keep the same behavior as we have natively, the proper way of usage is to validate a `value` in the `onBlur` callback, update the `error` of the item and keep track of updates with the `onChange` callback to drop the `error` value. The useForm utils hook nicely wraps this behaviour and is the recommended way to do deal with validations.



{% hint style="info" %}
Keep in mind that if the Form has any errors, the `Action.SubmitForm` `onSubmit` callback won't be triggered.
{% endhint %}

#### Example

{% tabs %}

{% tab title="FormValidationWithUtils.tsx" %}

```tsx
import { Action, ActionPanel, Form, showToast, Toast } from "@raycast/api";
import { useForm, FormValidation } from "@raycast/utils";

interface SignUpFormValues {
  name: string;
  password: string;
}

export default function Command() {
  const { handleSubmit, itemProps } = useForm<SignUpFormValues>({
    onSubmit(values) {
      showToast({
        style: Toast.Style.Success,
        title: "Yay!",
        message: `${values.name} account created`,
      });
    },
    validation: {
      name: FormValidation.Required,
      password: (value) => {
        if (value && value.length < 8) {
          return "Password must be at least 8 symbols";
        } else if (!value) {
          return "The item is required";
        }
      },
    },
  });
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextField title="Full Name" placeholder="Tim Cook" {...itemProps.name} />
      <Form.PasswordField title="New Password" {...itemProps.password} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="FormValidationWithoutUtils.tsx" %}

```typescript
import { Form } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [nameError, setNameError] = useState<string | undefined>();
  const [passwordError, setPasswordError] = useState<string | undefined>();

  function dropNameErrorIfNeeded() {
    if (nameError && nameError.length > 0) {
      setNameError(undefined);
    }
  }

  function dropPasswordErrorIfNeeded() {
    if (passwordError && passwordError.length > 0) {
      setPasswordError(undefined);
    }
  }

  return (
    <Form>
      <Form.TextField
        id="nameField"
        title="Full Name"
        placeholder="Tim Cook"
        error={nameError}
        onChange={dropNameErrorIfNeeded}
        onBlur={(event) => {
          if (event.target.value?.length == 0) {
            setNameError("The field should't be empty!");
          } else {
            dropNameErrorIfNeeded();
          }
        }}
      />
      <Form.PasswordField
        id="password"
        title="New Password"
        error={passwordError}
        onChange={dropPasswordErrorIfNeeded}
        onBlur={(event) => {
          const value = event.target.value;
          if (value && value.length > 0) {
            if (!validatePassword(value)) {
              setPasswordError("Password should be at least 8 characters!");
            } else {
              dropPasswordErrorIfNeeded();
            }
          } else {
            setPasswordError("The field should't be empty!");
          }
        }}
      />
      <Form.TextArea id="bioTextArea" title="Add Bio" placeholder="Describe who you are" />
      <Form.DatePicker id="birthDate" title="Date of Birth" />
    </Form>
  );
}

function validatePassword(value: string): boolean {
  return value.length >= 8;
}
```

{% endtab %}

{% endtabs %}

## Drafts

Drafts are a mechanism to preserve filled-in inputs (but not yet submitted) when an end-user exits the command. To enable this mechanism, set the `enableDrafts` prop on your Form and populate the initial values of the Form with the top-level prop `draftValues`.



{% hint style="info" %}

- Drafts for forms nested in navigation are not supported yet. In this case, you will see a warning about it.
- Drafts won't preserve the `Form.Password`'s values.
- Drafts will be dropped once `Action.SubmitForm` is triggered.
- If you call `popToRoot()`, drafts won't be preserved or updated.

{% endhint %}

#### Example

{% tabs %}
{% tab title="Uncontrolled Form" %}

```typescript
import { Form, ActionPanel, Action, popToRoot, LaunchProps } from "@raycast/api";

interface TodoValues {
  title: string;
  description?: string;
  dueDate?: Date;
}

export default function Command(props: LaunchProps<{ draftValues: TodoValues }>) {
  const { draftValues } = props;

  return (
    <Form
      enableDrafts
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values: TodoValues) => {
              console.log("onSubmit", values);
              popToRoot();
            }}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="title" title="Title" defaultValue={draftValues?.title} />
      <Form.TextArea id="description" title="Description" defaultValue={draftValues?.description} />
      <Form.DatePicker id="dueDate" title="Due Date" defaultValue={draftValues?.dueDate} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled Form" %}

```typescript
import { Form, ActionPanel, Action, popToRoot, LaunchProps } from "@raycast/api";
import { useState } from "react";

interface TodoValues {
  title: string;
  description?: string;
  dueDate?: Date;
}

export default function Command(props: LaunchProps<{ draftValues: TodoValues }>) {
  const { draftValues } = props;

  const [title, setTitle] = useState<string>(draftValues?.title || "");
  const [description, setDescription] = useState<string>(draftValues?.description || "");
  const [dueDate, setDueDate] = useState<Date | null>(draftValues?.dueDate || null);

  return (
    <Form
      enableDrafts
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values: TodoValues) => {
              console.log("onSubmit", values);
              popToRoot();
            }}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="title" title="Title" value={title} onChange={setTitle} />
      <Form.TextArea id="description" title="Description" value={description} onChange={setDescription} />
      <Form.DatePicker id="dueDate" title="Due Date" value={dueDate} onChange={setDueDate} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

## API Reference

### Form

Shows a list of form items such as Form.TextField.

Optionally add a Form.LinkAccessory in the right-hand side of the navigation bar.

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| actions | A reference to an ActionPanel. | <code>React.ReactNode</code> | - |
| children | The Form.Item elements of the form. | <code>React.ReactNode</code> | - |
| enableDrafts | Defines whether the Form.Items values will be preserved when user exits the screen. | <code>boolean</code> | `false` |
| isLoading | Indicates whether a loading bar should be shown or hidden below the search bar | <code>boolean</code> | `false` |
| navigationTitle | The main title for that view displayed in Raycast | <code>string</code> | Command title |
| searchBarAccessory | Form.LinkAccessory, string></code> | - |

### Form.TextField

A form item with a text field for input.



#### Example

{% tabs %}
{% tab title="Uncontrolled text field" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" defaultValue="Steve" />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled text field" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [name, setName] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" value={name} onChange={setName} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| defaultValue | The default value of the item. 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. | <code>string</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| placeholder | Placeholder text shown in the text field. | <code>string</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.PasswordField

A form item with a secure text field for password-entry in which the entered characters must be kept secret.



#### Example

{% tabs %}
{% tab title="Uncontrolled password field" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Password" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.PasswordField id="password" title="Enter Password" />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled password field" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [password, setPassword] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Password" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.PasswordField id="password" value={password} onChange={setPassword} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| defaultValue | The default value of the item. 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. | <code>string</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| placeholder | Placeholder text shown in the password field. | <code>string</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.TextArea

A form item with a text area for input. The item supports multiline text entry.



#### Example

{% tabs %}
{% tab title="Uncontrolled text area" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

const DESCRIPTION =
  "We spend too much time staring at loading indicators. The Raycast team is dedicated to make everybody interact faster with their computers.";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Description" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="description" defaultValue={DESCRIPTION} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled text area" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [description, setDescription] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Description" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="description" value={description} onChange={setDescription} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| defaultValue | The default value of the item. 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. | <code>string</code> | - |
| enableMarkdown | Whether markdown will be highlighted in the TextArea or not. When enabled, markdown shortcuts starts to work for the TextArea (pressing `⌘ + B` will add `**bold**` around the selected text, `⌘ + I` will make the selected text italic, etc.) | <code>boolean</code> | `false` |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| placeholder | Placeholder text shown in the text area. | <code>string</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.Checkbox

A form item with a checkbox.



#### Example

{% tabs %}
{% tab title="Uncontrolled checkbox" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Are you happy?" defaultValue={true} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled checkbox" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [checked, setChecked] = useState(true);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Do you like orange juice?" value={checked} onChange={setChecked} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| label<mark style="color:red;">*</mark> | The label displayed on the right side of the checkbox. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| defaultValue | The default value of the item. 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. | <code>boolean</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>boolean</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;boolean>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: boolean) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;boolean>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.DatePicker

A form item with a date picker.



#### Example

{% tabs %}
{% tab title="Uncontrolled date picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="dateOfBirth" title="Date of Birth" defaultValue={new Date(1955, 1, 24)} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled date picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [date, setDate] = useState<Date | null>(null);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="launchDate" title="Launch Date" value={date} onChange={setDate} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| defaultValue | The default value of the item. 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. | <code>Date</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| max | The maximum date (inclusive) allowed for selection. | <code>Date</code> | - |
| min | The minimum date (inclusive) allowed for selection. | <code>Date</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| type | Indicates what types of date components can be picked | <code>Form.DatePicker.Type</code> | - |
| value | The current value of the item. | <code>Date</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;Date \| null>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: Date \| null) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;Date \| null>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

#### Form.DatePicker.isFullDay

A method that determines if a given date represents a full day or a specific time.

```ts
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Create Event"
            onSubmit={(values) => {
              if (Form.DatePicker.isFullDay(values.reminderDate)) {
                // the event is for a full day
              } else {
                // the event is at a specific time
              }
            }}
          />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="eventTitle" title="Title" />
      <Form.DatePicker id="eventDate" title="Date" />
    </Form>
  );
}
```

### Form.Dropdown

A form item with a dropdown menu.



#### Example

{% tabs %}
{% tab title="Uncontrolled dropdown" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="emoji" title="Favorite Emoji" defaultValue="lol">
        <Form.Dropdown.Item value="poop" title="Pile of poop" icon="💩" />
        <Form.Dropdown.Item value="rocket" title="Rocket" icon="🚀" />
        <Form.Dropdown.Item value="lol" title="Rolling on the floor laughing face" icon="🤣" />
      </Form.Dropdown>
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled dropdown" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [programmingLanguage, setProgrammingLanguage] = useState<string>("typescript");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown
        id="dropdown"
        title="Favorite Language"
        value={programmingLanguage}
        onChange={setProgrammingLanguage}
      >
        <Form.Dropdown.Item value="cpp" title="C++" />
        <Form.Dropdown.Item value="javascript" title="JavaScript" />
        <Form.Dropdown.Item value="ruby" title="Ruby" />
        <Form.Dropdown.Item value="python" title="Python" />
        <Form.Dropdown.Item value="swift" title="Swift" />
        <Form.Dropdown.Item value="typescript" title="TypeScript" />
      </Form.Dropdown>
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| children | Sections or items. If Form.Dropdown.Item elements are specified, a default section is automatically created. | <code>React.ReactNode</code> | - |
| defaultValue | The default value of the item. 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. | <code>string</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| 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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| isLoading | Indicates whether a loading indicator should be shown or hidden next to the search bar | <code>boolean</code> | `false` |
| placeholder | Placeholder text that will be shown in the dropdown search field. | <code>string</code> | `"Search…"` |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| 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). | <code>boolean</code> | `false` |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string>) => void</code> | - |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.Dropdown.Item

A dropdown item in a Form.Dropdown

#### Example

```typescript
import { Action, ActionPanel, Form, Icon } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Icon" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="icon" title="Icon">
        <Form.Dropdown.Item value="circle" title="Cirlce" icon={Icon.Circle} />
      </Form.Dropdown>
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title displayed for the item. | <code>string</code> | - |
| value<mark style="color:red;">*</mark> | Value of the dropdown item. Make sure to assign each unique value for each item. | <code>string</code> | - |
| icon | A optional icon displayed for the item. | <code>Image.ImageLike</code> | - |
| 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. | <code>string[]</code> | The title of its section if any |

### Form.Dropdown.Section

Visually separated group of dropdown items.

Use sections to group related menu items together.

#### Example

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="food" title="Favorite Food">
        <Form.Dropdown.Section title="Fruits">
          <Form.Dropdown.Item value="apple" title="Apple" icon="🍎" />
          <Form.Dropdown.Item value="banana" title="Banana" icon="🍌" />
        </Form.Dropdown.Section>
        <Form.Dropdown.Section title="Vegetables">
          <Form.Dropdown.Item value="broccoli" title="Broccoli" icon="🥦" />
          <Form.Dropdown.Item value="carrot" title="Carrot" icon="🥕" />
        </Form.Dropdown.Section>
      </Form.Dropdown>
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | The item elements of the section. | <code>React.ReactNode</code> | - |
| title | Title displayed above the section | <code>string</code> | - |

### Form.TagPicker

A form item with a tag picker that allows the user to select multiple items.



#### Example

{% tabs %}
{% tab title="Uncontrolled tag picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="sports" title="Favorite Sports" defaultValue={["football"]}>
        <Form.TagPicker.Item value="basketball" title="Basketball" icon="🏀" />
        <Form.TagPicker.Item value="football" title="Football" icon="⚽️" />
        <Form.TagPicker.Item value="tennis" title="Tennis" icon="🎾" />
      </Form.TagPicker>
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled tag picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [countries, setCountries] = useState<string[]>(["ger", "ned", "pol"]);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Countries" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="countries" title="Visited Countries" value={countries} onChange={setCountries}>
        <Form.TagPicker.Item value="ger" title="Germany" icon="🇩🇪" />
        <Form.TagPicker.Item value="ind" title="India" icon="🇮🇳" />
        <Form.TagPicker.Item value="ned" title="Netherlands" icon="🇳🇱" />
        <Form.TagPicker.Item value="nor" title="Norway" icon="🇳🇴" />
        <Form.TagPicker.Item value="pol" title="Poland" icon="🇵🇱" />
        <Form.TagPicker.Item value="rus" title="Russia" icon="🇷🇺" />
        <Form.TagPicker.Item value="sco" title="Scotland" icon="🏴󠁧󠁢󠁳󠁣󠁴󠁿" />
      </Form.TagPicker>
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| children | The list of tags. | <code>React.ReactNode</code> | - |
| defaultValue | The default value of the item. 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. | <code>string[]</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| placeholder | Placeholder text shown in the token field. | <code>string</code> | - |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string[]</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string[]>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string[]) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string[]>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.TagPicker.Item

A tag picker item in a Form.TagPicker.

#### Example

```typescript
import { ActionPanel, Color, Form, Icon, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Color" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="color" title="Color">
        <Form.TagPicker.Item value="red" title="Red" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
        <Form.TagPicker.Item value="green" title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
        <Form.TagPicker.Item value="blue" title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
      </Form.TagPicker>
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The display title of the tag. | <code>string</code> | - |
| value<mark style="color:red;">*</mark> | Value of the tag. Make sure to assign unique value for each item. | <code>string</code> | - |
| icon | An icon to show in the tag. | <code>Image.ImageLike</code> | - |

### Form.Separator

A form item that shows a separator line. Use for grouping and visually separating form items.



#### Example

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="textfield" />
      <Form.Separator />
      <Form.TextArea id="textarea" />
    </Form>
  );
}
```

### Form.FilePicker

A form item with a button to open a dialog to pick some files and/or some directories (depending on its props).

{% hint style="info" %}
While the user picked some items that existed, it might be possible for them to be deleted or changed when the `onSubmit` callback is called. Hence you should always make sure that the items exist before acting on them!
{% endhint %}





#### Example

{% tabs %}
{% tab title="Uncontrolled file picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import fs from "fs";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { files: string[] }) => {
              const files = values.files.filter((file: any) => fs.existsSync(file) && fs.lstatSync(file).isFile());
              console.log(files);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Single selection file picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import fs from "fs";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { files: string[] }) => {
              const file = values.files[0];
              if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) {
                return false;
              }
              console.log(file);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" allowMultipleSelection={false} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Directory picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import fs from "fs";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { folders: string[] }) => {
              const folder = values.folders[0];
              if (!fs.existsSync(folder) || fs.lstatSync(folder).isDirectory()) {
                return false;
              }
              console.log(folder);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="folders" allowMultipleSelection={false} canChooseDirectories canChooseFiles={false} />
    </Form>
  );
}
```

{% endtab %}

{% tab title="Controlled file picker" %}

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [files, setFiles] = useState<string[]>([]);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" value={files} onChange={setFiles} />
    </Form>
  );
}
```

{% endtab %}
{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| id<mark style="color:red;">*</mark> | ID of the form item. Make sure to assign each form item a unique id. | <code>string</code> | - |
| allowMultipleSelection | Indicates whether the user can select multiple items or only one. | <code>boolean</code> | `true` |
| autoFocus | Indicates whether the item should be focused automatically once the form is rendered. | <code>boolean</code> | - |
| canChooseDirectories | Indicates whether it's possible to choose a directory. | <code>boolean</code> | `false` |
| canChooseFiles | Indicates whether it's possible to choose a file. | <code>boolean</code> | `true` |
| defaultValue | The default value of the item. 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. | <code>string[]</code> | - |
| error | An optional error message to show the form item validation issues. If the `error` is present, the Form Item will be highlighted with red border and will show an error message on the right. | <code>string</code> | - |
| info | An optional info message to describe the form item. It appears on the right side of the item with an info icon. When the icon is hovered, the info message is shown. | <code>string</code> | - |
| showHiddenFiles | Indicates whether the file picker displays files that are normally hidden from the user. | <code>boolean</code> | `false` |
| storeValue | Indicates whether the value of the item should be persisted after submitting, and restored next time the form is rendered. | <code>boolean</code> | - |
| title | The title displayed on the left side of the item. | <code>string</code> | - |
| value | The current value of the item. | <code>string[]</code> | - |
| onBlur | The callback that will be triggered when the item loses its focus. | <code>(event: FormEvent&lt;string[]>) => void</code> | - |
| onChange | The callback which will be triggered when the `value` of the item changes. | <code>(newValue: string[]) => void</code> | - |
| onFocus | The callback which will be triggered should be called when the item is focused. | <code>(event: FormEvent&lt;string[]>) => void</code> | - |

#### Methods (Imperative API)

| Name  | Signature               | Description                                                                |
| ----- | ----------------------- | -------------------------------------------------------------------------- |
| focus | <code>() => void</code> | Makes the item request focus.                                              |
| reset | <code>() => void</code> | Resets the form item to its initial value, or `defaultValue` if specified. |

### Form.Description

A form item with a simple text label.

Do _not_ use this component to show validation messages for other form fields.



#### Example

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Description
        title="Import / Export"
        text="Exporting will back-up your preferences, quicklinks, snippets, floating notes, script-command folder paths, aliases, hotkeys, favorites and other data."
      />
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| text<mark style="color:red;">*</mark> | Text that will be displayed in the middle. | <code>string</code> | - |
| title | The display title of the left side from the description item. | <code>string</code> | - |

### Form.LinkAccessory

A link that will be shown in the right-hand side of the navigation bar.

#### Example

```typescript
import { ActionPanel, Form, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      searchBarAccessory={
        <Form.LinkAccessory
          target="https://developers.raycast.com/api-reference/user-interface/form"
          text="Open Documentation"
        />
      }
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" defaultValue="Steve" />
    </Form>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The target of the link. | <code>string</code> | - |
| text<mark style="color:red;">*</mark> | The text value of the item. | <code>string</code> | - |

## Types

#### Form.Event

Some Form.Item callbacks (like `onFocus` and `onBlur`) can return a `Form.Event` object that you can use in a different ways.

| Property | Description | Type |
| :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | An interface containing target data related to the event | <code>{ id: string; value?: any }</code> |
| type<mark style="color:red;">*</mark> | A type of event | <code>Form.Event.Type</code> |

#### Example

```typescript
import { Form } from "@raycast/api";

export default function Main() {
  return (
    <Form>
      <Form.TextField id="textField" title="Text Field" onBlur={logEvent} onFocus={logEvent} />
      <Form.TextArea id="textArea" title="Text Area" onBlur={logEvent} onFocus={logEvent} />
      <Form.Dropdown id="dropdown" title="Dropdown" onBlur={logEvent} onFocus={logEvent}>
        {[1, 2, 3, 4, 5, 6, 7].map((num) => (
          <Form.Dropdown.Item value={String(num)} title={String(num)} key={num} />
        ))}
      </Form.Dropdown>
      <Form.TagPicker id="tagPicker" title="Tag Picker" onBlur={logEvent} onFocus={logEvent}>
        {[1, 2, 3, 4, 5, 6, 7].map((num) => (
          <Form.TagPicker.Item value={String(num)} title={String(num)} key={num} />
        ))}
      </Form.TagPicker>
    </Form>
  );
}

function logEvent(event: Form.Event<string[] | string>) {
  console.log(`Event '${event.type}' has happened for '${event.target.id}'. Current 'value': '${event.target.value}'`);
}
```

#### Form.Event.Type

The different types of `Form.Event`. Can be `"focus"` or `"blur"`.

### Form.Values

Values of items in the form.

For type-safe form values, you can define your own interface. Use the ID's of the form items as the property name.

#### Example

```typescript
import { Form, Action, ActionPanel } from "@raycast/api";

interface Values {
  todo: string;
  due?: Date;
}

export default function Command() {
  function handleSubmit(values: Values) {
    console.log(values);
  }

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextField id="todo" title="Todo" />
      <Form.DatePicker id="due" title="Due Date" />
    </Form>
  );
}
```

#### Properties

| Name              | Type  | Required | Description                     |
| ----------------- | ----- | -------- | ------------------------------- |
| \[itemId: string] | `any` | Yes      | The form value of a given item. |

### Form.DatePicker.Type

The types of date components the user can pick with a `Form.DatePicker`.

#### Enumeration members

| Name     | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| DateTime | Hour and second can be picked in addition to year, month and day |
| Date     | Only year, month, and day can be picked                          |

---

## Imperative API

You can use React's [useRef](https://reactjs.org/docs/hooks-reference.html#useref) hook to create variables which have access to imperative APIs (such as `.focus()` or `.reset()`) exposed by the native form items.

```typescript
import { useRef } from "react";
import { ActionPanel, Form, Action } from "@raycast/api";

interface FormValues {
  nameField: string;
  bioTextArea: string;
  datePicker: string;
}

export default function Command() {
  const textFieldRef = useRef<Form.TextField>(null);
  const textAreaRef = useRef<Form.TextArea>(null);
  const datePickerRef = useRef<Form.DatePicker>(null);
  const passwordFieldRef = useRef<Form.PasswordField>(null);
  const dropdownRef = useRef<Form.Dropdown>(null);
  const tagPickerRef = useRef<Form.TagPicker>(null);
  const firstCheckboxRef = useRef<Form.Checkbox>(null);
  const secondCheckboxRef = useRef<Form.Checkbox>(null);

  async function handleSubmit(values: FormValues) {
    console.log(values);
    datePickerRef.current?.focus();
    dropdownRef.current?.reset();
  }

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
          <ActionPanel.Section title="Focus">
            <Action title="Focus TextField" onAction={() => textFieldRef.current?.focus()} />
            <Action title="Focus TextArea" onAction={() => textAreaRef.current?.focus()} />
            <Action title="Focus DatePicker" onAction={() => datePickerRef.current?.focus()} />
            <Action title="Focus PasswordField" onAction={() => passwordFieldRef.current?.focus()} />
            <Action title="Focus Dropdown" onAction={() => dropdownRef.current?.focus()} />
            <Action title="Focus TagPicker" onAction={() => tagPickerRef.current?.focus()} />
            <Action title="Focus First Checkbox" onAction={() => firstCheckboxRef.current?.focus()} />
            <Action title="Focus Second Checkbox" onAction={() => secondCheckboxRef.current?.focus()} />
          </ActionPanel.Section>
          <ActionPanel.Section title="Reset">
            <Action title="Reset TextField" onAction={() => textFieldRef.current?.reset()} />
            <Action title="Reset TextArea" onAction={() => textAreaRef.current?.reset()} />
            <Action title="Reset DatePicker" onAction={() => datePickerRef.current?.reset()} />
            <Action title="Reset PasswordField" onAction={() => passwordFieldRef.current?.reset()} />
            <Action title="Reset Dropdown" onAction={() => dropdownRef.current?.reset()} />
            <Action title="Reset TagPicker" onAction={() => tagPickerRef.current?.reset()} />
            <Action title="Reset First Checkbox" onAction={() => firstCheckboxRef.current?.reset()} />
            <Action title="Reset Second Checkbox" onAction={() => secondCheckboxRef.current?.reset()} />
          </ActionPanel.Section>
        </ActionPanel>
      }
    >
      <Form.TextField id="textField" title="TextField" ref={textFieldRef} />
      <Form.TextArea id="textArea" title="TextArea" ref={textAreaRef} />
      <Form.DatePicker id="datePicker" title="DatePicker" ref={datePickerRef} />
      <Form.PasswordField id="passwordField" title="PasswordField" ref={passwordFieldRef} />
      <Form.Separator />
      <Form.Dropdown
        id="dropdown"
        title="Dropdown"
        defaultValue="first"
        onChange={(newValue) => {
          console.log(newValue);
        }}
        ref={dropdownRef}
      >
        <Form.Dropdown.Item value="first" title="First" />
        <Form.Dropdown.Item value="second" title="Second" />
      </Form.Dropdown>
      <Form.Separator />
      <Form.TagPicker
        id="tagPicker"
        title="TagPicker"
        ref={tagPickerRef}
        onChange={(t) => {
          console.log(t);
        }}
      >
        {["one", "two", "three"].map((tag) => (
          <Form.TagPicker.Item key={tag} value={tag} title={tag} />
        ))}
      </Form.TagPicker>
      <Form.Separator />
      <Form.Checkbox
        id="firstCheckbox"
        title="First Checkbox"
        label="First Checkbox"
        ref={firstCheckboxRef}
        onChange={(checked) => {
          console.log("first checkbox onChange ", checked);
        }}
      />
      <Form.Checkbox
        id="secondCheckbox"
        title="Second Checkbox"
        label="Second Checkbox"
        ref={secondCheckboxRef}
        onChange={(checked) => {
          console.log("second checkbox onChange ", checked);
        }}
      />
      <Form.Separator />
    </Form>
  );
}
```


# Grid

The `Grid` component is provided as an alternative to the List component when the defining characteristic of an item is an image.

{% hint style="info" %}
Because its API tries to stick as closely to List 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' h`icon` prop to `content`
- removing all List.Item does not _currently_ support accessories
- finally, replacing all usages of `List` with `Grid`.
  {% endhint %}



## Search Bar

The search bar allows users to interact quickly with grid items. By default, Grid.Items 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 `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.

```typescript
import { useEffect, useState } from "react";
import { Grid } from "@raycast/api";

const items = [
  { content: "🙈", keywords: ["see-no-evil", "monkey"] },
  { content: "🥳", keywords: ["partying", "face"] },
];

export default function Command() {
  const [searchText, setSearchText] = useState("");
  const [filteredList, filterList] = useState(items);

  useEffect(() => {
    filterList(items.filter((item) => item.keywords.some((keyword) => keyword.includes(searchText))));
  }, [searchText]);

  return (
    <Grid
      columns={5}
      inset={Grid.Inset.Large}
      filtering={false}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Emoji"
      searchBarPlaceholder="Search your favorite emoji"
    >
      {filteredList.map((item) => (
        <Grid.Item key={item.content} content={item.content} />
      ))}
    </Grid>
  );
}
```

### Programmatically updating the search bar

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.

```typescript
import { useState } from "react";
import { Action, ActionPanel, Grid } from "@raycast/api";

const items = [
  { content: "🙈", keywords: ["see-no-evil", "monkey"] },
  { content: "🥳", keywords: ["partying", "face"] },
];

export default function Command() {
  const [searchText, setSearchText] = useState("");

  return (
    <Grid
      searchText={searchText}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Emoji"
      searchBarPlaceholder="Search your favorite emoji"
    >
      {items.map((item) => (
        <Grid.Item
          key={item.content}
          content={item.content}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => setSearchText(item.content)} />
            </ActionPanel>
          }
        />
      ))}
    </Grid>
  );
}
```

### Dropdown

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 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

{% hint style="info" %}
Pagination requires version 1.69.0 or higher of the `@raycast/api` package.
{% endhint %}

`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, and one "from scratch".

{% tabs %}

{% tab title="GridWithUsePromisePagination.tsx" %}

```typescript
import { setTimeout } from "node:timers/promises";
import { useState } from "react";
import { Grid } from "@raycast/api";
import { usePromise } from "@raycast/utils";

export default function Command() {
  const [searchText, setSearchText] = useState("");

  const { isLoading, data, pagination } = usePromise(
    (searchText: string) => async (options: { page: number }) => {
      await setTimeout(200);
      const newData = Array.from({ length: 25 }, (_v, index) => ({ index, page: options.page, text: searchText }));
      return { data: newData, hasMore: options.page < 10 };
    },
    [searchText]
  );

  return (
    <Grid isLoading={isLoading} onSearchTextChange={setSearchText} pagination={pagination}>
      {data?.map((item) => (
        <Grid.Item
          key={`${item.index} ${item.page} ${item.text}`}
          content=""
          title={`Page: ${item.page} Item ${item.index}`}
          subtitle={item.text}
        />
      ))}
    </Grid>
  );
}
```

{% endtab %}

{% tab title="GridWithPagination.tsx" %}

```typescript
import { setTimeout } from "node:timers/promises";
import { useCallback, useEffect, useRef, useState } from "react";
import { Grid } from "@raycast/api";

type State = {
  searchText: string;
  isLoading: boolean;
  hasMore: boolean;
  data: {
    index: number;
    page: number;
    text: string;
  }[];
  nextPage: number;
};
const pageSize = 20;
export default function Command() {
  const [state, setState] = useState<State>({ searchText: "", isLoading: true, hasMore: true, data: [], nextPage: 0 });
  const cancelRef = useRef<AbortController | null>(null);

  const loadNextPage = useCallback(async (searchText: string, nextPage: number, signal?: AbortSignal) => {
    setState((previous) => ({ ...previous, isLoading: true }));
    await setTimeout(200);
    const newData = Array.from({ length: pageSize }, (_v, index) => ({
      index,
      page: nextPage,
      text: searchText,
    }));
    if (signal?.aborted) {
      return;
    }
    setState((previous) => ({
      ...previous,
      data: [...previous.data, ...newData],
      isLoading: false,
      hasMore: nextPage < 10,
    }));
  }, []);

  const onLoadMore = useCallback(() => {
    setState((previous) => ({ ...previous, nextPage: previous.nextPage + 1 }));
  }, []);

  const onSearchTextChange = useCallback(
    (searchText: string) => {
      if (searchText === state.searchText) return;
      setState((previous) => ({
        ...previous,
        data: [],
        nextPage: 0,
        searchText,
      }));
    },
    [state.searchText]
  );

  useEffect(() => {
    cancelRef.current?.abort();
    cancelRef.current = new AbortController();
    loadNextPage(state.searchText, state.nextPage, cancelRef.current?.signal);
    return () => {
      cancelRef.current?.abort();
    };
  }, [loadNextPage, state.searchText, state.nextPage]);

  return (
    <Grid
      isLoading={state.isLoading}
      onSearchTextChange={onSearchTextChange}
      pagination={{ onLoadMore, hasMore: state.hasMore, pageSize }}
    >
      {state.data.map((item) => (
        <Grid.Item
          key={`${item.index} ${item.page} ${item.text}`}
          content=""
          title={`Page: ${item.page} Item ${item.index}`}
          subtitle={item.text}
        />
      ))}
    </Grid>
  );
}
```

{% endtab %}

{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}

## Examples

{% tabs %}
{% tab title="Grid.tsx" %}

```jsx
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid columns={8} inset={Grid.Inset.Large}>
      <Grid.Item content="🥳" />
      <Grid.Item content="🙈" />
    </Grid>
  );
}
```

{% endtab %}

{% tab title="GridWithSections.tsx" %}

```typescript
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid>
      <Grid.Section title="Section 1">
        <Grid.Item content="https://placekitten.com/400/400" title="Item 1" />
      </Grid.Section>
      <Grid.Section title="Section 2" subtitle="Optional subtitle">
        <Grid.Item content="https://placekitten.com/400/400" title="Item 1" />
      </Grid.Section>
    </Grid>
  );
}
```

{% endtab %}

{% tab title="GridWithActions.tsx" %}

```typescript
import { ActionPanel, Action, Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid>
      <Grid.Item
        content="https://placekitten.com/400/400"
        title="Item 1"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard content="👋" />
          </ActionPanel>
        }
      />
    </Grid>
  );
}
```

{% endtab %}

{% tab title="GridWithEmptyView.tsx" %}

```typescript
import { useEffect, useState } from "react";
import { Grid, Image } from "@raycast/api";

export default function CommandWithCustomEmptyView() {
  const [state, setState] = useState<{
    searchText: string;
    items: { content: Image.ImageLike; title: string }[];
  }>({ searchText: "", items: [] });

  useEffect(() => {
    console.log("Running effect after state.searchText changed. Current value:", JSON.stringify(state.searchText));
    // perform an API call that eventually populates `items`.
  }, [state.searchText]);

  return (
    <Grid onSearchTextChange={(newValue) => setState((previous) => ({ ...previous, searchText: newValue }))}>
      {state.searchText === "" && state.items.length === 0 ? (
        <Grid.EmptyView icon={{ source: "https://placekitten.com/500/500" }} title="Type something to get started" />
      ) : (
        state.items.map((item, index) => <Grid.Item key={index} content={item.content} title={item.title} />)
      )}
    </Grid>
  );
}
```

{% endtab %}

{% endtabs %}

## API Reference

### Grid

Displays Grid.Sections.

The grid uses built-in filtering by indexing the title & keywords of its items.

#### Example

```typescript
import { Grid } from "@raycast/api";

const items = [
  { content: "🙈", keywords: ["see-no-evil", "monkey"] },
  { content: "🥳", keywords: ["partying", "face"] },
];

export default function Command() {
  return (
    <Grid
      columns={5}
      inset={Grid.Inset.Large}
      navigationTitle="Search Emoji"
      searchBarPlaceholder="Search your favorite emoji"
    >
      {items.map((item) => (
        <Grid.Item key={item.content} content={item.content} keywords={item.keywords} />
      ))}
    </Grid>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| actions | A reference to an ActionPanel. It will only be shown when there aren't any children. | <code>React.ReactNode</code> | - |
| aspectRatio | Aspect ratio for the Grid.Item elements. Defaults to 1. | <code>"1"</code> or <code>"3/2"</code> or <code>"2/3"</code> or <code>"4/3"</code> or <code>"3/4"</code> or <code>"16/9"</code> or <code>"9/16"</code> | - |
| children | Grid sections or items. If Grid.Item elements are specified, a default section is automatically created. | <code>React.ReactNode</code> | - |
| columns | Column count for the grid's sections. Minimum value is 1, maximum value is 8. | <code>number</code> | `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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| fit | Fit for the Grid.Item</code> | - |
| inset | Indicates how much space there should be between a Grid.Item</code> | - |
| isLoading | Indicates whether a loading bar should be shown or hidden below the search bar | <code>boolean</code> | `false` |
| navigationTitle | The main title for that view displayed in Raycast | <code>string</code> | Command title |
| pagination | Configuration for pagination | <code>{ hasMore: boolean; pageSize: number; onLoadMore: () => void }</code> | - |
| searchBarAccessory | Grid.Dropdown, string></code> | - |
| searchBarPlaceholder | Placeholder text that will be shown in the search bar. | <code>string</code> | `"Search…"` |
| searchText | The text that will be displayed in the search bar. | <code>string</code> | - |
| selectedItemId | Selects the item with the specified id. | <code>string</code> | - |
| 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). | <code>boolean</code> | `false` |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |
| onSelectionChange | Callback triggered when the item selection in the grid changes. | <code>(id: string) => void</code> | - |

### Grid.Dropdown

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

#### Example

```typescript
import { Grid, Image } from "@raycast/api";
import { useState } from "react";

const types = [
  { id: 1, name: "Smileys", value: "smileys" },
  { id: 2, name: "Animals & Nature", value: "animals-and-nature" },
];

const items: { [key: string]: { content: Image.ImageLike; keywords: string[] }[] } = {
  smileys: [{ content: "🥳", keywords: ["partying", "face"] }],
  "animals-and-nature": [{ content: "🙈", keywords: ["see-no-evil", "monkey"] }],
};

export default function Command() {
  const [type, setType] = useState<string>("smileys");

  return (
    <Grid
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite drink"
      searchBarAccessory={
        <Grid.Dropdown tooltip="Select Emoji Category" storeValue={true} onChange={(newValue) => setType(newValue)}>
          <Grid.Dropdown.Section title="Emoji Categories">
            {types.map((type) => (
              <Grid.Dropdown.Item key={type.id} title={type.name} value={type.value} />
            ))}
          </Grid.Dropdown.Section>
        </Grid.Dropdown>
      }
    >
      {(items[type] || []).map((item) => (
        <Grid.Item key={`${item.content}`} content={item.content} keywords={item.keywords} />
      ))}
    </Grid>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| tooltip<mark style="color:red;">*</mark> | Tooltip displayed when hovering the dropdown. | <code>string</code> | - |
| children | Dropdown sections or items. If Dropdown.Item elements are specified, a default section is automatically created. | <code>React.ReactNode</code> | - |
| 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. | <code>string</code> | - |
| 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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| id | ID of the dropdown. | <code>string</code> | - |
| isLoading | Indicates whether a loading indicator should be shown or hidden next to the search bar | <code>boolean</code> | `false` |
| placeholder | Placeholder text that will be shown in the dropdown search field. | <code>string</code> | `"Search…"` |
| storeValue | Indicates whether the value of the dropdown should be persisted after selection, and restored next time the dropdown is rendered. | <code>boolean</code> | - |
| 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). | <code>boolean</code> | `false` |
| value | The currently value of the dropdown. | <code>string</code> | - |
| onChange | Callback triggered when the dropdown selection changes. | <code>(newValue: string) => void</code> | - |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |

### Grid.Dropdown.Item

A dropdown item in a Grid.Dropdown

#### Example

```typescript
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid
      searchBarAccessory={
        <Grid.Dropdown tooltip="Dropdown With Items">
          <Grid.Dropdown.Item title="One" value="one" />
          <Grid.Dropdown.Item title="Two" value="two" />
          <Grid.Dropdown.Item title="Three" value="three" />
        </Grid.Dropdown>
      }
    >
      <Grid.Item content="https://placekitten.com/400/400" title="Item in the Main Grid" />
    </Grid>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title displayed for the item. | <code>string</code> | - |
| value<mark style="color:red;">*</mark> | Value of the dropdown item. Make sure to assign each unique value for each item. | <code>string</code> | - |
| icon | An optional icon displayed for the item. | <code>Image.ImageLike</code> | - |
| 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. | <code>string[]</code> | The title of its section if any |

### Grid.Dropdown.Section

Visually separated group of dropdown items.

Use sections to group related menu items together.

#### Example

```typescript
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid
      searchBarAccessory={
        <Grid.Dropdown tooltip="Dropdown With Sections">
          <Grid.Dropdown.Section title="First Section">
            <Grid.Dropdown.Item title="One" value="one" />
          </Grid.Dropdown.Section>
          <Grid.Dropdown.Section title="Second Section">
            <Grid.Dropdown.Item title="Two" value="two" />
          </Grid.Dropdown.Section>
        </Grid.Dropdown>
      }
    >
      <Grid.Item content="https://placekitten.com/400/400" title="Item in the Main Grid" />
    </Grid>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children | The item elements of the section. | <code>React.ReactNode</code> | - |
| title | Title displayed above the section | <code>string</code> | - |

### Grid.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 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.



#### Example

```typescript
import { useEffect, useState } from "react";
import { Grid, Image } from "@raycast/api";

export default function CommandWithCustomEmptyView() {
  const [state, setState] = useState<{
    searchText: string;
    items: { content: Image.ImageLike; title: string }[];
  }>({ searchText: "", items: [] });

  useEffect(() => {
    console.log("Running effect after state.searchText changed. Current value:", JSON.stringify(state.searchText));
    // perform an API call that eventually populates `items`.
  }, [state.searchText]);

  return (
    <Grid onSearchTextChange={(newValue) => setState((previous) => ({ ...previous, searchText: newValue }))}>
      {state.searchText === "" && state.items.length === 0 ? (
        <Grid.EmptyView icon={{ source: "https://placekitten.com/500/500" }} title="Type something to get started" />
      ) : (
        state.items.map((item, index) => <Grid.Item key={index} content={item.content} title={item.title} />)
      )}
    </Grid>
  );
}
```

#### Props

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

### Grid.Item

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.

#### Example

```typescript
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid>
      <Grid.Item content="🥳" title="Partying Face" subtitle="Smiley" />
    </Grid>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| content<mark style="color:red;">*</mark> | An image or color, optionally with a tooltip, representing the content of the grid item. | <code>Image.ImageLike } }</code> | - |
| accessory | An optional Grid.Item.Accessory</code> | - |
| actions | An ActionPanel that will be updated for the selected grid item. | <code>React.ReactNode</code> | - |
| id | ID of the item. This string is passed to the `onSelectionChange` handler of the Grid when the item is selected. Make sure to assign each item a unique ID or a UUID will be auto generated. | <code>string</code> | - |
| 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. | <code>string[]</code> | - |
| quickLook | Optional information to preview files with Quick Look. Toggle the preview ith Action.ToggleQuickLook. | <code>{ name?: string; path: string }</code> | - |
| subtitle | An optional subtitle displayed below the title. | <code>string</code> | - |
| title | An optional title displayed below the content. | <code>string</code> | - |

### Grid.Section

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.

#### Example



{% tabs %}
{% tab title="GridWithSection.tsx" %}

```typescript
import { Grid } from "@raycast/api";

export default function Command() {
  return (
    <Grid>
      <Grid.Section title="Section 1">
        <Grid.Item content="https://placekitten.com/400/400" title="Item 1" />
      </Grid.Section>
      <Grid.Section title="Section 2" subtitle="Optional subtitle">
        <Grid.Item content="https://placekitten.com/400/400" title="Item 1" />
      </Grid.Section>
    </Grid>
  );
}
```

{% endtab %}
{% tab title="GridWithStyledSection.tsx" %}

```typescript
import { Grid, Color } from "@raycast/api";

export default function Command() {
  return (
    <Grid columns={6}>
      <Grid.Section aspectRatio="2/3" title="Movies">
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
        <Grid.Item content="https://api.lorem.space/image/movie?w=150&h=220" />
      </Grid.Section>
      <Grid.Section columns={8} title="Colors">
        {Object.entries(Color).map(([key, value]) => (
          <Grid.Item key={key} content={{ color: value }} title={key} />
        ))}
      </Grid.Section>
    </Grid>
  );
}
```

{% endtab %}

{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| aspectRatio | Aspect ratio for the Grid.Item elements. Defaults to 1. | <code>"1"</code> or <code>"3/2"</code> or <code>"2/3"</code> or <code>"4/3"</code> or <code>"3/4"</code> or <code>"16/9"</code> or <code>"9/16"</code> | - |
| children | The Grid.Item elements of the section. | <code>React.ReactNode</code> | - |
| columns | Column count for the section. Minimum value is 1, maximum value is 8. | <code>number</code> | `5` |
| fit | Fit for the Grid.Item</code> | - |
| inset | Inset for the Grid.Item</code> | - |
| subtitle | An optional subtitle displayed next to the title of the section. | <code>string</code> | - |
| title | Title displayed above the section. | <code>string</code> | - |

## Types

### Grid.Item.Accessory

An interface describing an accessory view in a `Grid.Item`.



### Grid.Inset

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 `columns` prop.

#### Enumeration members

| Name   | Description   |
| ------ | ------------- |
| Small  | Small insets  |
| Medium | Medium insets |
| Large  | Large insets  |

### Grid.ItemSize (deprecated)

An enum representing the size of the Grid's child Grid.Items.

#### Enumeration members

| Name   | Description           |
| ------ | --------------------- |
| Small  | Fits 8 items per row. |
| Medium | Fits 5 items per row. |
| Large  | Fits 3 items per row. |

### Grid.Fit

An enum representing how Grid.Item's content should be fit.

#### Enumeration members

| Name    | Description                                                                                                                     |
| ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 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. |


# Icons & Images

## API Reference

### Icon

List of built-in icons that can be used for actions or list items.

#### Example

```typescript
import { Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Icon" icon={Icon.Circle} />
    </List>
  );
}
```

#### Enumeration members

| <p><picture><source srcset="../../.gitbook/assets/icon-add-person-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-add-person-16@light.svg" alt=""></picture><br>AddPerson</p> | <p><picture><source srcset="../../.gitbook/assets/icon-airplane-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-airplane-16@light.svg" alt=""></picture><br>Airplane</p> | <p><picture><source srcset="../../.gitbook/assets/icon-airplane-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-airplane-filled-16@light.svg" alt=""></picture><br>AirplaneFilled</p> |
| :---: | :---: | :---: |
| <p><picture><source srcset="../../.gitbook/assets/icon-airplane-landing-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-airplane-landing-16@light.svg" alt=""></picture><br>AirplaneLanding</p> | <p><picture><source srcset="../../.gitbook/assets/icon-airplane-takeoff-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-airplane-takeoff-16@light.svg" alt=""></picture><br>AirplaneTakeoff</p> | <p><picture><source srcset="../../.gitbook/assets/icon-airpods-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-airpods-16@light.svg" alt=""></picture><br>Airpods</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-alarm-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-alarm-16@light.svg" alt=""></picture><br>Alarm</p> | <p><picture><source srcset="../../.gitbook/assets/icon-alarm-ringing-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-alarm-ringing-16@light.svg" alt=""></picture><br>AlarmRinging</p> | <p><picture><source srcset="../../.gitbook/assets/icon-align-centre-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-align-centre-16@light.svg" alt=""></picture><br>AlignCentre</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-align-left-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-align-left-16@light.svg" alt=""></picture><br>AlignLeft</p> | <p><picture><source srcset="../../.gitbook/assets/icon-align-right-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-align-right-16@light.svg" alt=""></picture><br>AlignRight</p> | <p><picture><source srcset="../../.gitbook/assets/icon-american-football-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-american-football-16@light.svg" alt=""></picture><br>AmericanFootball</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-anchor-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-anchor-16@light.svg" alt=""></picture><br>Anchor</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-16@light.svg" alt=""></picture><br>AppWindow</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-grid-2x2-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-grid-2x2-16@light.svg" alt=""></picture><br>AppWindowGrid2x2</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-app-window-grid-3x3-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-grid-3x3-16@light.svg" alt=""></picture><br>AppWindowGrid3x3</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-list-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-list-16@light.svg" alt=""></picture><br>AppWindowList</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-sidebar-left-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-sidebar-left-16@light.svg" alt=""></picture><br>AppWindowSidebarLeft</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-app-window-sidebar-right-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-sidebar-right-16@light.svg" alt=""></picture><br>AppWindowSidebarRight</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-clockwise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-clockwise-16@light.svg" alt=""></picture><br>ArrowClockwise</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-counter-clockwise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-counter-clockwise-16@light.svg" alt=""></picture><br>ArrowCounterClockwise</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-arrow-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-down-16@light.svg" alt=""></picture><br>ArrowDown</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-down-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-down-circle-16@light.svg" alt=""></picture><br>ArrowDownCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-down-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-down-circle-filled-16@light.svg" alt=""></picture><br>ArrowDownCircleFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-arrow-left-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-left-16@light.svg" alt=""></picture><br>ArrowLeft</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-left-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-left-circle-16@light.svg" alt=""></picture><br>ArrowLeftCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-left-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-left-circle-filled-16@light.svg" alt=""></picture><br>ArrowLeftCircleFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-arrow-ne-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-ne-16@light.svg" alt=""></picture><br>ArrowNe</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-right-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-right-16@light.svg" alt=""></picture><br>ArrowRight</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-right-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-right-circle-16@light.svg" alt=""></picture><br>ArrowRightCircle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-arrow-right-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-right-circle-filled-16@light.svg" alt=""></picture><br>ArrowRightCircleFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-up-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-up-16@light.svg" alt=""></picture><br>ArrowUp</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrow-up-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-up-circle-16@light.svg" alt=""></picture><br>ArrowUpCircle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-arrow-up-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrow-up-circle-filled-16@light.svg" alt=""></picture><br>ArrowUpCircleFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrows-contract-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrows-contract-16@light.svg" alt=""></picture><br>ArrowsContract</p> | <p><picture><source srcset="../../.gitbook/assets/icon-arrows-expand-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-arrows-expand-16@light.svg" alt=""></picture><br>ArrowsExpand</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-at-symbol-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-at-symbol-16@light.svg" alt=""></picture><br>AtSymbol</p> | <p><picture><source srcset="../../.gitbook/assets/icon-band-aid-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-band-aid-16@light.svg" alt=""></picture><br>BandAid</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bank-note-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bank-note-16@light.svg" alt=""></picture><br>BankNote</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bar-chart-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bar-chart-16@light.svg" alt=""></picture><br>BarChart</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bar-code-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bar-code-16@light.svg" alt=""></picture><br>BarCode</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bath-tub-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bath-tub-16@light.svg" alt=""></picture><br>BathTub</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-battery-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-battery-16@light.svg" alt=""></picture><br>Battery</p> | <p><picture><source srcset="../../.gitbook/assets/icon-battery-charging-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-battery-charging-16@light.svg" alt=""></picture><br>BatteryCharging</p> | <p><picture><source srcset="../../.gitbook/assets/icon-battery-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-battery-disabled-16@light.svg" alt=""></picture><br>BatteryDisabled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bell-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bell-16@light.svg" alt=""></picture><br>Bell</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bell-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bell-disabled-16@light.svg" alt=""></picture><br>BellDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bike-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bike-16@light.svg" alt=""></picture><br>Bike</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-binoculars-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-binoculars-16@light.svg" alt=""></picture><br>Binoculars</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bird-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bird-16@light.svg" alt=""></picture><br>Bird</p> | <p><picture><source srcset="../../.gitbook/assets/icon-blank-document-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-blank-document-16@light.svg" alt=""></picture><br>BlankDocument</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bluetooth-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bluetooth-16@light.svg" alt=""></picture><br>Bluetooth</p> | <p><picture><source srcset="../../.gitbook/assets/icon-boat-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-boat-16@light.svg" alt=""></picture><br>Boat</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bold-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bold-16@light.svg" alt=""></picture><br>Bold</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bolt-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bolt-16@light.svg" alt=""></picture><br>Bolt</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bolt-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bolt-disabled-16@light.svg" alt=""></picture><br>BoltDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-book-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-book-16@light.svg" alt=""></picture><br>Book</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bookmark-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bookmark-16@light.svg" alt=""></picture><br>Bookmark</p> | <p><picture><source srcset="../../.gitbook/assets/icon-box-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-box-16@light.svg" alt=""></picture><br>Box</p> | <p><picture><source srcset="../../.gitbook/assets/icon-brush-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-brush-16@light.svg" alt=""></picture><br>Brush</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-speech-bubble-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speech-bubble-16@light.svg" alt=""></picture><br>Bubble</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bug-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bug-16@light.svg" alt=""></picture><br>Bug</p> | <p><picture><source srcset="../../.gitbook/assets/icon-building-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-building-16@light.svg" alt=""></picture><br>Building</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-bullet-points-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bullet-points-16@light.svg" alt=""></picture><br>BulletPoints</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bulls-eye-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bulls-eye-16@light.svg" alt=""></picture><br>BullsEye</p> | <p><picture><source srcset="../../.gitbook/assets/icon-bulls-eye-missed-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-bulls-eye-missed-16@light.svg" alt=""></picture><br>BullsEyeMissed</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-buoy-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-buoy-16@light.svg" alt=""></picture><br>Buoy</p> | <p><picture><source srcset="../../.gitbook/assets/icon-calculator-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-calculator-16@light.svg" alt=""></picture><br>Calculator</p> | <p><picture><source srcset="../../.gitbook/assets/icon-calendar-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-calendar-16@light.svg" alt=""></picture><br>Calendar</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-camera-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-camera-16@light.svg" alt=""></picture><br>Camera</p> | <p><picture><source srcset="../../.gitbook/assets/icon-car-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-car-16@light.svg" alt=""></picture><br>Car</p> | <p><picture><source srcset="../../.gitbook/assets/icon-cart-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cart-16@light.svg" alt=""></picture><br>Cart</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-cd-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cd-16@light.svg" alt=""></picture><br>Cd</p> | <p><picture><source srcset="../../.gitbook/assets/icon-center-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-center-16@light.svg" alt=""></picture><br>Center</p> | <p><picture><source srcset="../../.gitbook/assets/icon-check-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-check-16@light.svg" alt=""></picture><br>Check</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-check-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-check-circle-16@light.svg" alt=""></picture><br>CheckCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-check-list-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-check-list-16@light.svg" alt=""></picture><br>CheckList</p> | <p><picture><source srcset="../../.gitbook/assets/icon-check-rosette-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-check-rosette-16@light.svg" alt=""></picture><br>CheckRosette</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-checkmark-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-checkmark-16@light.svg" alt=""></picture><br>Checkmark</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chess-piece-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chess-piece-16@light.svg" alt=""></picture><br>ChessPiece</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-down-16@light.svg" alt=""></picture><br>ChevronDown</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-chevron-down-small-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-down-small-16@light.svg" alt=""></picture><br>ChevronDownSmall</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-left-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-left-16@light.svg" alt=""></picture><br>ChevronLeft</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-left-small-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-left-small-16@light.svg" alt=""></picture><br>ChevronLeftSmall</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-chevron-right-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-right-16@light.svg" alt=""></picture><br>ChevronRight</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-right-small-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-right-small-16@light.svg" alt=""></picture><br>ChevronRightSmall</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-up-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-up-16@light.svg" alt=""></picture><br>ChevronUp</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-chevron-up-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-up-down-16@light.svg" alt=""></picture><br>ChevronUpDown</p> | <p><picture><source srcset="../../.gitbook/assets/icon-chevron-up-small-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-chevron-up-small-16@light.svg" alt=""></picture><br>ChevronUpSmall</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-16@light.svg" alt=""></picture><br>Circle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-circle-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-disabled-16@light.svg" alt=""></picture><br>CircleDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-ellipsis-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-ellipsis-16@light.svg" alt=""></picture><br>CircleEllipsis</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-filled-16@light.svg" alt=""></picture><br>CircleFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-circle-progress-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-progress-16@light.svg" alt=""></picture><br>CircleProgress</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-progress-100-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-progress-100-16@light.svg" alt=""></picture><br>CircleProgress100</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-progress-25-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-progress-25-16@light.svg" alt=""></picture><br>CircleProgress25</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-circle-progress-50-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-progress-50-16@light.svg" alt=""></picture><br>CircleProgress50</p> | <p><picture><source srcset="../../.gitbook/assets/icon-circle-progress-75-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-circle-progress-75-16@light.svg" alt=""></picture><br>CircleProgress75</p> | <p><picture><source srcset="../../.gitbook/assets/icon-clear-formatting-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-clear-formatting-16@light.svg" alt=""></picture><br>ClearFormatting</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-copy-clipboard-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-copy-clipboard-16@light.svg" alt=""></picture><br>Clipboard</p> | <p><picture><source srcset="../../.gitbook/assets/icon-clock-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-clock-16@light.svg" alt=""></picture><br>Clock</p> | <p><picture><source srcset="../../.gitbook/assets/icon-cloud-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cloud-16@light.svg" alt=""></picture><br>Cloud</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-cloud-lightning-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cloud-lightning-16@light.svg" alt=""></picture><br>CloudLightning</p> | <p><picture><source srcset="../../.gitbook/assets/icon-cloud-rain-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cloud-rain-16@light.svg" alt=""></picture><br>CloudRain</p> | <p><picture><source srcset="../../.gitbook/assets/icon-cloud-snow-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cloud-snow-16@light.svg" alt=""></picture><br>CloudSnow</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-cloud-sun-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cloud-sun-16@light.svg" alt=""></picture><br>CloudSun</p> | <p><picture><source srcset="../../.gitbook/assets/icon-code-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-code-16@light.svg" alt=""></picture><br>Code</p> | <p><picture><source srcset="../../.gitbook/assets/icon-code-block-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-code-block-16@light.svg" alt=""></picture><br>CodeBlock</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-cog-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cog-16@light.svg" alt=""></picture><br>Cog</p> | <p><picture><source srcset="../../.gitbook/assets/icon-coin-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-coin-16@light.svg" alt=""></picture><br>Coin</p> | <p><picture><source srcset="../../.gitbook/assets/icon-coins-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-coins-16@light.svg" alt=""></picture><br>Coins</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-command-symbol-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-command-symbol-16@light.svg" alt=""></picture><br>CommandSymbol</p> | <p><picture><source srcset="../../.gitbook/assets/icon-compass-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-compass-16@light.svg" alt=""></picture><br>Compass</p> | <p><picture><source srcset="../../.gitbook/assets/icon-computer-chip-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-computer-chip-16@light.svg" alt=""></picture><br>ComputerChip</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-contrast-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-contrast-16@light.svg" alt=""></picture><br>Contrast</p> | <p><picture><source srcset="../../.gitbook/assets/icon-copy-clipboard-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-copy-clipboard-16@light.svg" alt=""></picture><br>CopyClipboard</p> | <p><picture><source srcset="../../.gitbook/assets/icon-credit-card-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-credit-card-16@light.svg" alt=""></picture><br>CreditCard</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-cricket-ball-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cricket-ball-16@light.svg" alt=""></picture><br>CricketBall</p> | <p><picture><source srcset="../../.gitbook/assets/icon-crop-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-crop-16@light.svg" alt=""></picture><br>Crop</p> | <p><picture><source srcset="../../.gitbook/assets/icon-crown-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-crown-16@light.svg" alt=""></picture><br>Crown</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-crypto-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-crypto-16@light.svg" alt=""></picture><br>Crypto</p> | <p><picture><source srcset="../../.gitbook/assets/icon-delete-document-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-delete-document-16@light.svg" alt=""></picture><br>DeleteDocument</p> | <p><picture><source srcset="../../.gitbook/assets/icon-desktop-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-desktop-16@light.svg" alt=""></picture><br>Desktop</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-devices-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-devices-16@light.svg" alt=""></picture><br>Devices</p> | <p><picture><source srcset="../../.gitbook/assets/icon-dna-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-dna-16@light.svg" alt=""></picture><br>Dna</p> | <p><picture><source srcset="../../.gitbook/assets/icon-blank-document-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-blank-document-16@light.svg" alt=""></picture><br>Document</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-dot-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-dot-16@light.svg" alt=""></picture><br>Dot</p> | <p><picture><source srcset="../../.gitbook/assets/icon-download-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-download-16@light.svg" alt=""></picture><br>Download</p> | <p><picture><source srcset="../../.gitbook/assets/icon-droplets-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-droplets-16@light.svg" alt=""></picture><br>Droplets</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-duplicate-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-duplicate-16@light.svg" alt=""></picture><br>Duplicate</p> | <p><picture><source srcset="../../.gitbook/assets/icon-edit-shape-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-edit-shape-16@light.svg" alt=""></picture><br>EditShape</p> | <p><picture><source srcset="../../.gitbook/assets/icon-eject-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-eject-16@light.svg" alt=""></picture><br>Eject</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-ellipsis-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-ellipsis-16@light.svg" alt=""></picture><br>Ellipsis</p> | <p><picture><source srcset="../../.gitbook/assets/icon-emoji-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-emoji-16@light.svg" alt=""></picture><br>Emoji</p> | <p><picture><source srcset="../../.gitbook/assets/icon-emoji-sad-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-emoji-sad-16@light.svg" alt=""></picture><br>EmojiSad</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-envelope-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-envelope-16@light.svg" alt=""></picture><br>Envelope</p> | <p><picture><source srcset="../../.gitbook/assets/icon-eraser-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-eraser-16@light.svg" alt=""></picture><br>Eraser</p> | <p><picture><source srcset="../../.gitbook/assets/icon-important-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-important-01-16@light.svg" alt=""></picture><br>ExclamationMark</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-exclamationmark-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-exclamationmark-16@light.svg" alt=""></picture><br>Exclamationmark</p> | <p><picture><source srcset="../../.gitbook/assets/icon-exclamationmark-2-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-exclamationmark-2-16@light.svg" alt=""></picture><br>Exclamationmark2</p> | <p><picture><source srcset="../../.gitbook/assets/icon-exclamationmark-3-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-exclamationmark-3-16@light.svg" alt=""></picture><br>Exclamationmark3</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-eye-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-eye-16@light.svg" alt=""></picture><br>Eye</p> | <p><picture><source srcset="../../.gitbook/assets/icon-eye-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-eye-disabled-16@light.svg" alt=""></picture><br>EyeDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-eye-dropper-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-eye-dropper-16@light.svg" alt=""></picture><br>EyeDropper</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-female-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-female-16@light.svg" alt=""></picture><br>Female</p> | <p><picture><source srcset="../../.gitbook/assets/icon-film-strip-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-film-strip-16@light.svg" alt=""></picture><br>FilmStrip</p> | <p><picture><source srcset="../../.gitbook/assets/icon-filter-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-filter-16@light.svg" alt=""></picture><br>Filter</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-finder-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-finder-16@light.svg" alt=""></picture><br>Finder</p> | <p><picture><source srcset="../../.gitbook/assets/icon-fingerprint-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-fingerprint-16@light.svg" alt=""></picture><br>Fingerprint</p> | <p><picture><source srcset="../../.gitbook/assets/icon-flag-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-flag-16@light.svg" alt=""></picture><br>Flag</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-folder-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-folder-16@light.svg" alt=""></picture><br>Folder</p> | <p><picture><source srcset="../../.gitbook/assets/icon-footprints-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-footprints-16@light.svg" alt=""></picture><br>Footprints</p> | <p><picture><source srcset="../../.gitbook/assets/icon-forward-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-forward-16@light.svg" alt=""></picture><br>Forward</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-forward-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-forward-filled-16@light.svg" alt=""></picture><br>ForwardFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-fountain-tip-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-fountain-tip-16@light.svg" alt=""></picture><br>FountainTip</p> | <p><picture><source srcset="../../.gitbook/assets/icon-full-signal-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-full-signal-16@light.svg" alt=""></picture><br>FullSignal</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-game-controller-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-game-controller-16@light.svg" alt=""></picture><br>GameController</p> | <p><picture><source srcset="../../.gitbook/assets/icon-gauge-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-gauge-16@light.svg" alt=""></picture><br>Gauge</p> | <p><picture><source srcset="../../.gitbook/assets/icon-cog-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-cog-16@light.svg" alt=""></picture><br>Gear</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-geopin-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-geopin-16@light.svg" alt=""></picture><br>Geopin</p> | <p><picture><source srcset="../../.gitbook/assets/icon-germ-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-germ-16@light.svg" alt=""></picture><br>Germ</p> | <p><picture><source srcset="../../.gitbook/assets/icon-gift-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-gift-16@light.svg" alt=""></picture><br>Gift</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-glasses-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-glasses-16@light.svg" alt=""></picture><br>Glasses</p> | <p><picture><source srcset="../../.gitbook/assets/icon-globe-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-globe-01-16@light.svg" alt=""></picture><br>Globe</p> | <p><picture><source srcset="../../.gitbook/assets/icon-goal-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-goal-16@light.svg" alt=""></picture><br>Goal</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-hammer-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-hammer-16@light.svg" alt=""></picture><br>Hammer</p> | <p><picture><source srcset="../../.gitbook/assets/icon-hard-drive-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-hard-drive-16@light.svg" alt=""></picture><br>HardDrive</p> | <p><picture><source srcset="../../.gitbook/assets/icon-hashtag-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-hashtag-16@light.svg" alt=""></picture><br>Hashtag</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-heading-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-heading-16@light.svg" alt=""></picture><br>Heading</p> | <p><picture><source srcset="../../.gitbook/assets/icon-headphones-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-headphones-16@light.svg" alt=""></picture><br>Headphones</p> | <p><picture><source srcset="../../.gitbook/assets/icon-heart-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-heart-16@light.svg" alt=""></picture><br>Heart</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-heart-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-heart-disabled-16@light.svg" alt=""></picture><br>HeartDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-heartbeat-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-heartbeat-16@light.svg" alt=""></picture><br>Heartbeat</p> | <p><picture><source srcset="../../.gitbook/assets/icon-highlight-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-highlight-16@light.svg" alt=""></picture><br>Highlight</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-hourglass-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-hourglass-16@light.svg" alt=""></picture><br>Hourglass</p> | <p><picture><source srcset="../../.gitbook/assets/icon-house-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-house-16@light.svg" alt=""></picture><br>House</p> | <p><picture><source srcset="../../.gitbook/assets/icon-humidity-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-humidity-16@light.svg" alt=""></picture><br>Humidity</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-image-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-image-16@light.svg" alt=""></picture><br>Image</p> | <p><picture><source srcset="../../.gitbook/assets/icon-important-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-important-01-16@light.svg" alt=""></picture><br>Important</p> | <p><picture><source srcset="../../.gitbook/assets/icon-info-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-info-01-16@light.svg" alt=""></picture><br>Info</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-italics-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-italics-16@light.svg" alt=""></picture><br>Italics</p> | <p><picture><source srcset="../../.gitbook/assets/icon-key-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-key-16@light.svg" alt=""></picture><br>Key</p> | <p><picture><source srcset="../../.gitbook/assets/icon-keyboard-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-keyboard-16@light.svg" alt=""></picture><br>Keyboard</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-layers-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-layers-16@light.svg" alt=""></picture><br>Layers</p> | <p><picture><source srcset="../../.gitbook/assets/icon-leaderboard-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-leaderboard-16@light.svg" alt=""></picture><br>Leaderboard</p> | <p><picture><source srcset="../../.gitbook/assets/icon-leaf-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-leaf-16@light.svg" alt=""></picture><br>Leaf</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-signal-2-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-signal-2-16@light.svg" alt=""></picture><br>LevelMeter</p> | <p><picture><source srcset="../../.gitbook/assets/icon-light-bulb-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-light-bulb-16@light.svg" alt=""></picture><br>LightBulb</p> | <p><picture><source srcset="../../.gitbook/assets/icon-light-bulb-off-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-light-bulb-off-16@light.svg" alt=""></picture><br>LightBulbOff</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-line-chart-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-line-chart-16@light.svg" alt=""></picture><br>LineChart</p> | <p><picture><source srcset="../../.gitbook/assets/icon-link-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-link-16@light.svg" alt=""></picture><br>Link</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-list-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-list-16@light.svg" alt=""></picture><br>List</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-livestream-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-livestream-01-16@light.svg" alt=""></picture><br>Livestream</p> | <p><picture><source srcset="../../.gitbook/assets/icon-livestream-disabled-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-livestream-disabled-01-16@light.svg" alt=""></picture><br>LivestreamDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-lock-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-lock-16@light.svg" alt=""></picture><br>Lock</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-lock-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-lock-disabled-16@light.svg" alt=""></picture><br>LockDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-lock-unlocked-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-lock-unlocked-16@light.svg" alt=""></picture><br>LockUnlocked</p> | <p><picture><source srcset="../../.gitbook/assets/icon-logout-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-logout-16@light.svg" alt=""></picture><br>Logout</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-lorry-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-lorry-16@light.svg" alt=""></picture><br>Lorry</p> | <p><picture><source srcset="../../.gitbook/assets/icon-lowercase-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-lowercase-16@light.svg" alt=""></picture><br>Lowercase</p> | <p><picture><source srcset="../../.gitbook/assets/icon-magnifying-glass-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-magnifying-glass-16@light.svg" alt=""></picture><br>MagnifyingGlass</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-male-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-male-16@light.svg" alt=""></picture><br>Male</p> | <p><picture><source srcset="../../.gitbook/assets/icon-map-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-map-16@light.svg" alt=""></picture><br>Map</p> | <p><picture><source srcset="../../.gitbook/assets/icon-mask-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mask-16@light.svg" alt=""></picture><br>Mask</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-maximize-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-maximize-16@light.svg" alt=""></picture><br>Maximize</p> | <p><picture><source srcset="../../.gitbook/assets/icon-medical-support-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-medical-support-16@light.svg" alt=""></picture><br>MedicalSupport</p> | <p><picture><source srcset="../../.gitbook/assets/icon-megaphone-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-megaphone-16@light.svg" alt=""></picture><br>Megaphone</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-computer-chip-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-computer-chip-16@light.svg" alt=""></picture><br>MemoryChip</p> | <p><picture><source srcset="../../.gitbook/assets/icon-memory-stick-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-memory-stick-16@light.svg" alt=""></picture><br>MemoryStick</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speech-bubble-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speech-bubble-16@light.svg" alt=""></picture><br>Message</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-microphone-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-microphone-16@light.svg" alt=""></picture><br>Microphone</p> | <p><picture><source srcset="../../.gitbook/assets/icon-microphone-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-microphone-disabled-16@light.svg" alt=""></picture><br>MicrophoneDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-minimize-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-minimize-16@light.svg" alt=""></picture><br>Minimize</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-minus-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-minus-16@light.svg" alt=""></picture><br>Minus</p> | <p><picture><source srcset="../../.gitbook/assets/icon-minus-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-minus-circle-16@light.svg" alt=""></picture><br>MinusCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-minus-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-minus-circle-filled-16@light.svg" alt=""></picture><br>MinusCircleFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-mobile-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mobile-16@light.svg" alt=""></picture><br>Mobile</p> | <p><picture><source srcset="../../.gitbook/assets/icon-monitor-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-monitor-16@light.svg" alt=""></picture><br>Monitor</p> | <p><picture><source srcset="../../.gitbook/assets/icon-moon-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-moon-16@light.svg" alt=""></picture><br>Moon</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-moon-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-moon-down-16@light.svg" alt=""></picture><br>MoonDown</p> | <p><picture><source srcset="../../.gitbook/assets/icon-moon-up-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-moon-up-16@light.svg" alt=""></picture><br>MoonUp</p> | <p><picture><source srcset="../../.gitbook/assets/icon-moonrise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-moonrise-16@light.svg" alt=""></picture><br>Moonrise</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-mountain-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mountain-16@light.svg" alt=""></picture><br>Mountain</p> | <p><picture><source srcset="../../.gitbook/assets/icon-mouse-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mouse-16@light.svg" alt=""></picture><br>Mouse</p> | <p><picture><source srcset="../../.gitbook/assets/icon-move-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-move-16@light.svg" alt=""></picture><br>Move</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-mug-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mug-16@light.svg" alt=""></picture><br>Mug</p> | <p><picture><source srcset="../../.gitbook/assets/icon-mug-steam-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-mug-steam-16@light.svg" alt=""></picture><br>MugSteam</p> | <p><picture><source srcset="../../.gitbook/assets/icon-multiply-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-multiply-16@light.svg" alt=""></picture><br>Multiply</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-music-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-music-16@light.svg" alt=""></picture><br>Music</p> | <p><picture><source srcset="../../.gitbook/assets/icon-network-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-network-16@light.svg" alt=""></picture><br>Network</p> | <p><picture><source srcset="../../.gitbook/assets/icon-new-document-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-new-document-16@light.svg" alt=""></picture><br>NewDocument</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-new-folder-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-new-folder-16@light.svg" alt=""></picture><br>NewFolder</p> | <p><picture><source srcset="../../.gitbook/assets/icon-paperclip-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-paperclip-16@light.svg" alt=""></picture><br>Paperclip</p> | <p><picture><source srcset="../../.gitbook/assets/icon-paragraph-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-paragraph-16@light.svg" alt=""></picture><br>Paragraph</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-patch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-patch-16@light.svg" alt=""></picture><br>Patch</p> | <p><picture><source srcset="../../.gitbook/assets/icon-pause-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pause-16@light.svg" alt=""></picture><br>Pause</p> | <p><picture><source srcset="../../.gitbook/assets/icon-pause-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pause-filled-16@light.svg" alt=""></picture><br>PauseFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-pencil-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pencil-16@light.svg" alt=""></picture><br>Pencil</p> | <p><picture><source srcset="../../.gitbook/assets/icon-person-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-person-16@light.svg" alt=""></picture><br>Person</p> | <p><picture><source srcset="../../.gitbook/assets/icon-person-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-person-circle-16@light.svg" alt=""></picture><br>PersonCircle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-person-lines-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-person-lines-16@light.svg" alt=""></picture><br>PersonLines</p> | <p><picture><source srcset="../../.gitbook/assets/icon-phone-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-phone-16@light.svg" alt=""></picture><br>Phone</p> | <p><picture><source srcset="../../.gitbook/assets/icon-phone-ringing-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-phone-ringing-16@light.svg" alt=""></picture><br>PhoneRinging</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-pie-chart-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pie-chart-16@light.svg" alt=""></picture><br>PieChart</p> | <p><picture><source srcset="../../.gitbook/assets/icon-pill-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pill-16@light.svg" alt=""></picture><br>Pill</p> | <p><picture><source srcset="../../.gitbook/assets/icon-pin-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pin-16@light.svg" alt=""></picture><br>Pin</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-pin-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-pin-disabled-16@light.svg" alt=""></picture><br>PinDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-play-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-play-16@light.svg" alt=""></picture><br>Play</p> | <p><picture><source srcset="../../.gitbook/assets/icon-play-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-play-filled-16@light.svg" alt=""></picture><br>PlayFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-plug-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plug-16@light.svg" alt=""></picture><br>Plug</p> | <p><picture><source srcset="../../.gitbook/assets/icon-plus-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-16@light.svg" alt=""></picture><br>Plus</p> | <p><picture><source srcset="../../.gitbook/assets/icon-plus-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-circle-16@light.svg" alt=""></picture><br>PlusCircle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-plus-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-circle-filled-16@light.svg" alt=""></picture><br>PlusCircleFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-plus-minus-divide-multiply-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-minus-divide-multiply-16@light.svg" alt=""></picture><br>PlusMinusDivideMultiply</p> | <p><picture><source srcset="../../.gitbook/assets/icon-plus-square-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-square-16@light.svg" alt=""></picture><br>PlusSquare</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-plus-top-right-square-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-plus-top-right-square-16@light.svg" alt=""></picture><br>PlusTopRightSquare</p> | <p><picture><source srcset="../../.gitbook/assets/icon-power-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-power-16@light.svg" alt=""></picture><br>Power</p> | <p><picture><source srcset="../../.gitbook/assets/icon-print-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-print-16@light.svg" alt=""></picture><br>Print</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-question-mark-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-question-mark-circle-16@light.svg" alt=""></picture><br>QuestionMark</p> | <p><picture><source srcset="../../.gitbook/assets/icon-question-mark-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-question-mark-circle-16@light.svg" alt=""></picture><br>QuestionMarkCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-quotation-marks-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-quotation-marks-16@light.svg" alt=""></picture><br>QuotationMarks</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-quote-block-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-quote-block-16@light.svg" alt=""></picture><br>QuoteBlock</p> | <p><picture><source srcset="../../.gitbook/assets/icon-racket-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-racket-16@light.svg" alt=""></picture><br>Racket</p> | <p><picture><source srcset="../../.gitbook/assets/icon-raindrop-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-raindrop-16@light.svg" alt=""></picture><br>Raindrop</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-raycast-logo-neg-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-raycast-logo-neg-16@light.svg" alt=""></picture><br>RaycastLogoNeg</p> | <p><picture><source srcset="../../.gitbook/assets/icon-raycast-logo-pos-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-raycast-logo-pos-16@light.svg" alt=""></picture><br>RaycastLogoPos</p> | <p><picture><source srcset="../../.gitbook/assets/icon-receipt-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-receipt-16@light.svg" alt=""></picture><br>Receipt</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-redo-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-redo-16@light.svg" alt=""></picture><br>Redo</p> | <p><picture><source srcset="../../.gitbook/assets/icon-remove-person-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-remove-person-16@light.svg" alt=""></picture><br>RemovePerson</p> | <p><picture><source srcset="../../.gitbook/assets/icon-repeat-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-repeat-16@light.svg" alt=""></picture><br>Repeat</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-replace-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-replace-16@light.svg" alt=""></picture><br>Replace</p> | <p><picture><source srcset="../../.gitbook/assets/icon-replace-one-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-replace-one-16@light.svg" alt=""></picture><br>ReplaceOne</p> | <p><picture><source srcset="../../.gitbook/assets/icon-reply-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-reply-16@light.svg" alt=""></picture><br>Reply</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-rewind-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rewind-16@light.svg" alt=""></picture><br>Rewind</p> | <p><picture><source srcset="../../.gitbook/assets/icon-rewind-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rewind-filled-16@light.svg" alt=""></picture><br>RewindFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-rocket-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rocket-16@light.svg" alt=""></picture><br>Rocket</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-rosette-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rosette-16@light.svg" alt=""></picture><br>Rosette</p> | <p><picture><source srcset="../../.gitbook/assets/icon-rotate-anti-clockwise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rotate-anti-clockwise-16@light.svg" alt=""></picture><br>RotateAntiClockwise</p> | <p><picture><source srcset="../../.gitbook/assets/icon-rotate-clockwise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rotate-clockwise-16@light.svg" alt=""></picture><br>RotateClockwise</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-rss-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-rss-16@light.svg" alt=""></picture><br>Rss</p> | <p><picture><source srcset="../../.gitbook/assets/icon-ruler-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-ruler-16@light.svg" alt=""></picture><br>Ruler</p> | <p><picture><source srcset="../../.gitbook/assets/icon-save-document-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-save-document-16@light.svg" alt=""></picture><br>SaveDocument</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-shield-01-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-shield-01-16@light.svg" alt=""></picture><br>Shield</p> | <p><picture><source srcset="../../.gitbook/assets/icon-short-paragraph-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-short-paragraph-16@light.svg" alt=""></picture><br>ShortParagraph</p> | <p><picture><source srcset="../../.gitbook/assets/icon-shuffle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-shuffle-16@light.svg" alt=""></picture><br>Shuffle</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-app-window-sidebar-right-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-sidebar-right-16@light.svg" alt=""></picture><br>Sidebar</p> | <p><picture><source srcset="../../.gitbook/assets/icon-signal-0-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-signal-0-16@light.svg" alt=""></picture><br>Signal0</p> | <p><picture><source srcset="../../.gitbook/assets/icon-signal-1-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-signal-1-16@light.svg" alt=""></picture><br>Signal1</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-signal-2-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-signal-2-16@light.svg" alt=""></picture><br>Signal2</p> | <p><picture><source srcset="../../.gitbook/assets/icon-signal-3-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-signal-3-16@light.svg" alt=""></picture><br>Signal3</p> | <p><picture><source srcset="../../.gitbook/assets/icon-snippets-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-snippets-16@light.svg" alt=""></picture><br>Snippets</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-snowflake-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-snowflake-16@light.svg" alt=""></picture><br>Snowflake</p> | <p><picture><source srcset="../../.gitbook/assets/icon-soccer-ball-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-soccer-ball-16@light.svg" alt=""></picture><br>SoccerBall</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speaker-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-16@light.svg" alt=""></picture><br>Speaker</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-speaker-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-down-16@light.svg" alt=""></picture><br>SpeakerDown</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speaker-high-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-high-16@light.svg" alt=""></picture><br>SpeakerHigh</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speaker-low-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-low-16@light.svg" alt=""></picture><br>SpeakerLow</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-speaker-off-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-off-16@light.svg" alt=""></picture><br>SpeakerOff</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speaker-on-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-on-16@light.svg" alt=""></picture><br>SpeakerOn</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speaker-up-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speaker-up-16@light.svg" alt=""></picture><br>SpeakerUp</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-speech-bubble-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speech-bubble-16@light.svg" alt=""></picture><br>SpeechBubble</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speech-bubble-active-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speech-bubble-active-16@light.svg" alt=""></picture><br>SpeechBubbleActive</p> | <p><picture><source srcset="../../.gitbook/assets/icon-speech-bubble-important-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-speech-bubble-important-16@light.svg" alt=""></picture><br>SpeechBubbleImportant</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-square-ellipsis-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-square-ellipsis-16@light.svg" alt=""></picture><br>SquareEllipsis</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stacked-bars-1-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stacked-bars-1-16@light.svg" alt=""></picture><br>StackedBars1</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stacked-bars-2-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stacked-bars-2-16@light.svg" alt=""></picture><br>StackedBars2</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-stacked-bars-3-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stacked-bars-3-16@light.svg" alt=""></picture><br>StackedBars3</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stacked-bars-4-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stacked-bars-4-16@light.svg" alt=""></picture><br>StackedBars4</p> | <p><picture><source srcset="../../.gitbook/assets/icon-star-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-star-16@light.svg" alt=""></picture><br>Star</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-star-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-star-circle-16@light.svg" alt=""></picture><br>StarCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-star-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-star-disabled-16@light.svg" alt=""></picture><br>StarDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stars-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stars-16@light.svg" alt=""></picture><br>Stars</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-stop-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stop-16@light.svg" alt=""></picture><br>Stop</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stop-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stop-filled-16@light.svg" alt=""></picture><br>StopFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-stopwatch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-stopwatch-16@light.svg" alt=""></picture><br>Stopwatch</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-store-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-store-16@light.svg" alt=""></picture><br>Store</p> | <p><picture><source srcset="../../.gitbook/assets/icon-strike-through-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-strike-through-16@light.svg" alt=""></picture><br>StrikeThrough</p> | <p><picture><source srcset="../../.gitbook/assets/icon-sun-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-sun-16@light.svg" alt=""></picture><br>Sun</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-sunrise-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-sunrise-16@light.svg" alt=""></picture><br>Sunrise</p> | <p><picture><source srcset="../../.gitbook/assets/icon-swatch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-swatch-16@light.svg" alt=""></picture><br>Swatch</p> | <p><picture><source srcset="../../.gitbook/assets/icon-switch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-switch-16@light.svg" alt=""></picture><br>Switch</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-syringe-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-syringe-16@light.svg" alt=""></picture><br>Syringe</p> | <p><picture><source srcset="../../.gitbook/assets/icon-tack-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tack-16@light.svg" alt=""></picture><br>Tack</p> | <p><picture><source srcset="../../.gitbook/assets/icon-tack-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tack-disabled-16@light.svg" alt=""></picture><br>TackDisabled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-tag-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tag-16@light.svg" alt=""></picture><br>Tag</p> | <p><picture><source srcset="../../.gitbook/assets/icon-temperature-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-temperature-16@light.svg" alt=""></picture><br>Temperature</p> | <p><picture><source srcset="../../.gitbook/assets/icon-tennis-ball-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tennis-ball-16@light.svg" alt=""></picture><br>TennisBall</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-terminal-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-terminal-16@light.svg" alt=""></picture><br>Terminal</p> | <p><picture><source srcset="../../.gitbook/assets/icon-text-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-text-16@light.svg" alt=""></picture><br>Text</p> | <p><picture><source srcset="../../.gitbook/assets/icon-text-cursor-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-text-cursor-16@light.svg" alt=""></picture><br>TextCursor</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-text-input-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-text-input-16@light.svg" alt=""></picture><br>TextInput</p> | <p><picture><source srcset="../../.gitbook/assets/icon-text-selection-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-text-selection-16@light.svg" alt=""></picture><br>TextSelection</p> | <p><picture><source srcset="../../.gitbook/assets/icon-thumbs-down-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-thumbs-down-16@light.svg" alt=""></picture><br>ThumbsDown</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-thumbs-down-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-thumbs-down-filled-16@light.svg" alt=""></picture><br>ThumbsDownFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-thumbs-up-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-thumbs-up-16@light.svg" alt=""></picture><br>ThumbsUp</p> | <p><picture><source srcset="../../.gitbook/assets/icon-thumbs-up-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-thumbs-up-filled-16@light.svg" alt=""></picture><br>ThumbsUpFilled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-ticket-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-ticket-16@light.svg" alt=""></picture><br>Ticket</p> | <p><picture><source srcset="../../.gitbook/assets/icon-torch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-torch-16@light.svg" alt=""></picture><br>Torch</p> | <p><picture><source srcset="../../.gitbook/assets/icon-train-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-train-16@light.svg" alt=""></picture><br>Train</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-trash-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-trash-16@light.svg" alt=""></picture><br>Trash</p> | <p><picture><source srcset="../../.gitbook/assets/icon-tray-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tray-16@light.svg" alt=""></picture><br>Tray</p> | <p><picture><source srcset="../../.gitbook/assets/icon-tree-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-tree-16@light.svg" alt=""></picture><br>Tree</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-trophy-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-trophy-16@light.svg" alt=""></picture><br>Trophy</p> | <p><picture><source srcset="../../.gitbook/assets/icon-two-people-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-two-people-16@light.svg" alt=""></picture><br>TwoPeople</p> | <p><picture><source srcset="../../.gitbook/assets/icon-umbrella-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-umbrella-16@light.svg" alt=""></picture><br>Umbrella</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-underline-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-underline-16@light.svg" alt=""></picture><br>Underline</p> | <p><picture><source srcset="../../.gitbook/assets/icon-undo-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-undo-16@light.svg" alt=""></picture><br>Undo</p> | <p><picture><source srcset="../../.gitbook/assets/icon-upload-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-upload-16@light.svg" alt=""></picture><br>Upload</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-uppercase-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-uppercase-16@light.svg" alt=""></picture><br>Uppercase</p> | <p><picture><source srcset="../../.gitbook/assets/icon-video-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-video-16@light.svg" alt=""></picture><br>Video</p> | <p><picture><source srcset="../../.gitbook/assets/icon-video-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-video-disabled-16@light.svg" alt=""></picture><br>VideoDisabled</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-wallet-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wallet-16@light.svg" alt=""></picture><br>Wallet</p> | <p><picture><source srcset="../../.gitbook/assets/icon-wand-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wand-16@light.svg" alt=""></picture><br>Wand</p> | <p><picture><source srcset="../../.gitbook/assets/icon-warning-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-warning-16@light.svg" alt=""></picture><br>Warning</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-waveform-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-waveform-16@light.svg" alt=""></picture><br>Waveform</p> | <p><picture><source srcset="../../.gitbook/assets/icon-weights-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-weights-16@light.svg" alt=""></picture><br>Weights</p> | <p><picture><source srcset="../../.gitbook/assets/icon-wifi-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wifi-16@light.svg" alt=""></picture><br>Wifi</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-wifi-disabled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wifi-disabled-16@light.svg" alt=""></picture><br>WifiDisabled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-wind-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wind-16@light.svg" alt=""></picture><br>Wind</p> | <p><picture><source srcset="../../.gitbook/assets/icon-app-window-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-app-window-16@light.svg" alt=""></picture><br>Window</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-windsock-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-windsock-16@light.svg" alt=""></picture><br>Windsock</p> | <p><picture><source srcset="../../.gitbook/assets/icon-wrench-screwdriver-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wrench-screwdriver-16@light.svg" alt=""></picture><br>WrenchScrewdriver</p> | <p><picture><source srcset="../../.gitbook/assets/icon-wrist-watch-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-wrist-watch-16@light.svg" alt=""></picture><br>WristWatch</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-x-mark-circle-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-x-mark-circle-16@light.svg" alt=""></picture><br>XMarkCircle</p> | <p><picture><source srcset="../../.gitbook/assets/icon-x-mark-circle-filled-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-x-mark-circle-filled-16@light.svg" alt=""></picture><br>XMarkCircleFilled</p> | <p><picture><source srcset="../../.gitbook/assets/icon-x-mark-circle-half-dash-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-x-mark-circle-half-dash-16@light.svg" alt=""></picture><br>XMarkCircleHalfDash</p> |
| <p><picture><source srcset="../../.gitbook/assets/icon-x-mark-top-right-square-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-x-mark-top-right-square-16@light.svg" alt=""></picture><br>XMarkTopRightSquare</p> | <p><picture><source srcset="../../.gitbook/assets/icon-xmark-16@dark.svg" media="(prefers-color-scheme: dark)"><img src="../../.gitbook/assets/icon-xmark-16@light.svg" alt=""></picture><br>Xmark</p> |

### Image.Mask

Available masks that can be used to change the shape of an image.

Can be handy to shape avatars or other items in a list.

#### Example

```typescript
import { Image, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Icon"
        icon={{
          source: "https://raycast.com/uploads/avatar.png",
          mask: Image.Mask.Circle,
        }}
      />
    </List>
  );
}
```

#### Enumeration members

| Name             | Value              |
| :--------------- | :----------------- |
| Circle           | "circle"           |
| RoundedRectangle | "roundedRectangle" |

## Types

### Image

Display different types of images, including network images or bundled assets.

Apply image transforms to the source, such as a `mask` or a `tintColor`.

{% hint style="info" %}
Tip: Suffix your local assets with `@dark` to automatically provide a dark theme option, eg: `icon.png` and `icon@dark.png`.
{% endhint %}

#### Example

```typescript
// Built-in icon
const icon = Icon.Eye;

// Built-in icon with tint color
const tintedIcon = { source: Icon.Bubble, tintColor: Color.Red };

// Bundled asset with circular mask
const avatar = { source: "avatar.png", mask: Image.Mask.Circle };

// Implicit theme-aware icon
// with 'icon.png' and 'icon@dark.png' in the `assets` folder
const icon = "icon.png";

// Explicit theme-aware icon
const icon = { source: { light: "https://example.com/icon-light.png", dark: "https://example.com/icon-dark.png" } };
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| source<mark style="color:red;">*</mark> | The Image.Source</code> |
| fallback | Image.Fallback</code> |
| mask | A Image.Mask</code> |
| tintColor | A Color.ColorLike</code> |

### FileIcon

An icon as it's used in the Finder.

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="File icon" icon={{ fileIcon: __filename }} />
    </List>
  );
}
```

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| fileIcon<mark style="color:red;">*</mark> | The path to a file or folder to get its icon from. | <code>string</code> |

### Image.ImageLike

```typescript
ImageLike: URL | Asset | Icon | FileIcon | Image;
```

Union type for the supported image types.

#### Example

```typescript
import { Icon, Image, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="URL" icon="https://raycast.com/uploads/avatar.png" />
      <List.Item title="Asset" icon="avatar.png" />
      <List.Item title="Icon" icon={Icon.Circle} />
      <List.Item title="FileIcon" icon={{ fileIcon: __filename }} />
      <List.Item
        title="Image"
        icon={{
          source: "https://raycast.com/uploads/avatar.png",
          mask: Image.Mask.Circle,
        }}
      />
    </List>
  );
}
```

### Image.Source

```typescript
Image.Source: URL | Asset | Icon | { light: URL | Asset; dark: URL | Asset }
```

The source of an Image or
a single emoji.

For consistency, it's best to use the built-in Icon in lists, the Action Panel, and other places. If a
specific icon isn't built-in, you can reference custom ones from the `assets` folder of the extension by file name,
e.g. `my-icon.png`. Alternatively, you can reference an absolute HTTPS URL that points to an image or use an emoji.
You can also specify different remote or local assets for light and dark theme.

#### Example

```typescript
import { Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="URL" icon={{ source: "https://raycast.com/uploads/avatar.png" }} />
      <List.Item title="Asset" icon={{ source: "avatar.png" }} />
      <List.Item title="Icon" icon={{ source: Icon.Circle }} />
      <List.Item
        title="Theme"
        icon={{
          source: {
            light: "https://raycast.com/uploads/avatar.png",
            dark: "https://raycast.com/uploads/avatar.png",
          },
        }}
      />
    </List>
  );
}
```

### Image.Fallback

```typescript
Image.Fallback: Asset | Icon | { light: Asset; dark: Asset }
```

A fallback Image, a single emoji, or a theme-aware asset. Any specified `mask` or `tintColor` will also apply to the fallback image.

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="URL Source With Asset Fallback"
        icon={{
          source: "https://raycast.com/uploads/avatar.png",
          fallback: "default-avatar.png",
        }}
      />
    </List>
  );
}
```

### Image.URL

Image is a string representing a URL.

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="URL" icon={{ source: "https://raycast.com/uploads/avatar.png" }} />
    </List>
  );
}
```

### Image.Asset

Image is a string representing an asset from the `assets/` folder

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Asset" icon={{ source: "avatar.png" }} />
    </List>
  );
}
```


---
description: >-
  The de-facto user interface in Raycast. Ideal to present similar data such as
  to-dos or files.
---

# List

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 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 `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.

```typescript
import { useEffect, useState } from "react";
import { Action, ActionPanel, List } from "@raycast/api";

const items = ["Augustiner Helles", "Camden Hells", "Leffe Blonde", "Sierra Nevada IPA"];

export default function Command() {
  const [searchText, setSearchText] = useState("");
  const [filteredList, filterList] = useState(items);

  useEffect(() => {
    filterList(items.filter((item) => item.includes(searchText)));
  }, [searchText]);

  return (
    <List
      filtering={false}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite beer"
    >
      {filteredList.map((item) => (
        <List.Item
          key={item}
          title={item}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => console.log(`${item} selected`)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}
```

### Programmatically updating the search bar

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.

```typescript
import { useEffect, useState } from "react";
import { Action, ActionPanel, List } from "@raycast/api";

const items = ["Augustiner Helles", "Camden Hells", "Leffe Blonde", "Sierra Nevada IPA"];

export default function Command() {
  const [searchText, setSearchText] = useState("");

  return (
    <List
      searchText={searchText}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite beer"
    >
      {items.map((item) => (
        <List.Item
          key={item}
          title={item}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => setSearchText(item)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}
```

### Dropdown

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 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

{% hint style="info" %}
Pagination requires version 1.69.0 or higher of the `@raycast/api` package.
{% endhint %}

`List`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 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, and one "from scratch".

{% tabs %}

{% tab title="ListWithUsePromisePagination.tsx" %}

```typescript
import { setTimeout } from "node:timers/promises";
import { useState } from "react";
import { List } from "@raycast/api";
import { usePromise } from "@raycast/utils";

export default function Command() {
  const [searchText, setSearchText] = useState("");

  const { isLoading, data, pagination } = usePromise(
    (searchText: string) => async (options: { page: number }) => {
      await setTimeout(200);
      const newData = Array.from({ length: 25 }, (_v, index) => ({
        index,
        page: options.page,
        text: searchText,
      }));
      return { data: newData, hasMore: options.page < 10 };
    },
    [searchText]
  );

  return (
    <List isLoading={isLoading} onSearchTextChange={setSearchText} pagination={pagination}>
      {data?.map((item) => (
        <List.Item
          key={`${item.page} ${item.index} ${item.text}`}
          title={`Page ${item.page} Item ${item.index}`}
          subtitle={item.text}
        />
      ))}
    </List>
  );
}
```

{% endtab %}
{% tab title="ListWithPagination.tsx" %}

```typescript
import { setTimeout } from "node:timers/promises";
import { useCallback, useEffect, useRef, useState } from "react";
import { List } from "@raycast/api";

type State = {
  searchText: string;
  isLoading: boolean;
  hasMore: boolean;
  data: {
    index: number;
    page: number;
    text: string;
  }[];
  nextPage: number;
};
const pageSize = 20;
export default function Command() {
  const [state, setState] = useState<State>({ searchText: "", isLoading: true, hasMore: true, data: [], nextPage: 0 });
  const cancelRef = useRef<AbortController | null>(null);

  const loadNextPage = useCallback(async (searchText: string, nextPage: number, signal?: AbortSignal) => {
    setState((previous) => ({ ...previous, isLoading: true }));
    await setTimeout(500);
    const newData = Array.from({ length: pageSize }, (_v, index) => ({
      index,
      page: nextPage,
      text: searchText,
    }));
    if (signal?.aborted) {
      return;
    }
    setState((previous) => ({
      ...previous,
      data: [...previous.data, ...newData],
      isLoading: false,
      hasMore: nextPage < 10,
    }));
  }, []);

  const onLoadMore = useCallback(() => {
    setState((previous) => ({ ...previous, nextPage: previous.nextPage + 1 }));
  }, []);

  const onSearchTextChange = useCallback(
    (searchText: string) => {
      if (searchText === state.searchText) return;
      setState((previous) => ({
        ...previous,
        data: [],
        nextPage: 0,
        searchText,
      }));
    },
    [state.searchText]
  );

  useEffect(() => {
    cancelRef.current?.abort();
    cancelRef.current = new AbortController();
    loadNextPage(state.searchText, state.nextPage, cancelRef.current?.signal);
    return () => {
      cancelRef.current?.abort();
    };
  }, [loadNextPage, state.searchText, state.nextPage]);

  return (
    <List
      isLoading={state.isLoading}
      onSearchTextChange={onSearchTextChange}
      pagination={{ onLoadMore, hasMore: state.hasMore, pageSize }}
    >
      {state.data.map((item) => (
        <List.Item
          key={`${item.page} ${item.index} ${item.text}`}
          title={`Page ${item.page} Item ${item.index}`}
          subtitle={item.text}
        />
      ))}
    </List>
  );
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}

## Examples

{% tabs %}
{% tab title="List.tsx" %}

```jsx
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Item 1" />
      <List.Item title="Item 2" subtitle="Optional subtitle" />
    </List>
  );
}
```

{% endtab %}

{% tab title="ListWithSections.tsx" %}

```jsx
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Section title="Section 1">
        <List.Item title="Item 1" />
      </List.Section>
      <List.Section title="Section 2" subtitle="Optional subtitle">
        <List.Item title="Item 1" />
      </List.Section>
    </List>
  );
}
```

{% endtab %}

{% tab title="ListWithActions.tsx" %}

```jsx
import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Item 1"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard content="👋" />
          </ActionPanel>
        }
      />
    </List>
  );
}
```

{% endtab %}

{% tab title="ListWithDetail.tsx" %}

```jsx
import { useState } from "react";
import { Action, ActionPanel, List } from "@raycast/api";
import { useCachedPromise } from "@raycast/utils";

interface Pokemon {
  name: string;
  height: number;
  weight: number;
  id: string;
  types: string[];
  abilities: Array<{ name: string; isMainSeries: boolean }>;
}

const pokemons: Pokemon[] = [
  {
    name: "bulbasaur",
    height: 7,
    weight: 69,
    id: "001",
    types: ["Grass", "Poison"],
    abilities: [
      { name: "Chlorophyll", isMainSeries: true },
      { name: "Overgrow", isMainSeries: true },
    ],
  },
  {
    name: "ivysaur",
    height: 10,
    weight: 130,
    id: "002",
    types: ["Grass", "Poison"],
    abilities: [
      { name: "Chlorophyll", isMainSeries: true },
      { name: "Overgrow", isMainSeries: true },
    ],
  },
];

export default function Command() {
  const [showingDetail, setShowingDetail] = useState(true);
  const { data, isLoading } = useCachedPromise(() => new Promise<Pokemon[]>((resolve) => resolve(pokemons)));

  return (
    <List isLoading={isLoading} isShowingDetail={showingDetail}>
      {data &&
        data.map((pokemon) => {
          const props: Partial<List.Item.Props> = showingDetail
            ? {
                detail: (
                  <List.Item.Detail
                    markdown={`![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/${
                      pokemon.id
                    }.png)\n\n${pokemon.types.join(" ")}`}
                  />
                ),
              }
            : { accessories: [{ text: pokemon.types.join(" ") }] };
          return (
            <List.Item
              key={pokemon.id}
              title={pokemon.name}
              subtitle={`#${pokemon.id}`}
              {...props}
              actions={
                <ActionPanel>
                  <Action.OpenInBrowser url={`https://www.pokemon.com/us/pokedex/${pokemon.name}`} />
                  <Action title="Toggle Detail" onAction={() => setShowingDetail(!showingDetail)} />
                </ActionPanel>
              }
            />
          );
        })}
    </List>
  );
}

```

{% endtab %}

{% tab title="ListWithEmptyView.tsx" %}

```typescript
import { useEffect, useState } from "react";
import { List } from "@raycast/api";

export default function CommandWithCustomEmptyView() {
  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.Item key={item} title={item} />)
      )}
    </List>
  );
}
```

{% endtab %}

{% endtabs %}

## API Reference

### List

Displays List.Section.

The list uses built-in filtering by indexing the title of list items and additionally keywords.

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List navigationTitle="Search Beers" searchBarPlaceholder="Search your favorite beer">
      <List.Item title="Augustiner Helles" />
      <List.Item title="Camden Hells" />
      <List.Item title="Leffe Blonde" />
      <List.Item title="Sierra Nevada IPA" />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| actions | A reference to an ActionPanel. It will only be shown when there aren't any children. | <code>React.ReactNode</code> | - |
| children | List sections or items. If List.Item elements are specified, a default section is automatically created. | <code>React.ReactNode</code> | - |
| 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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| isLoading | Indicates whether a loading bar should be shown or hidden below the search bar | <code>boolean</code> | `false` |
| isShowingDetail | Whether the List should have an area on the right side of the items to show additional details about the selected item. | <code>boolean</code> | - |
| navigationTitle | The main title for that view displayed in Raycast | <code>string</code> | Command title |
| pagination | Configuration for pagination | <code>{ hasMore: boolean; pageSize: number; onLoadMore: () => void }</code> | - |
| searchBarAccessory | List.Dropdown, string></code> | - |
| searchBarPlaceholder | Placeholder text that will be shown in the search bar. | <code>string</code> | `"Search…"` |
| searchText | The text that will be displayed in the search bar. | <code>string</code> | - |
| selectedItemId | Selects the item with the specified id. | <code>string</code> | - |
| 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). | <code>boolean</code> | `false` |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |
| onSelectionChange | Callback triggered when the item selection in the list changes. | <code>(id: string) => void</code> | - |

### List.Dropdown

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

#### Example

```typescript
import { List } from "@raycast/api";

type DrinkType = { id: string; name: string };

function DrinkDropdown(props: { drinkTypes: DrinkType[]; onDrinkTypeChange: (newValue: string) => void }) {
  const { drinkTypes, onDrinkTypeChange } = props;
  return (
    <List.Dropdown
      tooltip="Select Drink Type"
      storeValue={true}
      onChange={(newValue) => {
        onDrinkTypeChange(newValue);
      }}
    >
      <List.Dropdown.Section title="Alcoholic Beverages">
        {drinkTypes.map((drinkType) => (
          <List.Dropdown.Item key={drinkType.id} title={drinkType.name} value={drinkType.id} />
        ))}
      </List.Dropdown.Section>
    </List.Dropdown>
  );
}

export default function Command() {
  const drinkTypes: DrinkType[] = [
    { id: "1", name: "Beer" },
    { id: "2", name: "Wine" },
  ];
  const onDrinkTypeChange = (newValue: string) => {
    console.log(newValue);
  };
  return (
    <List
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite drink"
      searchBarAccessory={<DrinkDropdown drinkTypes={drinkTypes} onDrinkTypeChange={onDrinkTypeChange} />}
    >
      <List.Item title="Augustiner Helles" />
      <List.Item title="Camden Hells" />
      <List.Item title="Leffe Blonde" />
      <List.Item title="Sierra Nevada IPA" />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| tooltip<mark style="color:red;">*</mark> | Tooltip displayed when hovering the dropdown. | <code>string</code> | - |
| children | Dropdown sections or items. If Dropdown.Item elements are specified, a default section is automatically created. | <code>React.ReactNode</code> | - |
| 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. | <code>string</code> | - |
| 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. | <code>boolean</code> or <code>{ keepSectionOrder: boolean }</code> | `false` when `onSearchTextChange` is specified, `true` otherwise. |
| id | ID of the dropdown. | <code>string</code> | - |
| isLoading | Indicates whether a loading indicator should be shown or hidden next to the search bar | <code>boolean</code> | `false` |
| placeholder | Placeholder text that will be shown in the dropdown search field. | <code>string</code> | `"Search…"` |
| storeValue | Indicates whether the value of the dropdown should be persisted after selection, and restored next time the dropdown is rendered. | <code>boolean</code> | - |
| 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). | <code>boolean</code> | `false` |
| value | The currently value of the dropdown. | <code>string</code> | - |
| onChange | Callback triggered when the dropdown selection changes. | <code>(newValue: string) => void</code> | - |
| onSearchTextChange | Callback triggered when the search bar text changes. | <code>(text: string) => void</code> | - |

### List.Dropdown.Item

A dropdown item in a List.Dropdown

#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List
      searchBarAccessory={
        <List.Dropdown tooltip="Dropdown With Items">
          <List.Dropdown.Item title="One" value="one" />
          <List.Dropdown.Item title="Two" value="two" />
          <List.Dropdown.Item title="Three" value="three" />
        </List.Dropdown>
      }
    >
      <List.Item title="Item in the Main List" />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title displayed for the item. | <code>string</code> | - |
| value<mark style="color:red;">*</mark> | Value of the dropdown item. Make sure to assign each unique value for each item. | <code>string</code> | - |
| icon | An optional icon displayed for the item. | <code>Image.ImageLike</code> | - |
| 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. | <code>string[]</code> | 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

```typescript
import { List } from "@raycast/api";

export default function Command() {
  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. | <code>React.ReactNode</code> | - |
| title | Title displayed above the section | <code>string</code> | - |

### 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.Item`s.

Note that the `EmptyView` is _never_ displayed if the `List`'s `isLoading` property is true and the search bar is empty.



#### Example

```typescript
import { useEffect, useState } from "react";
import { List } from "@raycast/api";

export default function CommandWithCustomEmptyView() {
  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.Item key={item} title={item} />)
      )}
    </List>
  );
}
```

#### Props

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

### 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

```typescript
import { Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" accessories={[{ text: "Germany" }]} />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The main title displayed for that item, optionally with a tooltip. | <code>string</code> or <code>{ tooltip?: string; value: string }</code> | - |
| accessories | An optional array of List.Item.Accessory[]</code> | - |
| actions | An ActionPanel that will be updated for the selected list item. | <code>React.ReactNode</code> | - |
| 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. | <code>React.ReactNode</code> | - |
| icon | An optional icon displayed for the list item. | <code>Image.ImageLike }</code> | - |
| 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. | <code>string</code> | - |
| 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. | <code>string[]</code> | - |
| quickLook | Optional information to preview files with Quick Look. Toggle the preview with Action.ToggleQuickLook. | <code>{ name?: string; path: string }</code> | - |
| subtitle | An optional subtitle displayed next to the main title, optionally with a tooltip. | <code>string</code> or <code>{ tooltip?: string; value?: string }</code> | - |

### 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.



#### Example

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Pikachu"
        subtitle="Electric"
        detail={
          <List.Item.Detail markdown="![Illustration](https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png)" />
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| isLoading | Indicates whether a loading bar should be shown or hidden above the detail | <code>boolean</code> | `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. | <code>string</code> | - |
| metadata | The `List.Item.Detail.Metadata` to be rendered in the bottom side of the `List.Item.Detail` | <code>React.ReactNode</code> | - |

### 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

{% tabs %}

{% tab title="Metadata + Markdown" %}



```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  const markdown = `
![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/001.png)
There is a plant seed on its back right from the day this Pokémon is born. The seed slowly grows larger.
`;
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            markdown={markdown}
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Types" />
                <List.Item.Detail.Metadata.Label title="Grass" icon="pokemon_types/grass.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Poison" icon="pokemon_types/poison.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Chracteristics" />
                <List.Item.Detail.Metadata.Label title="Height" text="70cm" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Abilities" />
                <List.Item.Detail.Metadata.Label title="Chlorophyll" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Overgrow" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

{% endtab %}

{% tab title="Metadata Standalone" %}



```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Types" />
                <List.Item.Detail.Metadata.Label title="Grass" icon="pokemon_types/grass.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Poison" icon="pokemon_types/poison.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Chracteristics" />
                <List.Item.Detail.Metadata.Label title="Height" text="70cm" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Abilities" />
                <List.Item.Detail.Metadata.Label title="Chlorophyll" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Overgrow" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

{% endtab %}

{% endtabs %}

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children<mark style="color:red;">*</mark> | The elements of the Metadata view. | <code>React.ReactNode</code> | - |

### List.Item.Detail.Metadata.Label

A title with, optionally, an icon and/or text to its right.



#### Example

```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass" />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| title<mark style="color:red;">*</mark> | The title of the item. | <code>string</code> | - |
| icon | An icon to illustrate the value of the item. | <code>Image.ImageLike</code> | - |
| text | The text value of the item. Specifying `color` will display the text in the provided color. Defaults to Color.SecondaryText; value: string }</code> | - |

### List.Item.Detail.Metadata.Link

An item to display a link.



#### Example

```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Link
                  title="Evolution"
                  target="https://www.pokemon.com/us/pokedex/pikachu"
                  text="Raichu"
                />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The target of the link. | <code>string</code> | - |
| text<mark style="color:red;">*</mark> | The text value of the item. | <code>string</code> | - |
| title<mark style="color:red;">*</mark> | The title shown above the item. | <code>string</code> | - |

### List.Item.Detail.Metadata.TagList

A list of `Tags` displayed in a row.



#### Example

```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.TagList title="Type">
                  <List.Item.Detail.Metadata.TagList.Item text="Electric" color={"#eed535"} />
                </List.Item.Detail.Metadata.TagList>
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| children<mark style="color:red;">*</mark> | The tags contained in the TagList. | <code>React.ReactNode</code> | - |
| title<mark style="color:red;">*</mark> | The title shown above the item. | <code>string</code> | - |

### List.Item.Detail.Metadata.TagList.Item

A Tag in a `List.Item.Detail.Metadata.TagList`.

#### Props

| Prop | Description | Type | Default |
| :--- | :--- | :--- | :--- |
| color | Changes the text color to the provided color and sets a transparent background with the same color. | <code>Color.ColorLike</code> | - |
| icon | The optional icon tag icon. Required if the tag has no text. | <code>Image.ImageLike</code> | - |
| text | The optional tag text. Required if the tag has no icon. | <code>string</code> | - |
| onAction | Callback that is triggered when the item is clicked. | <code>() => void</code> | - |

### List.Item.Detail.Metadata.Separator

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



#### Example

```typescript
import { List } from "@raycast/api";

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/poison.svg" text="Poison" />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}
```

### 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

```typescript
import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Section title="Lager">
        <List.Item title="Camden Hells" />
      </List.Section>
      <List.Section title="IPA">
        <List.Item title="Sierra Nevada IPA" />
      </List.Section>
    </List>
  );
}
```

#### Props

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

## Types

### List.Item.Accessory

An interface describing an accessory view in a `List.Item`.



#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| tag<mark style="color:red;">*</mark> | A string or Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.). Color changes the text color to the provided color and sets a transparent background with the same color. Defaults to Color.SecondaryText; value: string</code> or <code>Date</code> or <code>undefined</code> or <code>null }</code> |
| text | An optional text that will be used as the label, optionally colored. Color changes the text color to the provided color. Defaults to Color.SecondaryText; value: string</code> or <code>undefined</code> or <code>null }</code> |
| date | An optional Date that will be used as the label, optionally colored. The date is formatted relatively to the current time (for example `new Date()` will be displayed as `"now"`, yesterday's Date will be displayed as "1d", etc.). Color changes the text color to the provided color. Defaults to Color.SecondaryText; value: Date</code> or <code>undefined</code> or <code>null }</code> |
| icon | An optional Image.ImageLike</code> or <code>null</code> |
| tooltip | An optional tooltip shown when the accessory is hovered. | <code>string</code> or <code>null</code> |

#### Example

```typescript
import { Color, Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="An Item with Accessories"
        accessories={[
          { text: `An Accessory Text`, icon: Icon.Hammer },
          { text: { value: `A Colored Accessory Text`, color: Color.Orange }, icon: Icon.Hammer },
          { icon: Icon.Person, tooltip: "A person" },
          { text: "Just Do It!" },
          { date: new Date() },
          { tag: new Date() },
          { tag: { value: new Date(), color: Color.Magenta } },
          { tag: { value: "User", color: Color.Magenta }, tooltip: "Tag with tooltip" },
        ]}
      />
    </List>
  );
}
```


# Navigation

## API Reference

### useNavigation

A hook that lets you push and pop view components in the navigation stack.

You most likely won't use this hook too often. To push a new component, use the Push Action.
When a user presses `ESC`, we automatically pop to the previous component.

#### Signature

```typescript
function useNavigation(): Navigation;
```

#### Example

```typescript
import { Action, ActionPanel, Detail, useNavigation } from "@raycast/api";

function Ping() {
  const { push } = useNavigation();

  return (
    <Detail
      markdown="Ping"
      actions={
        <ActionPanel>
          <Action title="Push" onAction={() => push(<Pong />)} />
        </ActionPanel>
      }
    />
  );
}

function Pong() {
  const { pop } = useNavigation();

  return (
    <Detail
      markdown="Pong"
      actions={
        <ActionPanel>
          <Action title="Pop" onAction={pop} />
        </ActionPanel>
      }
    />
  );
}

export default function Command() {
  return <Ping />;
}
```

#### Return

A Navigation functions.
Use the functions to alter the navigation stack.

## Types

### Navigation

Return type of the useNavigation hook to perform push and pop actions.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| pop<mark style="color:red;">*</mark> | Pop current view component from the navigation stack. | <code>() => void</code> |
| push<mark style="color:red;">*</mark> | Push a new view component to the navigation stack. | <code>(component: React.ReactNode, onPop: () => void) => void</code> |


# System Utilities

This set of utilities exposes some of Raycast's native functionality to allow deep integration into the user's setup. For example, you can use the Application APIs to check if a desktop application is installed and then provide an action to deep-link into it.

## API Reference

### getApplications

Returns all applications that can open the file or URL.

#### Signature

```typescript
async function getApplications(path?: PathLike): Promise<Application[]>;
```

#### Example

{% tabs %}
{% tab title="Find Application" %}

```typescript
import { getApplications, Application } from "@raycast/api";

// it is a lot more reliable to get an app by its bundle ID than its path
async function findApplication(bundleId: string): Application | undefined {
  const installedApplications = await getApplications();
  return installedApplications.filter((application) => application.bundleId == bundleId);
}
```

{% endtab %}

{% tab title="List Installed Applications" %}

```typescript
import { getApplications } from "@raycast/api";

export default async function Command() {
  const installedApplications = await getApplications();
  console.log("The following applications are installed on your Mac:");
  console.log(installedApplications.map((a) => a.name).join(", "));
}
```

{% endtab %}
{% endtabs %}

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| path | The path of the file or folder to get the applications for. If no path is specified, all installed applications are returned. | <code>PathLike</code> |

#### Return

An array of Application.

### getDefaultApplication

Returns the default application that the file or URL would be opened with.

#### Signature

```typescript
async function getDefaultApplication(path: PathLike): Promise<Application>;
```

#### Example

```typescript
import { getDefaultApplication } from "@raycast/api";

export default async function Command() {
  const defaultApplication = await getDefaultApplication(__filename);
  console.log(`Default application for JavaScript is: ${defaultApplication.name}`);
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> | The path of the file or folder to get the default application for. | <code>PathLike</code> |

#### Return

A Promise that resolves with the default Application that would open the file or URL. If no application was found, the promise will be rejected.

### getFrontmostApplication

Returns the frontmost application.

#### Signature

```typescript
async function getFrontmostApplication(): Promise<Application>;
```

#### Example

```typescript
import { getFrontmostApplication } from "@raycast/api";

export default async function Command() => {
  const frontmostApplication = await getFrontmostApplication();
  console.log(`The frontmost application is: ${frontmostApplication.name}`);
};
```

#### Return

A Promise that resolves with the frontmost Application. If no application was found, the promise will be rejected.

### showInFinder

Shows a file or directory in the Finder.

#### Signature

```typescript
async function showInFinder(path: PathLike): Promise<void>;
```

#### Example

```typescript
import { showInFinder } from "@raycast/api";
import { homedir } from "os";
import { join } from "path";

export default async function Command() {
  await showInFinder(join(homedir(), "Downloads"));
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> | The path to show in the Finder. | <code>PathLike</code> |

#### Return

A Promise that resolves when the item is revealed in the Finder.

### trash

Moves a file or directory to the Trash.

#### Signature

```typescript
async function trash(path: PathLike | PathLike[]): Promise<void>;
```

#### Example

```typescript
import { trash } from "@raycast/api";
import { writeFile } from "fs/promises";
import { homedir } from "os";
import { join } from "path";

export default async function Command() {
  const file = join(homedir(), "Desktop", "yolo.txt");
  await writeFile(file, "I will be deleted soon!");
  await trash(file);
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| path<mark style="color:red;">*</mark> |  | <code>PathLike[]</code> |

#### Return

A Promise that resolves when all files are moved to the trash.

### open

Opens a target with the default application or specified application.

#### Signature

```typescript
async function open(target: string, application?: Application | string): Promise<void>;
```

#### Example

```typescript
import { open } from "@raycast/api";

export default async function Command() {
  await open("https://www.raycast.com", "com.google.Chrome");
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The file, folder or URL to open. | <code>string</code> |
| application | The application name to use for opening the file. If no application is specified, the default application as determined by the system is used to open the specified file. Note that you can use the application name, app identifier, or absolute path to the app. | <code>string</code> or <code>Application</code> |

#### Return

A Promise that resolves when the target has been opened.

### captureException

Report the provided exception to the Developer Hub.
This helps in handling failures gracefully while staying informed about the occurrence of the failure.

#### Signature

```typescript
function captureException(exception: unknown): void;
```

#### Example

```typescript
import { open, captureException, showToast, Toast } from "@raycast/api";

export default async function Command() {
  const url = "https://www.raycast.com";
  const app = "Google Chrome";
  try {
    await open(url, app);
  } catch (e: unknown) {
    captureException(e);
    await showToast({
      style: Toast.Style.Failure,
      title: `Could not open ${url} in ${app}.`,
    });
  }
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| target<mark style="color:red;">*</mark> | The file, folder or URL to open. | <code>string</code> |
| application | The application name to use for opening the file. If no application is specified, the default application as determined by the system is used to open the specified file. Note that you can use the application name, app identifier, or absolute path to the app. | <code>string</code> or <code>Application</code> |

## Types

### Application

An object that represents a locally installed application on the system.

It can be used to open files or folders in a specific application. Use getApplications or
getDefaultApplication to get applications that can open a specific file or folder.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| name<mark style="color:red;">*</mark> | The display name of the application. | <code>string</code> |
| path<mark style="color:red;">*</mark> | The absolute path to the application bundle, e.g. `/Applications/Raycast.app`, | <code>string</code> |
| bundleId | The bundle identifier of the application, e.g. `com.raycast.macos`. | <code>string</code> |
| localizedName | The localized name of the application. | <code>string</code> |

### PathLike

```typescript
PathLike: string | Buffer | URL;
```

Supported path types.


# Raycast Window & Search Bar

## API Reference

### clearSearchBar

Clear the text in the search bar.

#### Signature

```typescript
async function clearSearchBar(options?: { forceScrollToTop?: boolean }): Promise<void>;
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Can be used to control the behaviour after the search bar is cleared. | <code>Object</code> |
| options.forceScrollToTop | Can be used to force scrolling to the top. Defaults to scrolling to the top after the the search bar was cleared. | <code>boolean</code> |

#### Return

A Promise that resolves when the search bar is cleared.

### closeMainWindow

Closes the main Raycast window.

#### Signature

```typescript
async function closeMainWindow(options?: { clearRootSearch?: boolean; popToRootType?: PopToRootType }): Promise<void>;
```

#### Example

```typescript
import { closeMainWindow } from "@raycast/api";
import { setTimeout } from "timers/promises";

export default async function Command() {
  await setTimeout(1000);
  await closeMainWindow({ clearRootSearch: true });
}
```

You can use the `popToRootType` parameter to temporarily prevent Raycast from applying the user's "Pop to Root Search" preference in Raycast; for example, when you need to interact with an external system utility and then allow the user to return back to the view command:

```typescript
import { closeMainWindow, PopToRootType } from "@raycast/api";

export default async () => {
  await closeMainWindow({ popToRootType: PopToRootType.Suspended });
};
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Can be used to control the behaviour after closing the main window. | <code>Object</code> |
| options.clearRootSearch | Clears the text in the root search bar and scrolls to the top | <code>boolean</code> |
| options.popToRootType | Defines the pop to root behavior (PopToRootType</code> |

#### Return

A Promise that resolves when the main window is closed.

### popToRoot

Pops the navigation stack back to root search.

#### Signature

```typescript
async function popToRoot(options?: { clearSearchBar?: boolean }): Promise<void>;
```

#### Example

```typescript
import { Detail, popToRoot } from "@raycast/api";
import { useEffect } from "react";
import { setTimeout } from "timers";

export default function Command() {
  useEffect(() => {
    setTimeout(() => {
      popToRoot({ clearSearchBar: true });
    }, 3000);
  }, []);

  return <Detail markdown="See you soon 👋" />;
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options | Can be used to control the behaviour after going back to the root search. | <code>Object</code> |
| options.clearSearchBar |  | <code>boolean</code> |

#### Return

A Promise that resolves when Raycast popped to root.

## Types

### PopToRootType

Defines the pop to root behavior when the main window is closed.

#### Enumeration members

| Name      | Description                                                    |
| :-------- | :------------------------------------------------------------- |
| Default   | Respects the user's "Pop to Root Search" preference in Raycast |
| Immediate | Immediately pops back to root                                  |
| Suspended | Prevents Raycast from popping back to root                     |


# Window Management

The Window Management API provides developers with some functions to create commands with some advanced logic to move Windows around.

{% hint style="info" %}

Some users might not have access to this API. If a user doesn't have access to Raycast Pro, they will be asked if they want to get access when your extension calls the Window Management API. If the user doesn't wish to get access, the API call will throw an error.

You can check if a user has access to the API using `environment.canAccess(WindowManagement)`.

{% endhint %}

## API Reference

### WindowManagement.getActiveWindow

Gets the active Window.

#### Signature

```typescript
async function getActiveWindow(): Promise<Window>;
```

#### Example

```typescript
import { WindowManagement, showToast } from "@raycast/api";

export default async function Command() {
  try {
    const window = await WindowManagement.getActiveWindow();
    if (window.positionable) {
      WindowManagement.setWindowBounds({ id: window.id, bounds: { position: { x: 100 } } });
    }
  } catch (error) {
    showToast({ title: "Could not move window", message: error.message, style: Toast.Style.Failure });
  }
}
```

#### Return

A Promise that resolves with the active Window. If no window is active, the promise will be rejected.

### WindowManagement.getWindowsOnActiveDesktop

Gets the list of Window.

#### Signature

```typescript
async function getWindowsOnActiveDesktop(): Promise<Window[]>;
```

#### Example

```typescript
import { WindowManagement, showToast } from "@raycast/api";

export default async function Command() {
  const windows = await WindowManagement.getWindowsOnActiveDesktop();
  const chrome = windows.find((x) => x.application?.bundleId === "com.google.Chrome");
  if (!chrome) {
    showToast({ title: "Couldn't find chrome", style: Toast.Style.Failure });
    return;
  }
  WindowManagement.setWindowBounds({ id: chrome.id, bounds: { position: { x: 100 } } });
}
```

#### Return

A Promise that resolves with an array of Windows.

### WindowManagement.getDesktops

Gets the list of Desktops available across all screens.

#### Signature

```typescript
async function getDesktops(): Promise<Desktop[]>;
```

#### Example

```typescript
import { WindowManagement, showToast } from "@raycast/api";

export default function Command() {
  const desktops = await WindowManagement.getDesktops();
  const screens = Set(desktops.map((desktop) => desktop.screenId));
  showToast({ title: `Found ${desktops.length} desktops on ${screens.size} screens.` });
}
```

#### Return

A Promise that resolves with the desktops.

### WindowManagement.setWindowBounds

Move a Window or make it fullscreen.

#### Signature

```typescript
async function setWindowBounds(
  options: { id: string } & (
    | {
        bounds: {
          position?: { x?: number; y?: number };
          size?: { width?: number; height?: number };
        };
        desktopId?: string;
      }
    | {
        bounds: "fullscreen";
      }
  )
): Promise<void>;
```

#### Example

```typescript
import { WindowManagement, showToast } from "@raycast/api";

export default async function Command() {
  try {
    const window = await WindowManagement.getActiveWindow();
    if (window.positionable) {
      WindowManagement.setWindowBounds({ id: window.id, bounds: { position: { x: 100 } } });
    }
  } catch (error) {
    showToast({ title: "Could not move window", message: error.message, style: Toast.Style.Failure });
  }
}
```

#### Parameters

| Name | Description | Type |
| :--- | :--- | :--- |
| options<mark style="color:red;">*</mark> |  | <code>{ id: string }</code> or <code>{ bounds: { position?: { x?: number; y?: number }; size?: { height?: number; width?: number } }; desktopId?: string }</code> or <code>{ id: string }</code> or <code>{ bounds: "fullscreen" }</code> |

#### Return

A Promise that resolves with the window was moved. If the move isn't possible (for example trying to make a window fullscreen that doesn't support it), the promise will be rejected.

## Types

### WindowManagement.Window

A Window from an Application.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| active<mark style="color:red;">*</mark> |  | <code>boolean</code> |
| bounds<mark style="color:red;">*</mark> |  | <code>{ position: { x: number; y: number }; size: { height: number; width: number } }</code> or <code>"fullscreen"</code> |
| desktopId<mark style="color:red;">*</mark> |  | <code>string</code> |
| fullScreenSettable<mark style="color:red;">*</mark> |  | <code>boolean</code> |
| id<mark style="color:red;">*</mark> |  | <code>string</code> |
| positionable<mark style="color:red;">*</mark> |  | <code>boolean</code> |
| resizable<mark style="color:red;">*</mark> |  | <code>boolean</code> |
| application |  | <code>Application</code> |

### WindowManagement.Desktop

A Desktop represents a virtual desktop on a Screen.

#### Properties

| Property | Description | Type |
| :--- | :--- | :--- |
| active<mark style="color:red;">*</mark> |  | <code>boolean</code> |
| id<mark style="color:red;">*</mark> |  | <code>string</code> |
| screenId<mark style="color:red;">*</mark> |  | <code>string</code> |
| size<mark style="color:red;">*</mark> |  | <code>{ height: number; width: number }</code> |
| type<mark style="color:red;">*</mark> |  | <code>WindowManagement.DesktopType</code> |

### WindowManagement.DesktopType

The type of a Desktop.

#### Enumeration members

| Name       | Description                                                                               |
| :--------- | :---------------------------------------------------------------------------------------- |
| User       | The default Desktop type. It can contain any number of Window |
| FullScreen | A Desktop made of a single fullscreen window                                              |