Skip to main content

API

The FindkitUI constructor supports following options for customization

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    minTerms: 0,
    // ...
});

Constructor Options​

api docs

publicToken: string​

The public token which identifies the Findkit Project. This can be seen from the Hub or with findkit status CLI command.

This is the only required option.

api docs

minTerms: number​

Search terms threshold when to make the search request. Defaults to 3. Can be set to 0 as well when a search will be then made immediately when the UI is rendered.

api docs

css: string​

Inject custom styles to the Shadow Root. See Styling.

api docs

lockScroll: boolean​

Lock page scrolling. Only used with mode: "modal". Defaults to true. You may want set this to false when using the Offset Modal Pattern with page scrolling.

Use this CSS to enable page scrolling:

.findkit--modal-container {
    inset: initial;
    position: absolute;
    width: 100%;
}
api docs

shadowDom: boolean​

Disable shadow dom. See Styling.

api docs

slots: object​

Inject custom components to into the UI. See Slot Overrides.

api docs

params: object​

Customize search request params. See Search Params.

api docs

groups: object[]​

Group search results. See Groups.

api docs

groupOrder: "relevancy" | "static" | (a,b)=>number​

Group order logic. Defaults to "static" which preserves groups array order.

In "relevancy" mode groups are ordered based on the groups most relevants results relevancy. Relevancy mode can be affected by groups' option relevancyBoost, which is multiplied with the result relevancy

Also supports custom sort functions.

api docs

infiniteScroll: boolean​

Disable automatic result loading on scroll and require button click to load more results.

api docs

instanceId: string​

When using multiple FindkitUI instances you must provide a custom instanceId to avoid conflicts in the query strings and idendifying class names. This is needed for example when you have global site search and a more specific search running on the same page.

note

If you have only one search setup and you are getting an error about a conflicting instance id it means you are accidentally doing multiple new Findkit() calls without calling dispose on the previous instance.

If you are creating the FindkitUI instance inside a React component you must call the dispose method on a useEffect cleanup. See the React custom container example.

Defaults to "fdk".

api docs

load: Function​

Custom async function for loading the implemention code. See Disable CDN.

api docs

searchEndpoint: string​

Send search requests to this custom endpoint.

api docs

container: selector​

Render the modal to a custom container. If not defined Findkit UI will create one dynamically and appends it to <body>.

Can be defined as a CSS selector or as an Element object.

api docs

Set to false to disable the modal mode. This makes sense only when used with a custom container with the container option.

This disables following:

  • Focus trapping
  • Open/close modes. It is always "open".
  • Scrolling in the container
api docs

Set to false to hide the default modal header with the search input and the close button. Useful with the non-fullscreen embedding patterns where the input is placed on the website outside the Findkit UI context. Ex. in the site header.

api docs

router: Router​

Possible values:

  • "querystring" (default)
  • "hash"
  • "memory"

See Routing.

api docs

fetchCount: number​

How many results to fetch in a single request.

api docs

lang: string​

New in v0.5.0

Set the UI language. If not defined the language is read from the <html lang> attribute. See setLang. Not to be confused with the lang search param filter.

Replaces deprecated ui.lang in v0.5.0

api docs

translations: object​

New in v0.5.0

Add the UI translations. See addTranslation.

See TranslationStrings for the available transtion strings.

Example

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    lang: "sv",
    // Add translations
    translations: {
        sv: {
            close: "Stänga"
            // ... https://findk.it/strings
        }
    }
});

Replaces deprecated ui.overrides in v0.5.0

api docs

monitorDocumentLang: boolean​

New in v0.5.0

Update the UI language by monitoring <html lang> changes. Useful on Single-Page Apps where the language can change without a page load.

Defaults to true

api docs

Methods​

Following methods are available on the FindkitUI instance.

api docs

.open(terms)​

Open the search modal. If search terms are passed in the input will populated with it and a search request is made immediately.

.openFrom(selector)​

Open the modal from the given element or elements. Select can be a Element object or a CSS selector string. A cleanup function is returned which will unbind all the event listeners when called.

api docs

.trapFocus(selector)​

Add additional elements to the focus trap. For example if you want to add close button outside of the modal use this to make it keyboard accessible.

A function is returned which will remove the element from the focus trap when invoked.

api docs

.bindInput(selector)​

Bind any input to the Search UI. The selector can be CSS string or the raw HTMLInputElement. A unbind funtion is returned.

  • Input value is throttled to UI search terms
  • Focus is included in the focus trap
  • The lazy load will be triggered when the input is focused
api docs

.preload()​

Preload the implementation code and css. This is automatically called on mouseover for elements passed to .openFrom() and on focus for inputs passed to .bindInput().

api docs

.close()​

Close the search modal.

api docs

.dispose()​

Close the search modal and discard the FindkitUI instance with its resources. The modal cannot be opened any more after it is disposed.

api docs

.updateParams(fn)​

Update the search params. It calls the given function immediately giving the internal params object as the first parameter. The object can mutated or a new one can be returned. A new search will be issued immediately.

Example

ui.updateParams((params) => {
    params.tagQuery = [["domain/another.example"]];
});
api docs

.updateGroups(fn)​

Update the groups. The callback function works like in updateParams but the previously defined groups are spread to the function params.

Example

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    groups: [{ tagQuery: [["html"]] }, { tagQuery: [["pdf"]] }],
});

ui.updateGroups((pages, pdf) => {
    pages.previewSize = 5;
    pdf.previewSize = 5;
});
api docs

.setLang(lang)​

New in v0.5.0

Set the current UI language. See lang.

api docs

.addTranslation(lang, translation)​

New in v0.5.0

Add a new UI translation. Can be used to override existing translation strings as well. See TranslationStrings for the available transtion strings.

See translations.

api docs

.on()​

Args

  • eventName: string
  • callback: (event) => void

Bind event handled to an event. Returns an unbind function. See Events.

api docs

.once()​

Args

  • eventName: string
  • callback: (event) => void

Like .on() but unbound immediately after the first event. See Events.

api docs

Properties​

.params​

The current Search Params

api docs

.groups​

The current Groups

api docs

.terms​

The current search terms used on the last completed search request