Skip to main content

Events

Events emitted by the FindkitUI instance. See on() and once().

Example:

const unsubscribe = ui.on("open", () => {
    alert("Modal opened!");
});

The events are also emitted as DOM events on the window object.

Event Names​

The available event names.

loading​

Delayed loading event. Fired when any network request issued by FinkditUI takes more than usual due to bad network conditions. If the network is quick enough this event never fires. Fired for the lazy load and search requests.

Used to implement loading indicator in a way it does not flash when the responses instant. Clear the loading indicator in the loading-done event.

If you need to know exactly when the search requests happen see fetch and fetch-done events.

Also available as useLoading slot override hook.

Event Object Interface

loading-done​

Fired when the loading event completes.

Event Object Interface

open​

When the modal is opened

Event Object Interface

request-open​

When the modal is requested to open. Used to add loading indicators when the lazy loading has not yet happened. Emitted before open event.

Event Object Interface

close​

Emitted when the modal is closed

debounced-search​

Emitted when the user has stopped typing search terms. Used to for search analytics.

Event Object Interface

params​

Emitted when the .params changes from a .updateParams() call.

Event Object Interface

groups​

Emitted when the .groups changes from a .updateGroups() call.

Event Object Interface

status​

Emitted when the status changes

Event Object Interface

fetch​

Emitted before sending a search request.

It possible to make transient updates to the search request inside the fetch event handler either by updating the search terms on the event object event.terms property or by calling the event.transientUpdateParams() or event.transientUpdateGroups(). The updates are only used for that specific search and are not not persisted to the internal FindkitUI state. The transient* methods otherwise work like the normal updateParams and updateGroups methods.

A common use case is to sort results by creation date when there are no search terms and by relevancy when user types some search terms.

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

ui.on("fetch", (event) => {
    // Sort by creation date when there is no search terms
    if (event.terms.length.trim() === "") {
        event.transientUpdateParams((params) => {
            params.sort = { created: { $order: "desc" } };
        });
    }
});

Another use case is to implement customs terms that actually are filters:

ui.on("fetch", (event) => {
    const tags = [];

    // Turn "tag:electronics computer" to "computer"
    event.terms = event.terms.replaceAll(/tag:([^ ]+)/g, (tag) => {
        tags.push(tag);
        return "";
    });

    // And filter using the "electronics" tag
    if (tags.length > 0) {
        event.transientUpdateParams({
            filter: { tags: { $all: tags } },
        });
    }
});

The transient methods and terms updating is added in v0.13.0

Event Object Interface

fetch-done​

Emitted when a search request completes

Event Object Interface

hit-click​

When a search hit is clicked.

Event Object Interface

lang​

New in v0.5.0

Emitted when

  • <html lang> is initially read
  • <html lang> is mutated
  • Language is set explicitly with setLang
Event Object Interface

custom-router-data​

New in v0.9.0

Emits data previously set using the setCustomRouterData method when the Findkit router reads the URL. If there is no custom data in the URL defaultCustomRouterData is emitted. The URL is read on page load and on History pushState and replaceState calls.

Read the Custom Router Data page for more information.

ui.on("custom-router-data", (e) => {
    // Use e.data to fill form inputs, update React/Vue/Svelte state...
    // Update search params using .updateParams()
});
Event Object Interface

bind-input​

New in v0.8.0

Emitted when an input is bound using .bindInput() or useInput(). This is also called for the build-in input.

Event Object Interface

unbind-input​

New in v0.8.0

When an input is unbound using the unbound method returned from .bindInput(). Emitted also when the UI is disposed with .dispose().

Use to properly cleanup any listeners you set on the bind-input event.

Example

ui.on("bind-input", (e1) => {
    const listener = () => {
        /* whatever */
    };

    e1.input.addEventListener("focus", listener);

    ui.once("unbind-input", (e2) => {
        if (e1.input === e2.input) {
            e.input.removeEventListener("focus", listener);
        }
    });
});
Event Object Interface

dispose​

Emitted when the FindkitUI instance is discarded with the .dispose() method.

init​

New in v0.17.0

Emitted when a FindkitUI instance is being constructed. Allows full customization of the options passed to it. Useful when you need to modify a FindkitUI instance when you cannot access the code actually creating the instance. For example when the Findkit WordPress plugin creates the instance in a Gutenberg block.

Since this event is fired from the constructor it is only usable from the DOM Event.

Example

window.addEventListener("findkituievent", (e) => {
    if (e.detail.eventName !== "init") {
        return;
    }

    if (e.detail.instance.id !== "my") {
        return;
    }

    // See API docs for what is available
    // https://docs.findkit.com/ui-api/ui.initevent/
    const { css } = e.detail.data.utils;
    const { useState } = e.detail.data.preact;

    e.detail.data.options.minTerms = 5;

    e.detail.data.options.css = css`
        .modified {
            color: red;
        }
    `;

    e.detail.data.options.slots = {
        Header(props) {
            const [state] = useState("preact state");

            return html`
                ${props.children}
                <div class="modified">Hello</div>
            `;
        },
    };
});
Event Object Interface

DOM Events​

All events are emitted as DOM events on the window object as well. This allows for example analytics tools to bind to all FindkitUI instances without having access to the code that actually creates the instances. For example the ones created by the Findkit WordPress plugin.

The events are wrapped into a findkituievent CustomEvent.

Example

window.addEventListener("findkituievent", (e) => {
    // The FindkitUI instance
    e.detail.instance;

    // This event may come from multiple instances so you should guard using
    // the instance id.
    if (e.detail.instance.id !== "my") {
        // Only interested on events from `new FindkitUI({instanceId: "my"})`
        return;
    }

    // The FindkitUI event name
    if (e.detail.eventName !== "fetch") {
        return;
    }

    // The data passed to the event
    e.detail.data;
    e.detail.data.terms;
    e.detail.data.transientUpdateParams();
    // ...
});