Vicinae

List

A searchable, scrollable list of items with optional detail panels, accessories, and filters.

List

Basic List

import { Action, ActionPanel, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard title="Copy" content="🍎" />
          </ActionPanel>
        }
      />
      <List.Item title="Banana" icon="🍌" />
      <List.Item title="Cherry" icon="🍒" />
    </List>
  );
}

Detail Panel

Set isShowingDetail to show a side panel with markdown and metadata.

import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Apple"
        icon="🍎"
        detail={
          <List.Item.Detail
            markdown="# Apple\n\nA crisp, sweet fruit."
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Color" text="Red" />
                <List.Item.Detail.Metadata.TagList title="Season">
                  <List.Item.Detail.Metadata.TagList.Item text="Autumn" color={Color.Orange} />
                </List.Item.Detail.Metadata.TagList>
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
      {/* ... */}
    </List>
  );
}

Accessories

Right-side metadata supporting text, colored tags, and icons.

import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Apple"
        icon="🍎"
        accessories={[
          { text: "95 kcal" },
          { tag: { value: "fruit", color: Color.Red } },
        ]}
      />
      {/* ... */}
    </List>
  );
}

Empty View

Placeholder when the list has no items.

import { Color, List } from "@vicinae/api";

export default function Command() {
  return (
    <List>
      <List.EmptyView
        title="No Fruits Found"
        description="Try a different search."
        icon={{ source: "🍎", tintColor: Color.SecondaryText }}
      />
    </List>
  );
}

Filter items via a dropdown in the search bar.

import { useState } from "react";
import { List } from "@vicinae/api";

export default function Command() {
  const [type, setType] = useState("all");

  return (
    <List
      searchBarAccessory={
        <List.Dropdown tooltip="Type" value={type} onChange={setType}>
          <List.Dropdown.Item title="All" value="all" />
          <List.Dropdown.Item title="Berries" value="berry" />
          <List.Dropdown.Item title="Citrus" value="citrus" />
        </List.Dropdown>
      }
    >
      {/* filtered items */}
    </List>
  );
}

Handle search yourself by controlling searchText. This automatically disables built-in filtering.

import { useState } from "react";
import { List } from "@vicinae/api";

export default function Command() {
  const [query, setQuery] = useState("");

  return (
    <List searchText={query} onSearchTextChange={setQuery}>
      {/* manually filtered items */}
    </List>
  );
}