Advanced

Option overrides

Inject or compute options client-side, per suggestion type. Useful when an option list depends on the user's typed input (e.g. dollar amounts, account names) or comes from your own state.

new AIAutocomplete(el, {
  optionOverrides: {
    account: () => [
      { text: "Savings", is_tappable: true, kind: null },
      { text: "Checking", is_tappable: true, kind: null },
    ],
    value: (query) => {
      const digits = query.replace(/\D/g, "");
      if (!digits) return [{ text: "$100", is_tappable: true, kind: null }];
      return [{ text: `$${digits}`, is_tappable: true, kind: null }];
    },
  },
  onSubmit: handleSubmit,
});

Controlled mode

Pass value, completedParams, onChange, and onParamsChange to lift state out of the library. Push updates back in with setValue and setCompletedParams.

const ac = new AIAutocomplete(container, {
  apiConfig: { apiKey: "pk_v1_your_public_key" },
  value: "initial text",
  completedParams: [],
  onChange: (text) => {/* sync to your store */},
  onParamsChange: (params) => {/* sync to your store */},
  onSubmit: handleSubmit,
});

// Push updates back into the library
ac.setValue("new text");
ac.setCompletedParams([]);

SSR safety

The library is SSR-safe — there's no top-level document or window access. Instantiate the library only on the client (e.g. in a useEffect, onMount, or after window is defined).

Accessibility

The component implements the ARIA combobox pattern. Things you should know:

• The dropdown uses role="listbox" with aria-activedescendant pointing at the highlighted option.
• Pills are buttons (role="button") and announce as part of the live input.
• Keyboard: arrow keys navigate, Enter submits, Tab autocompletes, Escape closes the dropdown.