Base

The base configuration provides core settings for all Inkeep widgets. These settings control authentication, branding, theming, and general behavior.

Basic Configuration

import { type InkeepBaseSettings } from "@inkeep/cxkit-types";
 
// Simple configuration
const baseSettings: InkeepBaseSettings = {
  // Core authentication and branding
  env: "production",
  apiKey: "YOUR_API_KEY",
  organizationDisplayName: "Your Organization",
  primaryBrandColor: "#26D6FF", // See "Theme Customization" section for advanced theming options
  shouldBypassCaptcha: false, // Only enable with server-side API keys
 
  // User identification - See "User Properties" section for all options
  userProperties: {
    id: "user-id",
    email: "user@example.com",
    name: "User Name",
  },
 
  // Optional: Analytics configuration - See "Analytics Configuration" section
  privacyPreferences: {
    optOutAnalyticalCookies: false,
    optOutAllAnalytics: false,
  },
 
  // Optional: Color mode sync - See "Color Mode" section for advanced options
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme"],
      isDarkMode: (attrs) => attrs["data-theme"] === "dark",
    },
  },
};
 
// Advanced configuration with enterprise features
const enterpriseSettings: InkeepBaseSettings = {
  env: process.env.NODE_ENV,
  apiKey: process.env.INKEEP_API_KEY,
  organizationDisplayName: "Enterprise Corp",
  primaryBrandColor: "#0A2463",
  aiApiBaseUrl: "https://api.enterprise.com/inkeep",
  analyticsApiBaseUrl: "https://analytics.enterprise.com",
  userProperties: {
    id: getUserId(),
    email: getUserEmail(),
    name: getUserName(),
    role: getUserRole(),
    team: getCurrentTeam(),
  },
  userAuthToken: getAuthToken(),
  tags: ["enterprise", "self-hosted", getCurrentRegion()],
};

Configuration Options

Core Settings

Essential configuration options for authentication, branding, and basic widget setup. These settings form the foundation of your Inkeep integration.

Each setting serves a specific purpose in customizing the widget behavior:

Option	Type	Required	Description
`env`	`'production' \| 'development'`	No	Environment setting (defaults to 'production')
`apiKey`	`string`	Yes	Your Inkeep API key
`organizationDisplayName`	`string`	No	Display name for your organization
`primaryBrandColor`	`string`	Yes	Primary brand color (hex code)
`aiApiBaseUrl`	`string`	No	Custom base URL for API endpoints
`analyticsApiBaseUrl`	`string`	No	Custom base URL for analytics endpoints
`shadowHost`	`HTMLElement \| null`	No	Reference to shadow DOM host element
`rootElement`	`HTMLElement \| null`	No	Reference to root mounting element
`shouldBypassCaptcha`	`boolean`	No	Bypass captcha challenge (server-side API only)
`tags`	`string[]`	No	Custom tags for widget identification
`prism`	`Prism`	No	Instance of Prism for syntax highlighting. You can add support for additional languages by importing them from `prismjs` and passing in the Prism instance

User Properties

Configure user-specific information for personalization, tracking, and authentication. This allows you to identify users and provide personalized experiences.

interface UserProperties {
  /**
   * The user ID.
   */
  id?: string;
  /**
   * The user email.
   */
  email?: string;
  /**
   * The user name.
   */
  name?: string;
  /**
   * The user cohorts.
   */
  cohorts?: string[];
}

Property	Type	Required	Description
`userProperties`	`UserProperties`	No	User identification and metadata
`userAuthToken`	`string`	No	Authentication token for the user

// Basic user configuration
const baseSettings: InkeepBaseSettings = {
  userProperties: {
    id: "user-123",
    email: "user@example.com",
    name: "John Doe",
  },
};
 
// Advanced user configuration
const enterpriseSettings: InkeepBaseSettings = {
  userProperties: {
    id: "user-456",
    email: "jane@enterprise.com",
    name: "Jane Smith",
    cohorts: ["admin", "engineering"],
  },
  userAuthToken: "jwt-token-here",
};

