API
The FindkitUI
constructor supports following options for customization
const ui = new FindkitUI({
publicToken: "<TOKEN>",
minTerms: 0,
// ...
});
Constructor Options
api docspublicToken: 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 docsminTerms: 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.
css: string
Inject custom styles to the Shadow Root. See Styling.
api docslockScroll: 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%;
}
shadowDom: boolean
Disable shadow dom. See Styling.
api docsslots: object
Inject custom components to into the UI. See Slot Overrides.
api docsparams: object
Customize search request params. See Search Params.
api docsgroups: object[]
Group search results. See Groups.
api docsgroupOrder: "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 docsinfiniteScroll: boolean
Disable automatic result loading on scroll and require button click to load more results.
api docsinstanceId: 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.
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"
.
load: Function
Custom async function for loading the implemention code. See Disable CDN.
api docssearchEndpoint: string
Send search requests to this custom endpoint.
api docscontainer: 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.
modal: boolean
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
header: boolean
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.
router: Router
Possible values:
"querystring"
(default)"hash"
"memory"
See Routing.
api docsfetchCount: number
How many results to fetch in a single request.
api docslang: 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 docstranslations: 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 docsmonitorDocumentLang: 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
Methods
Following methods are available on the FindkitUI
instance.
.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.
.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
.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()
.
.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.
.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"]];
});
.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;
});
.setLang(lang)
New in v0.5.0
Set the current UI language. See lang
.
.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
.
.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.
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