io.search

Allows searching for arbitrary results from a search box.

Usage

TypeScript

const user = await io.search("Search for a user", {
  renderResult: user => ({
    label: user.name,
    description: user.email,
    image: {
      url: user.avatar,
      size: "small",
    },
  }),
  onSearch: async query => {
    return users.filter(user => user.name.includes(query));
  },
});

JavaScript

const user = await io.search("Search for a user", {
  renderResult: user => ({
    label: user.name,
    description: user.email,
    image: {
      url: user.avatar,
      size: "small",
    },
  }),
  onSearch: async query => {
    return users.filter(user => user.name.includes(query));
  },
});

Python

async def on_search(query: str):
    return [user for user in users if query in user.name]

def render_result(user):
    return {
        "label": user.name,
        "description": user.email,
        "image": {
            "url": user.avatar,
            "size": "small",
        },
    }

user = await io.search("Search for a user",
  render_result=render_result,
  on_search=on_search,
)

interval.com

Multi-search

TypeScript

Starting with v0.37.0, you can also accept multiple results at a time using the .multiple() chained method:

const selectedTags = await io
  .search("Add tags to this blog post", {
    renderResult: tag => tag.label,
    onSearch: async query => {
      return tags.filter(tag => tag.label.includes(query));
    },
  })
  .multiple({
    defaultValue: [
      { id: 12, label: "Web dev" },
      { id: 9, label: "Programming" },
    ],
  })
  .optional();

interval.com

The .multiple() method accepts an optional options object with a defaultValue property, which allows specifying the defaults for the multi-input. Any singular defaultValue prop from the search options object will be discarded for .multiple() inputs.

Optional multiple inputs with .multiple().optional() are supported, but multiple optional inputs with .optional().multiple() are not.

JavaScript

Starting with v0.37.0, you can also accept multiple results at a time using the .multiple() chained method:

const selectedTags = await io
  .search("Add tags to this blog post", {
    renderResult: tag => tag.label,
    onSearch: async query => {
      return tags.filter(tag => tag.label.includes(query));
    },
  })
  .multiple({
    defaultValue: [
      { id: 12, label: "Web dev" },
      { id: 9, label: "Programming" },
    ],
  })
  .optional();

interval.com

The .multiple() method accepts an optional options object with a defaultValue property, which allows specifying the defaults for the multi-input. Any singular defaultValue prop from the search options object will be discarded for .multiple() inputs.

Optional multiple inputs with .multiple().optional() are supported, but multiple optional inputs with .optional().multiple() are not.

Python

You can also accept multiple results at a time using the .multiple() chained method:

async def on_search(query: str):
    return [tag for tag in tags if query in tag.label]

def render_result(tag):
    return tag.label

user = await io.search("Add tags to this blog post",
  render_result=render_result,
  on_search=on_search,
).multiple(default_value=[
  { "id": 12, "label": "Web dev" },
  { "id": 9, "label": "Programming" },
]).optional();

interval.com

The .multiple() method accepts an optional options object with a default_value property, which allows specifying the defaults for the multi-input. Any singular default_value prop from the search options object will be discarded for .multiple() inputs.

Optional multiple inputs with .multiple().optional() are supported, but multiple optional inputs with .optional().multiple() are not.

Props

TypeScript

defaultValue

Optional

T

The default selected result.

disabled

Optional

boolean

Whether the search box is disabled.

helpText

Optional

string

Optional label providing additional context. Supports inline markdown elements like bold, italics, and links.

initialResults

Optional

T[]

Array of arbitrary data objects to set as the initial search results when no query has been provided.

onSearch

Required

(query: string) => Promise<T[]>

Receives a search query string as argument, returns an array of arbitrary data objects. Your provided `onSearch` function is called whenever the search query changes, debounced to limit the number of calls.

placeholder

Optional

string

Text to display in the input when no value is set.

renderResult

Required

(result: T) => string | number | boolean | Date | object

Controls how objects from `initialResults` and `onSearch` are rendered. Receives a single data object as argument. May return either a primitive value or an object for more advanced customization:

renderResult: (result: T) =>
  | string
  | number
  | boolean
  | Date
  | {
    // the visible item label
    label: string | number | boolean | Date;
    // an optional description
    description?: string;
    // a visible image to be displayed alongside the result
    // new in version 0.33.0
    image?: {
      // a URL to the image
      url?: string
      // the image alt tag
      alt?: string
      // the size of the image
      size?: "thumbnail" | "small" | "medium" | "large"
    }
    // deprecated, replaced with image.url
    imageUrl?: string
  }

Returns

T

JavaScript

defaultValue

Optional

T

The default selected result.

disabled

Optional

boolean

Whether the search box is disabled.

helpText

Optional

string

Optional label providing additional context. Supports inline markdown elements like bold, italics, and links.

initialResults

Optional

T[]

Array of arbitrary data objects to set as the initial search results when no query has been provided.

onSearch

Required

(query: string) => Promise<T[]>

Receives a search query string as argument, returns an array of arbitrary data objects. Your provided `onSearch` function is called whenever the search query changes, debounced to limit the number of calls.

placeholder

Optional

string

Text to display in the input when no value is set.

renderResult

Required

(result: T) => string | number | boolean | Date | object

Controls how objects from `initialResults` and `onSearch` are rendered. Receives a single data object as argument. May return either a primitive value or an object for more advanced customization:

renderResult: (result: T) =>
  | string
  | number
  | boolean
  | Date
  | {
    // the visible item label
    label: string | number | boolean | Date;
    // an optional description
    description?: string;
    // a visible image to be displayed alongside the result
    // new in version 0.33.0
    image?: {
      // a URL to the image
      url?: string
      // the image alt tag
      alt?: string
      // the size of the image
      size?: "thumbnail" | "small" | "medium" | "large"
    }
    // deprecated, replaced with image.url
    imageUrl?: string
  }

Returns

T

Python

default_value

Optional

T

The default selected result.

disabled

Optional

bool

Whether the search box is disabled, preventing edits to the `defaultValue`.

help_text

Optional

str

Secondary label for providing additional context.

initial_results

Optional

Iterable[T]

Iterable of arbitrary data objects to set as the initial search results when no query has been provided.

on_search

Required

(str) -> Awaitable[Iterable[T]]

Receives a search query string as argument, returns an iterable of arbitrary data objects. Your provided `on_search` function is called whenever the search query changes, debounced to limit the number of calls.

placeholder

Optional

str

Text to display in the input when no value is set.

render_result

Required

(T) -> PrimitiveValue | RenderableSearchResult

Controls how objects from `initial_results` and `on_search` are rendered. Receives a single data object as argument. May return either a primitive value or an object for more advanced customization.

PrimitiveValue = str | int | float | bool | date | time | datetime

class ImageSchema(TypedDict):
    url: NotRequired[str]
    alt: NotRequired[str]
    size: NotRequired[Literal["thumbnail", "small", "medium", "large"]]

class RenderableSearchResult(TypedDict):
    label: PrimitiveValue
    description: NotRequired[str]
    image: NotRequired[ImageSchema]

Returns

T

Examples

Typing

If using TypeScript, you can provide an optional type argument to io.search to aid it in inference for the return type and renderResult argument. TypeScript cannot always infer this automatically.

const selectedUser = await io.search<User>("Search for a user", {
  renderResult: user => ({
    label: user.name,
    description: user.email,
    image: {
      url: user.avatar,
      size: "small",
    },
  }),
  onSearch: async query => {
    return users.filter(user => user.name.includes(query));
  },
});

In the example above, both user and selectedUser are properly typed as User.

Was this section useful?