Ui componentsCommon settings

Search

Customize search-related settings for the Inkeep widgets.

The search configuration provides settings for all search-related components, including search behavior, appearance, and functionality. These settings allow you to customize how users interact with the search interface, how results are displayed, and how the search behavior works.

Basic Configuration

// Basic search configuration
const searchSettings: InkeepSearchSettings = {
  placeholder: "Search documentation...",
  defaultQuery: "",
  maxResults: 40,
  debounceTimeMs: 300,
  shouldOpenLinksInNewTab: true,
  shouldAutoFocusInput: true,
};
 
// Advanced configuration with analytics and customization
const searchSettings: InkeepSearchSettings = {
  placeholder: "Search our docs, GitHub, and community...",
  defaultQuery: new URLSearchParams(window.location.search).get("q") || "",
  maxResults: 50,
  debounceTimeMs: 250,
  shouldOpenLinksInNewTab: true,
  searchQueryParamKey: "search",
  onQueryChange: (query) => {
    analytics.track("search_query", { query });
    updateURLParams(query);
  },
  tabs: ["Publications", ["GitHub", { isAlwaysVisible: true }], "Forums"],
};

Core Settings

Configure basic search behavior and appearance:

OptionTypeDefaultDescription
placeholderstring'Search anything...' (desktop), 'Search' (mobile)Text shown in empty search input
defaultQuerystring''Initial search query on load
maxResultsnumber40Maximum number of results to show
debounceTimeMsnumber0Milliseconds to wait before searching
shouldOpenLinksInNewTabbooleanfalseOpen results in new tab
searchQueryParamKeystringnullURL parameter for search query; gets appended to the URL when a result is clicked
view"single-pane" | "dual-pane""single-pane"Whether to render the search results in a single list or a two pane view with a list of results on the left and a preview of the content on the right
const searchSettings: InkeepSearchSettings = {
  // ...
  placeholder: "Search documentation...",
  defaultQuery: "",
  maxResults: 40,
  debounceTimeMs: 300,
  shouldOpenLinksInNewTab: true,
  searchQueryParamKey: "q",
};

Search Tabs

Configure result categorization and organization:

interface SearchTab {
  [0]: string;
  [1]: {
    isAlwaysVisible?: boolean;
  };
}
OptionTypeRequiredDescription
tabs(string | SearchTab)[]NoTabs to display in results

The tabs feature supports several configuration patterns:

const searchSettings: InkeepSearchSettings = {
  // Basic tabs
  tabs: ["All", "Publications", "GitHub", "Forums"],
 
  // With always visible option
  tabs: [
    "All",
    "Publications",
    ["GitHub", { isAlwaysVisible: true }],
    "Forums",
  ],
 
  // Hide "All" tab, show only Publications and GitHub
  tabs: ["Publications", "GitHub"],
 
  // No tabs (just show all results)
  tabs: [],
};

Default tabs if none provided:

  • All
  • Publications
  • PDFs
  • GitHub
  • Forums
  • Discord
  • Slack
  • StackOverflow

The tabs are displayed in the order they are provided in the tabs array.

Event Handling

Configure search event callbacks:

OptionTypeRequiredDescription
onQueryChange(query: string) => voidNoCalled when search query changes
const searchSettings: InkeepSearchSettings = {
  // ...
  onQueryChange: (query) => {
    // Maybe Update URL
    const url = new URL(window.location.href);
    url.searchParams.set("q", query);
    window.history.replaceState({}, "", url);
  },
};

On this page