List

Components

UiList

Display a list of items. The items will be automatically filtered based on the command bar search panel value.

Example

List

import { UiListItem, UiList, UiIcons } from '@altdot/extension';

const items: UiListItem[] = [
  {
    group: 'fruit',
    title: 'Apple',
    value: 'apple',
    icon: <UiList.Icon icon={UiIcons.Wand} />
  },
  {
    group: 'fruit',
    title: 'Banana',
    value: 'banana',
    icon: <UiList.Icon icon={UiIcons.Wand} />
  },
  {
    group: 'vegetable',
    title: 'Carrot',
    value: 'carrot',
    icon: <UiList.Icon icon={UiIcons.Wand} />
  },
  {
    group: 'vegetable',
    title: 'Eggplant',
    value: 'eggplant',
    icon: <UiList.Icon icon={UiIcons.Wand} />
  },
];

export default function Command() {
  return (
    <UiList items={items} />
  );
}

List with actions

import { UiListItem, UiList, UiIcons, _extension } from '@altdot/extension';

const items: UiListItem[] = [
  {
    group: 'fruit',
    title: 'Apple',
    value: 'apple',
    actions: [
      {
        type: 'button',
        value: 'toast',
        title: 'Show toast',
        icon: UiIcons.BellRing,
        onSelected() {
          _extension.ui.showToast({ title: 'Apple' }),
        }
      }
    ],
  },
  {
    group: 'fruit',
    title: 'Banana',
    value: 'banana',
    actions: [
      {
        type: 'button',
        value: 'toast',
        title: 'Show toast',
        icon: UiIcons.BellRing,
        onSelected() {
          _extension.ui.showToast({ title: 'Banana' }),
        }
      }
    ],
  },
  {
    group: 'vegetable',
    title: 'Carrot',
    value: 'carrot',
  },
  {
    group: 'vegetable',
    title: 'Eggplant',
    value: 'eggplant',
  },
];

export default function Command() {
  return (
    <UiList items={items} />
  );
}

List with custom render item

import { UiListItem, UiList, UiIcons, _extension } from '@altdot/extension';

const items: UiListItem[] = [
  {
    group: 'fruit',
    title: 'Apple',
    value: 'apple',
  },
  {
    group: 'fruit',
    title: 'Banana',
    value: 'banana',
  },
  {
    group: 'vegetable',
    title: 'Carrot',
    value: 'carrot',
  },
  {
    group: 'vegetable',
    title: 'Eggplant',
    value: 'eggplant',
  },
];

export default function Command() {
  return (
    <UiList
      items={items}
      renderItem={({ item, ref, selected }) => (
        <UiList.Item
          {...item}
          selected={selected}
          ref={ref}
          icon={<UiList.Icon icon={UiIcons.Wand} />}
          actions={[
            {
              type: 'button',
              value: 'toast',
              title: 'Show toast',
              icon: UiIcons.BellRing,
              onSelected() {
                _extension.ui.showToast({ title: item.title }),
              }
            }
          ]}
        />
      )}
    />
  );
}

List with custom filter

import { UiListItem, UiList, UiIcons, _extension } from '@altdot/extension';

const items: UiListItem[] = [
  {
    group: 'fruit',
    title: 'Apple',
    value: 'apple',
  },
  {
    group: 'fruit',
    title: 'Banana',
    value: 'banana',
  },
  {
    group: 'vegetable',
    title: 'Carrot',
    value: 'carrot',
  },
  {
    group: 'vegetable',
    title: 'Eggplant',
    value: 'eggplant',
  },
];

function customFilter(items: UiListItem[], search: string) {
  return items.filter((item) => item.title.startsWith(search));
}

export default function Command() {
  return (
    <UiList
      items={items}
      customFilter={customFilter}
    />
  );
}

Props

Name	Type	Description
items	UiListItem[]	The list items
search	?string	Items search filter
selectedItem	?string	Items search filter
shouldFilter	?boolean	Whether to filter the items
noDataSlot	?React.ReactNode	Element to show when no items match the filter
disabledItemSelection	?boolean	Disable the item selection
onItemSelected	?((value: string) => void)	Fired when an item is selected
onSearchChanged	?((value: string) => void)	Fired when the search is changed
renderItem	?((detail: UiListRenderItemDetail[], index: number) => React.ReactNode)	Custom list item renderer
renderGroupHeader	?((label: string, index: number) => React.ReactNode)	Custom group header renderer

UiList.Item

Ui list item component.

Example

<UiList
  items={items}
  renderItem={({ item, ref, selected }) => (
    <UiList.Item
      {...item}
      selected={selected}
      ref={ref}
      icon={<UiList.Icon icon={UiIcons.Wand} />}
    />
  )}
