Altering HTML Outputs

This page covers customising the result preview HTML output structure.

Some use cases for this include:

  • The default HTML structure is not sufficient for your styling needs
  • You want to override or insert additional content sourced from your own fields (e.g. an image)
  • You want to change the default use case of linking to a web page entirely (e.g. use client side routing)

💡 If you only need to style the dropdown or search popup, you can include your own css file to do so and / or override the variables exposed by the default css bundle.

The only API option is similarly specified under the uiOptions key of the root configuration object.

    uiOptions: {
        listItemRender: ...

It’s interface is as follows:

type ListItemRender = async (
  h: CreateElement,
  opts: Options,  // what you passed to infisearch.init
  result: Result,
  query: Query,
) => Promise<HTMLElement>;

If you haven’t, you should also read through the Search API documentation on the Result and Query parameters.

h function

This is an optional helper function you may use to create elements.

The method signature is as such:

export type CreateElement = (
  // Element name
  name: string,

  // Element attribute map
  attrs: { [attrName: string]: string },

   Child elements (HTMLElement) OR text nodes (string)
   String parameters are automatically escaped.
  ...children: (string | HTMLElement)[]
) => HTMLElement;

Accessibility and User Interaction

To ensure that combobox controls work as expected, you should also ensure that the appropriate elements are labelled with role='option' (and optionally role='group').

Elements with role='option' will also have the .focus class applied to them once they are visually focused. You can use this class to style the option.


At the current, this API is moderately lengthy, performing things such as limiting the number of sub matches (heading-content pairs) per document, formatting the relative file path of documents into a breadcrumb form, etc.

There may be room for breaking this API down further as such, please help to bring up a feature request if you have any suggestions!.

Source Code

See the source to get a better idea of using this API.