Privacy Preferences

Control analytics and cookie preferences for tracking user interactions with the widget.

interface PrivacyPreferences {
  /**
   * Whether to opt out of analytical cookies
   */
  optOutAnalyticalCookies?: boolean;
  /**
   * Whether to opt out of all analytics
   */
  optOutAllAnalytics?: boolean;
  /**
   * Whether to opt out of functional cookies
   */
  optOutFunctionalCookies?: boolean;
}

Property	Type	Required	Description
`privacyPreferences`	`PrivacyPreferences`	No	Privacy preferences configuration

// Basic analytics configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  privacyPreferences: {
    optOutAnalyticalCookies: false,
    optOutAllAnalytics: false,
    optOutFunctionalCookies: false,
  },
};
 
// Privacy-focused configuration
const privacySettings: InkeepBaseSettings = {
  // ...
  privacyPreferences: {
    optOutAnalyticalCookies: true,
    optOutAllAnalytics: true,
    optOutFunctionalCookies: true,
  },
};

Event Handling

Configure callbacks for tracking and processing widget events. This allows you to integrate with your own analytics or monitoring systems.

type InkeepCallbackEvent = InkeepEventWithCommon & {
  userProperties: UserProperties;
  eventName: string;
  properties: {
    componentType?: any;
    tags?: string[];
    [key: string]: any;
  };
};

Property	Type	Required	Description
`onEvent`	`(event: InkeepCallbackEvent) => void`	No	Event processing callback function

// Basic event handling
const baseSettings: InkeepBaseSettings = {
  // ...
  onEvent: (event) => {
    console.log("Event:", event.eventName, event.properties);
    analytics.track(event.eventName, event.properties);
  },
};

You can see the Analytics guide for more information.

Color Mode

Synchronize the widget's appearance with your application's theme. This enables seamless dark/light mode integration.

interface ColorMode {
  // ...
  sync?: {
    target: HTMLElement | string;
    attributes: string[];
    isDarkMode: (attributes: Record<string, string | null>) => boolean;
    onChange?: (colorMode: string) => void;
  };
}

Property	Type	Required	Description
`colorMode`	`ColorMode`	No	Theme synchronization configuration

// Basic color mode configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme"],
      isDarkMode: (attrs) => attrs["data-theme"] === "dark",
    },
  },
};
 
// Advanced color mode configuration
const advancedSettings: InkeepBaseSettings = {
  // ...
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme", "class"],
      isDarkMode: (attrs) => {
        const preference = localStorage.getItem("theme");
        return (
          preference === "dark" ||
          attrs["data-theme"] === "dark" ||
          attrs["class"]?.includes("dark") ||
          window.matchMedia("(prefers-color-scheme: dark)").matches
        );
      },
      onChange: (mode) => {
        localStorage.setItem("theme", mode);
        updateThemeColor(mode);
      },
    },
  },
};

Theme Customization

Configure advanced styling and branding options for the widget. This includes colors, styles, and custom CSS.

interface UserTheme {
  // ...
  syntaxHighlighter?: {
    lightTheme?: any;
    darkTheme?: any;
  };
  primaryColors?: PrimaryColors;
  varsClassName?: string;
  styles?: Array<{
    key: string;
    type: "link" | "style";
    value: string;
  }>;
}

Property	Type	Required	Description
`theme`	`UserTheme`	No	Theme customization settings

// Basic theme configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  theme: {
    primaryColors: {
      medium: "#26D6FF",
      light: "#60a5fa",
      strong: "#1d4ed8",
    },
    styles: [
      {
        key: "chat-container",
        type: "style",
        value: ".ikp-chat { border-radius: 8px; }",
      },
    ],
  },
};
 
