Skip to main content
Big news! Interval has been acquired by Meter. Learn more →

io.search

Allows searching for arbitrary results from a search box.

Usage​

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));
  },
});
interval.com

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.

Props​

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

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?
On this page