Ui componentsCommon settings

Base

Review the basic configuration settings for our widgets.

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:

OptionTypeRequiredDescription
env'production' | 'development'NoEnvironment setting (defaults to 'production')
apiKeystringYesYour Inkeep API key
organizationDisplayNamestringNoDisplay name for your organization
primaryBrandColorstringYesPrimary brand color (hex code)
aiApiBaseUrlstringNoCustom base URL for API endpoints
analyticsApiBaseUrlstringNoCustom base URL for analytics endpoints
shadowHostHTMLElement | nullNoReference to shadow DOM host element
rootElementHTMLElement | nullNoReference to root mounting element
shouldBypassCaptchabooleanNoBypass captcha challenge (server-side API only)
tagsstring[]NoCustom tags for widget identification
prismPrismNoInstance 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[];
}
PropertyTypeRequiredDescription
userPropertiesUserPropertiesNoUser identification and metadata
userAuthTokenstringNoAuthentication 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;
}
PropertyTypeRequiredDescription
privacyPreferencesPrivacyPreferencesNoPrivacy 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;
  };
};
PropertyTypeRequiredDescription
onEvent(event: InkeepCallbackEvent) => voidNoEvent 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;
  };
}
PropertyTypeRequiredDescription
colorModeColorModeNoTheme 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;
  }>;
}
PropertyTypeRequiredDescription
themeUserThemeNoTheme 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;
};
PropertyTypeRequiredDescription
customIconsCustomIconMapNoCustom 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;
  };
};
PropertyTypeRequiredDescription
urlQueryParamsToAppendobjectNoURL 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(),
  },
};

Source Transformation

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
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => ({
    ...source,
    title: `${source.title} - My Site`,
    icon: { builtIn: "LuBookOpen" },
  }),
};
 
// 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;
  },
};

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

ParameterTypeDescription
sourceSourceItemThe 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.

On this page