Search Params
The search request can be customized with the params
option
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
// Limit results to example.com domain
filter: { tags: "domain/example.com" },
},
});
The params can be dynamically updated using the
ui.updateParams()
method and the
useParams()
hook
to update from Slot Overrides.
Options
api docssemantic: object
New in 1.4.0
Make AI powered semantic search using text embedding vectors.
Requires ml_model
option in the TOML configuration
for the vectors to be generated.
Parameters:
mode: string
"only"
: Use only the semantic search, no keyword search"hybrid"
: Use both semantic and keyword search
weight: number
- Numerical value for the weight of the semantic search in the hybrid mode
k
: number- Number of nearest neighbors to fetch from the semantic search
- Defaults to 5
Since semantic search cannot completely filter out results it is recommended to set operator: "or"
with the hybrid mode.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
operator: "or",
semantic: {
mode: "hybrid",
weight: 50,
k: 5,
},
},
});
createdDecay: number
0-1 numerical value for demoting old pages
modifiedDecay: number
0-1 numerical value for demoting stagnant pages
decayScale: string
To be used with createdDecay
or modifiedDecay
. Defines in which timeframe
decay filter is applied, e.g. "7d".
highlightLength: number
The length of returned hilight string. Se to 0
disable highlighting.
Too large values might slow down the search.
size: number
How many results to fetch in a single request.
lang: string
Limit results to the given language. A two letter language code. Not to be
confused with the lang
constructor option which sets the UI
language.
tagQuery: string[][]
Legacy tags only filtering method. Please prefer the filter option which is more intuitive and flexible to use.
Logical AND and OR operators are supported.
OR-syntax:
[["A", "B", "C"]]; // A OR B OR C
AND-syntax:
[["A"], ["B"], ["C"]]; // A AND B AND C
combining queries:
[["A"], ["B", "C"]]; // A AND (B OR C)
Complex tag queries can be expensive. Because of this, it's recommended that you preprocess your pages to have meaningful tags.
For example if there is 100 different sports categories on your website and you want to
show all the search results in a group "Sports". Instead of giving each sport a
specific tag name and querying it swimming OR biking OR ...
give each sport page a sport
tag and use it in the query.
tagBoost: Record<string, number>
Boost page scores with certain tags.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
tagBoost: {
important: 2,
},
},
});
This will increase the search score of pages with important
tag by x2. It is
also possible to down boost by using boost numbers less than one. Ex. 0.5 to
drop the score to half.
sort: Sort
New in v0.9.0
Use alternative sorting. By default search results are sorted by the relevancy score but it can be forced to be sorted by created or modified dates, keywords or by any custom field.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
sort: {
created: {
$order: "asc",
},
},
},
});
Multi-level sorting is also possible
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
sort: [
{
price: {
$order: "asc",
},
},
{
created: {
$order: "asc",
},
},
],
},
});
If sorting values are the same, the search results are sorted by the relevance score.
It is not possible to sort by the build-in title field. If you need to sort by the title, copy it to a keyword custom field and sort using it.
randomSort: RandomSort
New in v1.4.0
Give matching search results random relevancy scores, causing random result order. Same seed generates same random result order, meaning pagination works normally.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
randomSort: { seed: Date.now() },
},
});
With seed you can define "shared randoms" based on some value that is shared between users.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: {
// set the random seed based on day of the month
// meaning the results change every day
// while all the users see the same results each day
randomSort: { seed: new Date().getUTCDate() },
},
});
It is not possible to use sort
and randomSort
together.
Using both together will cause a search error.
filter: Filter
New in v0.9.0
Filter the search results by tags, created, modified, language and custom field using a MongoDB style filtering query. Read more on the Filtering page.
api docsskip: boolean
New in v0.15.0
Skip the search and always return an empty response. Can be used to optimize the search request when visually hiding some of the groups.
operator: "and" | "or"
New in v1.1.0
Whether to require all terms to appear in a page or any of them.
and
: All terms must appear in a page.or
: Only one term must appear in a page. Addional terms will increase the score.
Default is and
.
Example
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: { operator: "and" },
});
content: boolean
Return stored content text with the search results. This is a protected query and
must be enabled in using the
allow_content
TOML option.
The content will be returned in the content
field in hit
objects of the search results.
Default is false
.
Example
import {
FindkitUI,
html,
} from "https://cdn.findkit.com/ui/v1.1.0/esm/index.js";
const ui = new FindkitUI({
publicToken: "<TOKEN>",
params: { content: true },
slots: {
Hit(props) {
return html`${props.hit.content} `;
},
},
});