io.search

Represents a search component.

Usage

JavaScript/TypeScript

const value = await io.search("Search for Order ID". {
  renderResult: order => ({
    label: order.id,
    description: order.notes,
    image: {
      url: order.image,
      size: "small",
    },
  }),
  onSearch: async query => {
    return orders.filter(order => order.includes(query));
  },
})

Python

async def render_result(order):
    return {
        "label": order["id"],
        "description": order["notes"],
        "image": {
            "url": order["image"],
            "size": "small"
        }
        
    }

async def on_search(query):
    return [order for order in orders if query in order]

value = await io.search(
    "Search for Order ID",
    render_result=render_result,
    on_search=on_search
)

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.