Hooks

React hooks for state management and async operations

SuperCmd implements all Raycast hooks from both @raycast/api and @raycast/utils. All hooks are fully compatible with the Raycast API specification.

Navigation

useNavigation

useNavigation

Navigate between views in your extension

The useNavigation hook provides methods to navigate between views.

push · (component: React.ReactElement) => void

Push a new view onto the navigation stack

pop · () => void

Pop the current view from the navigation stack

import { useNavigation, Detail, List } from '@raycast/api';

function MyList() {
  const { push } = useNavigation();
  
  return (
    <List>
      <List.Item 
        title="View Details"
        actions={
          <ActionPanel>
            <Action 
              title="Open" 
              onAction={() => push(<Detail markdown="# Details" />)}
            />
          </ActionPanel>
        }
      />
    </List>
  );
}

---

Data Fetching

useFetch

useFetch

Fetch data from HTTP APIs with automatic state management

Fetch data from HTTP endpoints with built-in loading states, error handling, and pagination.

Type Signature:

function useFetch<T = any, U = undefined>(
  url: string | ((options: { page: number; cursor?: string }) => string),
  options?: {
    method?: string;
    headers?: Record<string, string>;
    body?: any;
    mapResult?: (result: any) => { data: T; hasMore?: boolean; cursor?: string } | T;
    parseResponse?: (response: Response) => Promise<any>;
    initialData?: T;
    execute?: boolean;
    keepPreviousData?: boolean;
    onData?: (data: T) => void;
    onError?: (error: Error) => void;
    onWillExecute?: () => void;
  }
): {
  data: T | undefined;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
  mutate: (asyncUpdate?: Promise<T>, options?: any) => Promise<T | undefined>;
  pagination: { page: number; hasMore: boolean; onLoadMore: () => void };
}

Example:

import { useFetch } from '@raycast/utils';
import { List } from '@raycast/api';

function MyCommand() {
  const { data, isLoading } = useFetch('https://api.example.com/items');
  
  return (
    <List isLoading={isLoading}>
      {data?.map(item => (
        <List.Item key={item.id} title={item.name} />
      ))}
    </List>
  );
}

---

usePromise

usePromise

Execute async functions with state management

Execute asynchronous functions with automatic state tracking.

Type Signature:

function usePromise<T>(
  fn: (...args: any[]) => Promise<T>,
  args?: any[],
  options?: {
    execute?: boolean;
    onData?: (data: T) => void;
    onError?: (error: Error) => void;
    onWillExecute?: () => void;
  }
): {
  data: T | undefined;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
  mutate: (asyncUpdate?: Promise<T>) => Promise<T | undefined>;
}

Example:

import { usePromise } from '@raycast/utils';

function MyCommand() {
  const { data, isLoading } = usePromise(
    async (query: string) => {
      const response = await fetch(`https://api.example.com/search?q=${query}`);
      return response.json();
    },
    ['initial query']
  );
  
  return <List isLoading={isLoading}>...</List>;
}

---

useCachedPromise

useCachedPromise

Execute async functions with caching and pagination

Like usePromise but with built-in caching and pagination support.

Type Signature:

function useCachedPromise<T>(
  fn: (...args: any[]) => Promise<T>,
  args?: any[],
  options?: {
    execute?: boolean;
    keepPreviousData?: boolean;
    initialData?: T;
    onData?: (data: T) => void;
    onError?: (error: Error) => void;
    abortable?: AbortController;
  }
): {
  data: T | undefined;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
  mutate: (data: T | Promise<T>) => Promise<T | undefined>;
}

---

useCachedState

useCachedState

Persist state to local storage automatically

State hook that persists to LocalStorage automatically.

Type Signature:

function useCachedState<T>(
  key: string,
  initialValue?: T
): [T | undefined, (value: T | undefined) => void, boolean]

Example:

import { useCachedState } from '@raycast/utils';

function MyCommand() {
  const [query, setQuery] = useCachedState<string>('search-query', '');
  
  return (
    <List 
      searchText={query}
      onSearchTextChange={setQuery}
    >
      ...
    </List>
  );
}

---

Form Management

useForm

useForm

Manage form state with validation

Manage form values, validation, and field props.

Type Signature:

function useForm<T extends Form.Values>(options?: {
  onSubmit: (values: T) => void | Promise<void>;
  initialValues?: Partial<T>;
  validation?: {
    [K in keyof T]?: (value: T[K]) => string | undefined | null;
  };
}): {
  handleSubmit: (values: T) => void;
  itemProps: <K extends keyof T>(id: K) => {
    id: string;
    value: T[K];
    error: string | undefined;
    onChange: (value: T[K]) => void;
    onBlur: () => void;
  };
  values: T;
  setValues: (values: Partial<T>) => void;
  reset: () => void;
}