// Advanced theme configuration
const enterpriseSettings: InkeepBaseSettings = {
  // ...
  theme: {
    primaryColors: {
      mediumSubtle: "rgba(38, 214, 255, 0.3)",
      strong: "#1d4ed8",
      stronger: "#1e40af",
    },
    syntaxHighlighter: {
      lightTheme: themes.github,
      darkTheme: themes.dracula,
    },
    styles: [
      {
        key: "google-fonts",
        type: "link",
        value:
          "https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap",
      },
      {
        key: "custom-theme",
        type: "style",
        value: `
          .ikp-chat {
            width: min(95vw, 600px);
            border-radius: clamp(8px, 2vw, 16px);
            background: var(--ikp-color-background);
            @media (max-width: 768px) {
              width: 100vw;
              border-radius: 0;
            }
          }
        `,
      },
    ],
  },
};

You can see the Theme Customization guide for more information.

Custom Icons

Configure custom icons for various widget elements. You can use built-in icons from popular icon libraries or provide custom SVG URLs.

type InkeepCustomIcon =
  | {
      builtIn: AvailableBuiltInIcons;
    }
  | {
      custom: string; // url of svg or png of icon
    };
 
type CustomIconMap = {
  [K in keyof CustomIcons]?: InkeepCustomIcon;
};

Property	Type	Required	Description
`customIcons`	`CustomIconMap`	No	Custom icon configurations

const baseSettings: InkeepBaseSettings = {
  env: "production",
  apiKey: "YOUR_API_KEY",
  organizationDisplayName: "Enterprise Corp",
  primaryBrandColor: "#26D6FF",
  customIcons: {
    search: {
      builtIn: "LuBookOpen",
    },
    close: {
      custom: "https://assets.enterprise.com/icons/close.svg",
    },
    chat: {
      builtIn: "LuMessageSquare",
    },
  },
};

You can see the Custom Icons guide for more information.

URL Parameters

Configure URL parameters that will be automatically appended to all links within the widget. This is useful for tracking and maintaining context across page navigations.

type URLParametersConfig = {
  urlQueryParamsToAppend?: {
    [key: string]: string | number | boolean;
  };
};

Property	Type	Required	Description
`urlQueryParamsToAppend`	`object`	No	URL parameters to append to links

// Basic URL parameters configuration
const baseSettings: InkeepBaseSettings = {
  urlQueryParamsToAppend: {
    utm_source: "widget",
    user_id: "123",
  },
};
 
// Advanced URL parameters configuration
const enterpriseSettings: InkeepBaseSettings = {
  urlQueryParamsToAppend: {
    utm_source: window.location.hostname,
    utm_medium: "widget",
    user_id: getUserId(),
    team_id: getTeamId(),
    features: getEnabledFeatures().join(","),
    session: getSessionId(),
  },
};

Configure how source information is displayed in the widget by transforming the raw source data before it's rendered. This allows you to customize titles, URLs, descriptions, and other metadata for search results and chat references.

Type Signature

type TransformSource = (
  source: SourceItem,
  type: TransformSourceType,
  opts?: TransformSourceOptions
) => TransformedSource;
 
interface SourceItem {
  id?: string;
  title: string | undefined;
  url: string;
  description: string | undefined;
  breadcrumbs: string[];
  type: `${SourceItemType}`;
  contentType?: string;
  tag?: string;
  tabs?: (SourceTab | string)[];
}
 
interface TransformedSource {
  id?: string;
  title: string;
  url: string;
  description?: string;
  breadcrumbs?: string[];
  tabs?: (string | [string, { breadcrumbs: string[] }])[];
  icon: InkeepCustomIcon;
  shouldOpenInNewTab?: boolean;
  appendToUrl?: object;
  type: string;
  tag?: string;
}

Examples

Basic source transformation

This example sets the title of all sources to include the organization name, and uses the book icon for all sources.

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => ({
    ...source,
    title: `${source.title} - My Site`,
    icon: { builtIn: "LuBookOpen" },
  }),
};

Advanced source transformation

This example shows how to transform the source data based on whether the source is a search result or a chat source.