/>

Props

Name	Type	Description
value	string	The list item’s unique value
selected	?boolean	Whether the item is selected
title	?string | React.ReactNode	The list item’s title that will be displayed
actions	?UiListItemAction[]	The list item’s actions
subtitle	?(string | React.ReactNode)	Subtitle that will be displayed next to the title
icon	`?(string	React.ReactNode)`
description	?(string | React.ReactNode)	Shortcut description about the item
alias	?(string | React.ReactNode)	The list item’s alias
keywords	?string[]	Additional keywords for the item. It will be used when filtering the list items.
onSelected	?(() => void)	Will be fired when the item is selected
suffix	?(string | React.ReactNode)	The item’s suffix. Will be displayed on the item’s right side.

UiList.Icon

Icon wrapper for the ui list item.

Example

<UiList
  items={items}
  renderItem={({ item, ref, selected }) => (
    <UiList.Item
      {...item}
      selected={selected}
      ref={ref}
      icon={<UiList.Icon icon={UiIcons.Wand} />}
    />
  )}
/>

Props

Name	Type	Description
icon	`string	React.Element`

Types

UiListItem

The list item data.

interface UiListItem<T = any> {
  value: string;
  title: string;
  metadata?: T;
  alias?: string;
  group?: string;
  subtitle?: string;
  keywords?: string[];
  description?: string;
  searchOnly?: boolean;
  icon?: React.ReactNode;
  onSelected?: () => void;
  actions?: UiListItemAction[];
  suffix?: string | React.ReactNode;
}

Property	Type	Description
value	string	The list item’s unique value
title	string	The list item’s title that will be displayed
actions	?UiListItemAction[]	The list item’s actions
subtitle	?string	Subtitle that will be displayed next to the title
icon	?React.ReactNode	The list item’s icon that will be displayed
description	?string	Shortcut description about the item
metadata	?any	The list item’s metadata
alias	?string	The list item’s alias
keywords	?string[]	Additional keywords for the item. It will be used when filtering the list items.
searchOnly	?boolean	Whether the item will only be shown when filtering the items
onSelected	?(() => void)	Will be fired when the item is selected
suffix	?(string | React.ReactNode)	The item’s suffix. Will be displayed on the item’s right side.

UiListItemActionBase

Contains information about the list item.

interface UiListItemActionBase {
  title: string;
  value: string;
  disabled?: boolean;
  icon: React.ReactNode;
  shortcut?: KeyboardShortcut;
  color?: 'default' | 'primary' | 'destructive';
}

Property	Type	Description
value	string	The action’s unique value
title	string	The action’s title
icon	?React.ReactNode	The action’s icon
disabled	?boolean	Whether the item is disabled
color	?('default' | 'primary' | 'destructive')	The action’s color
shortcut	?KeyboardShortcut	The action’s keyboard shortcut

UiListItemActionButton

List item action button type.

interface UiListItemActionButton extends UiListItemActionBase {
  type: 'button';
  onAction: () => void;
}

Property	Type	Description
type	button	Item action type
onAction	() => void	Will be fired when the action is selected
UiListItemActionBase

UiListItemActionMenu

List item action button type.

interface UiListItemActionMenu extends UiListItemActionBase {
  type: 'menu';
  items: UiListItemActionButton[];
}

Property	Type	Description
type	button	Item action type
items	UiListItemActionButton[]	The action menu items
UiListItemActionBase

UiListItemAction

The list item action.

type UiListItemAction = UiListItemActionMenu | UiListItemActionButton;

UiListRenderItemDetail

The item detail when passing a function in the renderItem prop.

interface UiListRenderItemDetail {
  item: UiListItem;
  selected: boolean;
  ref: React.Ref<HTMLDivElement>;
  props: Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> & {
    onSelected?: () => void;
  };
}

Property	Type	Description
item	UiListItem	The list item
selected	boolean	Whether the item is selected
ref	React.Ref<HTMLDivElement>	The item’s ref prop
props	Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> & { onSelected?: () => void }	The item’s props

KeyboardShorcut

Keyboard shortcut.

interface KeyboardShortcut {
  key: string;
  mod1: KeyboardShortcutModifier;
  mod2?: KeyboardShortcutModifier;
}

Property	Type	Description
key	string	The keyboard shortcut key
mod1	KeyboardShortcutModifier	The keyboard shortcut modifier key
mod2	?KeyboardShortcutModifier	The keyboard shortcut modifier key

KeyboardShortcutModifier

Keyboard shortcut modifier.

type KeyboardShortcutModifier = 'mod' | 'altKey' | 'metaKey' | 'ctrlKey' | 'shiftKey';