Preferences
Use the Preferences API to make your extension configurable.
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.
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.
function getPreferenceValues(): { [preferenceName: string]: any };
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);
}
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 |
|---|---|
textfield | string |
password | string |
checkbox | boolean |
dropdown | string |
appPicker | |
file | string |
directory | string |
Opens the extension's preferences screen.
export declare function openExtensionPreferences(): Promise<void>;
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>
}
/>
);
}
A Promise that resolves when the extensions preferences screen is opened.
Opens the command's preferences screen.
export declare function openCommandPreferences(): Promise<void>;
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>
}
/>
);
}
A Promise that resolves when the command's preferences screen is opened.
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 |
|---|---|
textfield | string |
password | string |
checkbox | boolean |
dropdown | string |
appPicker | |
file | string |
directory | string |
Raycast provides a global TypeScript namespace called
Preferences which contains the types of the preferences of all the commands of the extensions.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.Last modified 4mo ago