// Advanced source transformation
const enterpriseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type, opts) => {
    // Transform based on source type
    if (type === "searchResultItem") {
      return {
        ...source,
        title: `${opts?.organizationDisplayName} - ${source.title}`,
        description: source.description?.slice(0, 150) + "...",
        breadcrumbs: [...(source.breadcrumbs || []), "Documentation"],
        tabs: ["Docs", ["API", { breadcrumbs: ["API", "Reference"] }]],
        icon: { builtIn: "LuBookOpen" },
        shouldOpenInNewTab: true,
        appendToUrl: { source: type },
      };
    }
 
    // Different transformation for chat sources
    if (type === "chatSourceItem") {
      return {
        ...source,
        icon: { custom: "https://assets.example.com/chat-icon.svg" },
        shouldOpenInNewTab: false,
      };
    }
 
    return source;
  },
};

Add a documentation tab

Let's have a "Documentation" tab that shows the sources that come from your docs. Assuming you have other sources aside docs.

You'd first one to define a Documentation tab:

const searchSettings: InkeepSearchSettings = {
  // ...
  tabs: ["Documentation", ...otherTabs],
};

More info on tabs can be found in the Search and Chat guide.

Then you'd need to update the transformSource function to add qualifying sources to the Documentation tab:

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => {
    const tabs = source.tabs || [];
    // Do desired check here
    if (source.type === "documentation" || source.url.includes("mydocs.com")) {
      tabs.push("Documentation");
    }
    return {
      ...source,
      tabs,
    };
  },
};

Say you're in a Blog tab, and a blog post has a breadcrumb of Blog > Announcement > My Post. You may want to hide the Blog breadcrumb when the user is in the Blog tab.

Well when setting a tab for a source, you can also decide the breadcrumbs to show in that tab for that source.

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => ({
    ...source,
    tabs: [
      [
        "Blog",
        {
          breadcrumbs:
            source.breadcrumbs[0] === "Blog" ? source.breadcrumbs.slice(1) : source.breadcrumbs,
        },
      ],
      ...otherTabs,
    ],
  }),
};

The transformSource function allows you to modify how source information appears in different contexts:

Parameter	Type	Description
`source`	`SourceItem`	The original source data containing title, URL, description, etc.
`type`	`'chatSourceItem' \| 'searchResultItem' \| 'intelligentFormSource'`	Context where the source is being displayed
`opts`	`{ organizationDisplayName?: string; tabs?: (string \| SearchTab)[] }`	Additional options including organization name and configured tabs

The function should return a TransformedSource object that defines how the source should be displayed. This gives you control over:

Title and description formatting
URL modifications and parameters
Breadcrumb trails
Tab categorization
Icons and visual elements
Link behavior (new tab vs same window)
Additional metadata and tags

Common use cases include:

Adding organization branding to titles
Truncating long descriptions
Categorizing content into tabs
Adding tracking parameters to URLs
Customizing navigation behavior
Setting context-specific icons

Custom Filters

Configure how we filter the search and chat

export interface SearchAndChatFilters {
  attributes?: {
    [key: string]: any;
  };
}

Supported Operators

Comparison Operators: $eq, $ne, $gt, $gte, $lt, $lte
Array Operators: $in, $nin
Boolean Operators: $exists
Logical Operators: $and, $or

Filter by custom tags and attributes

A common filter scenario is you have docs that covers many products, versions, and SDKs.

The first part to setting up filters is to add <meta> tags prefixed with inkeep: to each page. For example:

<meta name="inkeep:version" content="latest" />
<meta name="inkeep:sdk" content="react" />

Then to filter the search and chat with your custom tags version and sdk:

const baseSettings: InkeepBaseSettings = {
  // ...
  filters: {
    attributes: {
      "$and": [{ version: { $in: ["latest"] } }, { sdk: { $in: ["react, "vue"] } }]
    }
  },
};

Filters can be dynamically generated based on the page the user is on, giving full control over the search and chat experience.