Hooks and Utils

Following utils can be imported from @findkit/ui for slot component usage.

Functions starting with the use keyword are Preact hooks.

useParams()

Slot override hook version of updateParams.

Example

import { FindkitUI, html, useInput } from "@findkit/ui";

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    slots: {
        Header(props) {
            const [params, setParams] = useParams();
            const checked = params.filter.tags === "crawler";

            return html`
                ${props.children}
                <label>
                    <input
                        type="checkbox"
                        checked=${checked}
                        onChange=${() => {
                            setParams((params) => {
                                if (checked) {
                                    params.filter.tags = "crawler";
                                } else {
                                    delete params.filter.tags;
                                }
                            });
                        }}
                    />
                    Limit results with tag "crawler"
                </label>
            `;
        },
    },
});

api docs

useGroups()

Slot override Hook version of updateGroups.

Example

const [groups, setGroups] = useGroups();

const onClick = () => {
    setGroups((group1, groups2 /* ...groups */) => {
        group1.title = "new title";
        group2.params.filter.tags = "crawler";
    });
};

api docs

useTerms()

Return the search terms used for the current search results.

api docs

useInput()

Hook for binding custom inputs as the search terms inputs. Usually used in the Header slot to override the default search input with a fully custom one

import { FindkitUI, html, useInput } from "@findkit/ui";

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    slots: {
        Header(props) {
            const ref = useInput();
            return html`<input type="text" ref=${ref} />`;
        },
    },
});

api docs

useTotalHitCount()

Return total hit count. Includes count from all groups if multiple groups are used.

api docs

useLoading()

Delayed loading event as a hook. Return true when a network requet is taking longer than usual. Use to to implement custom loading indicators in a slot overrides.

api docs

useLang()

Return the current UI language. Can be used to implement custom ui string translations on slot overrides. See setLang.

api docs

useTranslate()

New in v0.19.0

Get the translation function. Can render existing translations but it can also render custom translations. See also addTranslation

import { FindkitUI, useTranslate } from "@findkit/ui";

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    slots: {
        Header(props) {
            const t = useTranslate();
            return html`${t("greet", { name: "Matt" })}`;
        },
    },
});

ui.addTranslation(
    "en",
    {}, // Override build-in translations
    {   // Custom translations
        greet: "Hello {{name}}!",
    },
);

When using Typescript the translation key is constrained to the internal keys. Use type argument to widen it.

const t = useTranslate<"greet" | "another">();

api docs

useCustomRouterData()

New in v0.16.0

Preact Hook version of the setCustomRouterData method. Works like useState but the value must be a flat object of string values. Eg. {[key: string]: string}

import { FindkitUI, html, useCustomRouterData, useParams } from "@findkit/ui";

const ui = new FindkitUI({
    publicToken: "<TOKEN>",
    slots: {
        Header(props) {
            const [data, setData] = useCustomRouterData({ value: "yes" });
            const [params, setParams] = useParams();

            const onClick = () => {
                setData((data) => {
                    if (data.value === "yes") {
                        data.value = "no";
                    } else {
                        data.value = "yes";
                    }
                });

                // Update search params
                updateParams(/* ... */);
            };

            return html`
                <button type="button" onClick=${onClick}>${data.value}</button>
            `;
        },
    },
});

api docs

useResults()

New in v0.20.0

Access the search results by groups. Returns an array of GroupResults objects. If you are not using groups just use the first item in the array: const results = useResults()[0].

preact

Object of commonly used Preact Hooks. See the api docs for details.

api docs

html

Prebound HTM (Hyperscript Tagged Markup) tagged template. For more information see: https://github.com/developit/htm

api docs

h

The Preact JSX pragma

api docs