Example:

import { useForm } from '@raycast/utils';
import { Form, Action, ActionPanel } from '@raycast/api';

interface FormValues {
  name: string;
  email: string;
}

function MyCommand() {
  const { handleSubmit, itemProps } = useForm<FormValues>({
    onSubmit: (values) => console.log(values),
    validation: {
      email: (value) => {
        if (!value?.includes('@')) return 'Invalid email';
      },
    },
  });
  
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextField title="Name" {...itemProps('name')} />
      <Form.TextField title="Email" {...itemProps('email')} />
    </Form>
  );
}

---

Shell & SQL

useExec

useExec

Execute shell commands with state tracking

Execute shell commands and track their output and state.

Type Signature:

function useExec(
  command: string,
  args: string[],
  options?: {
    execute?: boolean;
    cwd?: string;
    shell?: boolean;
    env?: Record<string, string>;
    timeout?: number;
    stripFinalNewline?: boolean;
    onData?: (data: string) => void;
    onError?: (error: Error) => void;
  }
): {
  data: string | undefined;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
}

Example:

import { useExec } from '@raycast/utils';

function MyCommand() {
  const { data, isLoading } = useExec('git', ['status']);
  
  return <Detail markdown={data || 'Loading...'} isLoading={isLoading} />;
}

---

useSQL

useSQL

Query SQLite databases with state tracking

Query SQLite databases with automatic state management.

Type Signature:

function useSQL<T = any>(
  databasePath: string,
  query: string,
  options?: {
    execute?: boolean;
    permissionView?: React.ReactNode;
    onData?: (data: T[]) => void;
    onError?: (error: Error) => void;
  }
): {
  data: T[] | undefined;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
  permissionView: React.ReactNode;
}

---

AI & Streaming

useAI

useAI

Execute AI prompts with streaming support

Execute AI prompts with automatic state tracking and streaming.

Type Signature:

function useAI(
  prompt: string,
  options?: {
    model?: string;
    creativity?: 'none' | 'low' | 'medium' | 'high' | 'maximum' | number;
    execute?: boolean;
    stream?: boolean;
    onData?: (data: string) => void;
    onError?: (error: Error) => void;
    onWillExecute?: (args: [string]) => void;
  }
): {
  data: string;
  isLoading: boolean;
  error: Error | undefined;
  revalidate: () => void;
}

Example:

import { useAI } from '@raycast/utils';
import { Detail } from '@raycast/api';

function MyCommand() {
  const { data, isLoading } = useAI('Explain React hooks in 3 sentences', {
    creativity: 'medium',
    stream: true,
  });
  
  return <Detail markdown={data || 'Thinking...'} isLoading={isLoading} />;
}

---

useStreamJSON

useStreamJSON

Fetch and stream JSON data with client-side pagination

Fetch JSON data with client-side filtering, transformation, and pagination.

Type Signature:

function useStreamJSON<T>(
  url: string,
  options?: {
    dataPath?: string;
    filter?: (item: T) => boolean;
    transform?: (item: any) => T;
    pageSize?: number;
    execute?: boolean;
    onData?: (items: T[]) => void;
    onError?: (error: Error) => void;
  }
): {
  data: T[] | undefined;
  isLoading: boolean;
  error: Error | undefined;
  pagination: { hasMore: boolean; onLoadMore: () => void };
}

---

Utilities

useLocalStorage

useLocalStorage

React hook for LocalStorage with change notifications

LocalStorage hook with automatic synchronization across extensions.

Type Signature:

function useLocalStorage<T extends LocalStorage.Value>(
  key: string,
  initialValue?: T
): {
  value: T | undefined;
  setValue: (value: T) => Promise<void>;
  removeValue: () => Promise<void>;
  isLoading: boolean;
}

---

useFrecencySorting

useFrecencySorting

Sort items by frequency and recency

Sort items based on frequency and recency of access.

Type Signature:

function useFrecencySorting<T>(
  items: T[],
  options: {
    key: (item: T) => string;
    namespace?: string;
  }
): {
  data: T[];
  visitItem: (item: T) => Promise<void>;
  resetRanking: (item: T) => Promise<void>;
}

Example:

import { useFrecencySorting } from '@raycast/utils';
import { List } from '@raycast/api';

function MyCommand() {
  const allItems = [{ id: '1', name: 'Item 1' }, { id: '2', name: 'Item 2' }];
  const { data, visitItem } = useFrecencySorting(allItems, {
    key: (item) => item.id,
  });
  
  return (
    <List>
      {data.map(item => (
        <List.Item 
          key={item.id} 
          title={item.name}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => visitItem(item)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}