Migrating from @inkeep/uikit to @inkeep/cxkit-react

This guide will help you migrate your application from using @inkeep/uikit to the new @inkeep/cxkit-react package. The new package includes several breaking changes but offers improved functionality and a more consistent API.

Overview

With version 0.5.x, we've renamed our package from @inkeep/uikit to @inkeep/cxkit-react to better reflect its purpose as a customer experience toolkit. This change comes with several API improvements and breaking changes that require updates to your code.

Installation

First, you'll need to update your package dependency:

Breaking Changes

Package Import Changes

Update your imports from:

import { InkeepChatButton } from "@inkeep/uikit";

To:

import { InkeepChatButton } from "@inkeep/cxkit-react";

Base Settings Changes

Several properties in the base settings have been removed or renamed:

Removed Properties

`integrationId`

The integrationId property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your integration.

// Old
baseSettings: {
  apiKey: "your-api-key",
  integrationId: "your-integration-id",
  // ...
}

// New
baseSettings: {
  apiKey: "your-api-key",
  // No integrationId needed
}

`organizationId`

The organizationId property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your organization.

// Old
baseSettings: {
  apiKey: "your-api-key",
  organizationId: "your-organization-id",
  // ...
}

// New
baseSettings: {
  apiKey: "your-api-key",
  // No organizationId needed
}

`userType`

The userType property has been removed in favor of the more flexible userProperties.cohorts array, which allows you to specify multiple user types or roles. See docs here for more details.

// Old
baseSettings: {
  userType: "admin",
  // ...
}

// New
baseSettings: {
  userProperties: {
    cohorts: ["admin", "engineering"],
    // ...
  },
  // ...
}

`remoteErrorLogsLevel`

The remoteErrorLogsLevel property has been removed as error logging is now handled internally with improved defaults.

`consoleDebugLevel`

The consoleDebugLevel property has been removed as debugging is now handled internally with improved defaults.

`customCardSettings`

The customCardSettings property has been removed in favor of the more powerful and flexible transformSource function, which allows for more comprehensive customization of search results and chat sources

// Old
baseSettings: {
  customCardSettings: {
    // Custom card settings
  },
  // ...
}

// New
baseSettings: {
  transformSource: (source) => {
    // Transform source data
    return {
      ...source,
      tabs: [] // Transform tabs
    };
  },
  // ...
}

See Source Transformation for more details.

`breadcrumbRules`

The breadcrumbRules property has been removed in favor of the more powerful and flexible transformSource function, which allows for more comprehensive customization of breadcrumbs.

// Old
baseSettings: {
  breadcrumbRules: [
    // Breadcrumb rules
  ],
  // ...
}

// New
baseSettings: {
  transformSource: (source) => {
    // Transform source data
    return {
      ...source,
      breadcrumbs: []
    };
  },
  // ...
}

See Source Transformation for more details.

`stringReplacementRules`

The stringReplacementRules property has been removed in favor of the more powerful and flexible transformSource function, which allows for more comprehensive string transformations.

// Old
baseSettings: {
  stringReplacementRules: [
    // String replacement rules
  ],
  // ...
}

// New
baseSettings: {
  transformSource: (source) => {
    // Transform source data
    return {
      ...source,
      breadcrumbs: []
    };
  },
  // ...
}

See Source Transformation for more details.

Renamed Properties

`userId`

`userEmail`

`userName`

User properties are now grouped under userProperties. See User Properties for more details.

// Old
baseSettings: {
  userId: "user-456",
  userEmail: "jane@enterprise.com",
  userName: "Jane Smith",
  // ...
}

// New
baseSettings: {
  userProperties: {
    id: "user-456",
    email: "jane@enterprise.com",
    name: "Jane Smith",
    cohorts: ["admin", "engineering"],
  },
  // ...
}

`userToken`

The userToken property has been renamed to userAuthToken to better reflect its purpose as an authentication token for the user. See User Properties for more details:

// Old
baseSettings: {
  userToken: "jwt-token-for-user-authentication",
  // ...
}

// New
baseSettings: {
  userAuthToken: "jwt-token-for-user-authentication",
  // ...
}

`logEventCallback`

The logEventCallback property has been renamed to onEvent with an updated event structure for more consistent event handling. See Event Handling for more details:

// Old
baseSettings: {
  logEventCallback: (event) => {
    // Handle event
    console.log(event);
  },
  // ...
}

// New
baseSettings: {
  onEvent: (event) => {
    // Handle event
    console.log(event);
  },
  // ...
}

`chatApiProxyDomain`

The chatApiProxyDomain property has been renamed to aiApiBaseUrl to better reflect its purpose as an API endpoint for AI chat functionality. See Event Handling for more details:

// Old
baseSettings: {
  chatApiProxyDomain: "https://api.inkeep.com/chat",
  // ...
}

// New
baseSettings: {
  aiApiBaseUrl: "https://api.inkeep.com/chat",
  // ...
}

`analyticsApiProxyDomain`

The analyticsApiProxyDomain property has been renamed to analyticsApiBaseUrl to better reflect its purpose as an API endpoint for analytics functionality. See Core Settings for more details:

// Old
baseSettings: {
  analyticsApiProxyDomain: "https://api.example.com/analytics",
  // ...
}

// New
baseSettings: {
  analyticsApiBaseUrl: "https://api.example.com/analytics",
  // ...
}

`appendQueryParamsToUrls`

The appendQueryParamsToUrls property has been renamed to urlQueryParamsToAppend for clarity. See URL Parameters for more details:

// Old
baseSettings: {
  appendQueryParamsToUrls: { utm_source: "docs" },
  // ...
}

// New
baseSettings: {
  urlQueryParamsToAppend: { utm_source: "docs" },
  // ...
}

`stylesheets`

`stylesheetUrls`

Stylesheet properties have been consolidated under a single styles property. Style strings can be passed directly. See Theme Configuration for more details:

// Old
baseSettings: {
  stylesheets: ["custom-styles.css"],
  stylesheetUrls: ["https://example.com/styles.css"],
  // ...
}

// New
baseSettings: {
  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-ai-chat-message {
            border-radius: 8px;
            padding: 12px;
          }
          [data-theme='dark'] .ikp-ai-chat-message {
            background: #2D3748;
          }
        `,
      },
    ],
  // ...
}

Modified properties

`env`

env options are now lowercase: "development" | "production"

// Old
baseSettings: {
  env: "DEVELOPMENT",
  // ...
}

// New
baseSettings: {
  env: "development",
  // ...
}

AI Chat Settings Changes

Removed Properties

`isControlledMessage`

The isControlledMessage property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the defaultMessage prop for uncontrolled behavior or the message and onInputMessageChange props for controlled behavior.

`includeAIAnnotations`

The includeAIAnnotations property has been removed as annotations are now handled internally with improved defaults. Equivalent functionality will be available in a future release.

`aiAnnotationPolicies`

The aiAnnotationPolicies property has been removed as annotation policies are now handled internally with improved defaults. Equivalent functionality will be available in a future release.

Renamed Properties

`botName`

`botAvatarSrcUrl`

`botAvatarDarkSrcUrl`

botName → aiAssistantName
botAvatarSrcUrl → aiAssistantAvatar

botAvatarDarkSrcUrl → can be configured by changing aiAssistantAvatar to an object:

// Old
aiChatSettings: {
  botAvatarSrcUrl: "/assets/assistant.png",
  botAvatarDarkSrcUrl: "/assets/assistant-dark.png",
  // ...
}

// New
aiChatSettings: {
  aiAssistantAvatar: {
    light: "/assets/assistant-light.png",
    dark: "/assets/assistant-dark.png"
  },
  // ...
}

`userAvatarSrcUrl`

userAvatarSrcUrl → userAvatar

// Old
aiChatSettings: {
  userAvatarSrcUrl: userProfile.avatarUrl,
  // ...
}

// New
aiChatSettings: {
  userAvatar: userProfile.avatarUrl,
  // ...
}

`quickQuestions`

quickQuestions is now exampleQuestions for improved clarity:

// Old
baseSettings: {
  quickQuestions: ["What is the capital of France?", "What is the capital of Germany?"],
  // ...
}

// New
baseSettings: {
  exampleQuestions: ["What is the capital of France?", "What is the capital of Germany?"],
  // ...
}

`exampleQuestionsLabel`

exampleQuestionsLabel is now exampleQuestionsTitle for improved clarity:

// Old
baseSettings: {
  exampleQuestionsLabel: "Example Questions",
  // ...
}

// New
baseSettings: {
  exampleQuestionsTitle: "Example Questions",
  // ...
}

`shouldHighlightFirstQuickQuestion`

shouldHighlightFirstQuickQuestion is now isFirstExampleQuestionHighlighted for improved clarity:

// Old
baseSettings: {
  shouldHighlightFirstQuickQuestion: true,
  // ...
}

// New
baseSettings: {
  isFirstExampleQuestionHighlighted: true,
  // ...
}

`disclaimerSettings`

isDisclaimerEnabled is now isEnabled and disclaimerLabel is now label and disclaimerTooltip is now tooltip within the AIChatDisclaimerSettings type.

// Old
import {
  type InkeepAIChatSettings,
  type AIChatDisclaimerSettings,
} from "@inkeep/uikit";

const aiChatDisclaimerSettings: AIChatDisclaimerSettings = {
  isDisclaimerEnabled: true,
  disclaimerLabel: "Usage policy",
  disclaimerTooltip:
    "Information provided by {{botName || 'this AI assistant'}} is not guaranteed to be accurate or comprehensive. Please consult {{organizationDisplayName}}'s terms of service and privacy policy for details on how information is used.",
};

const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  disclaimerSettings: aiChatDisclaimerSettings,
};

// New
import {
  type InkeepAIChatSettings,
  type AIChatDisclaimerSettings,
} from "@inkeep/cxkit-react";

const aiChatDisclaimerSettings: AIChatDisclaimerSettings = {
  isEnabled: true,
  label: "Usage policy",
  tooltip:
    "Information provided by {{botName || 'this AI assistant'}} is not guaranteed to be accurate or comprehensive. Please consult {{organizationDisplayName}}'s terms of service and privacy policy for details on how information is used.",
};

const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  disclaimerSettings: aiChatDisclaimerSettings,

`handleMessageChange`

handleMessageChange is now onInputMessageChange for improved clarity:

// Old
baseSettings: {
  handleMessageChange: (message) => {
    // Handle message change
    console.log(message);
  },
  // ...
}

// New
baseSettings: {
  onInputMessageChange: (message) => {
    // Handle message change
    console.log(message);
  },
  // ...
}

`getHelpCallToActions`

getHelpCallToActions is now getHelpOptions for improved clarity:

// Old
baseSettings: {
  getHelpCallToActions: () => {
    // Get help call to actions
    return [
      {
        icon: { builtIn: 'FaDiscord' },
        name: 'Discord',
        url: 'https://inkeep.com/',
      },
    ];
  },
  // ...
}

// New
baseSettings: {
  getHelpOptions: () => {
    // Get help options
    return [
      {
        name: 'Discord',
        icon: {
          builtIn: 'FaDiscord',
        },
        action: {
          type: 'open_link',
          url: 'https://inkeep.com/',
        },
      },
    ];
  },
  // ...
}

`FormConfig` type

FormConfig type is now AIChatFormSettings for improved clarity and the configuration has changed. See here for more details: AIChatFormSettings

`isChatSharingEnabled`

The isChatSharingEnabled property has been renamed to isShareButtonVisible for improved clarity:

// Old
aiChatSettings: {
  isChatSharingEnabled: true,
  // ...
}

// New
aiChatSettings: {
  isShareButtonVisible: true,
  // ...
}

`shouldShowCopyChatButton`

The shouldShowCopyChatButton property has been renamed to isCopyChatButtonVisible for improved clarity and consistency with other visibility properties:

// Old
aiChatSettings: {
  shouldShowCopyChatButton: true,
  // ...
}

// New
aiChatSettings: {
  isCopyChatButtonVisible: true,
  // ...
}

`actionButtonLabels`

The actionButtonLabels property has been renamed to toolbarButtonLabels to better reflect its purpose for configuring toolbar button text:

// Old
aiChatSettings: {
  actionButtonLabels: {
    copy: "Copy Chat",
    share: "Share Chat",
    // ...
  },
  // ...
}

// New
aiChatSettings: {
  toolbarButtonLabels: {
    copy: "Copy Chat",
    share: "Share Chat",
    // ...
  },
  // ...
}

`context`

`guidance`

The context and guidance properties have been consolidated under the more flexible prompts property. The new prompts is an array of strings.

// Old
aiChatSettings: {
  context: "The user is new to the product.",
  guidance: "Be concise.",
  // ...
}

// New
aiChatSettings: {
  prompts: [
    "The user is new to the product.",
    "Be concise."
  ],
  // ...
}

Search Settings Changes

Removed Properties

`isControlledSearchQuery`

The isControlledSearchQuery property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the defaultQuery prop for uncontrolled behavior or the query and onQueryChange props for controlled behavior.

Renamed Properties

`prefilledQuery`

The prefilledQuery property has been renamed to defaultQuery for improved clarity and consistency with React patterns:

// Old
searchSettings: {
  prefilledQuery: "How to get started",
  // ...
}

// New
searchSettings: {
  defaultQuery: "How to get started",
  // ...
}

`handleSearchQueryChange`

The handleSearchQueryChange property has been renamed to onQueryChange for improved clarity and consistency with React event handler naming conventions:

// Old
searchSettings: {
  handleSearchQueryChange: (query) => {
    // Handle query change
    console.log(query);
  },
  // ...
}

// New
searchSettings: {
  onQueryChange: (query) => {
    // Handle query change
    console.log(query);
  },
  // ...
}

`tabSettings`

The tabSettings property has been renamed to tabs for improved clarity and simplicity. tabs definitions have been updated as well. See docs here for more details.

// Old
searchSettings: {
  tabSettings: {
      isAllTabEnabled: true,
      rootBreadcrumbsToUseAsTabs: ['Docs'],
      tabOrderByLabel: ['Resources', 'Blog', 'Solutions'],
      disabledDefaultTabs: undefined, // string[] | undefined
      alwaysDisplayedTabs: ['Blog'],
    },
  // ...
}

// New

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: [],
  // ...
};

`shouldShowAskAICard`

The shouldShowAskAICard property has been elevated to a top-level property:

// Old
searchSettings: {
  shouldShowAskAICard: true,
  // ...
}

// New
shouldShowAskAICard: true, // Now a top-level property

`maximumHitsLimit`

The maximumHitsLimit property has been renamed to maxResults for improved clarity and simplicity:

// Old
searchSettings: {
  maximumHitsLimit: 10,
  // ...
}

// New
searchSettings: {
  maxResults: 10,
  // ...
}

`debounceTime`

The debounceTime property has been renamed to debounceTimeMs for improved clarity on the unit of time:

// Old
searchSettings: {
  debounceTime: 500,
  // ...
}

// New
searchSettings: {
  debounceTimeMs: 500,
  // ...
}

Removed Properties

`isShortcutKeyEnabled`

The isShortcutKeyEnabled property has been removed. To disable the shortcut key, pass shortcutKey as null.

// Old
modalSettings: {
  isShortcutKeyEnabled: false,
  // ...
}

// New
modalSettings: {
  shortcutKey: null, // Disables the shortcut key
  // ...
}

`isAlignedToTop`

The isAlignedToTop property has been removed as modal positioning is now handled through CSS.

`isAlignedToRight`

The isAlignedToRight property has been removed as modal positioning is now handled through CSS.

`onShortcutKeyPressed`

The onShortcutKeyPressed property has been removed as shortcut key handling is now managed internally.

Renamed Properties

`openShortcutKey`

The openShortcutKey property has been renamed to shortcutKey for improved clarity. It has a default value of k:

// Old
modalSettings: {
  openShortcutKey: "k",
  // ...
}

// New
modalSettings: {
  shortcutKey: "k",
  // ...
}

`askAILabel`

The askAILabel property has been moved to be a top-level prop:

// Old
modalSettings: {
  askAILabel: "Ask AI",
  // ...
}

// New
askAILabel: "Ask AI", // Now a top-level prop

`switchToSearchMessage`

The switchToSearchMessage property has been renamed to searchLabel and moved to be a top-level prop:

// Old
modalSettings: {
  switchToSearchMessage: "Search Documentation",
  // ...
}

// New
searchLabel: "Search Documentation", // Now a top-level prop

`isModeSwitchingEnabled`

The isModeSwitchingEnabled property has been renamed to canToggleView and moved to be a top-level prop:

// Old
modalSettings: {
  isModeSwitchingEnabled: true,
  // ...
}

// New
canToggleView: true, // Now a top-level prop

`forceInitialDefaultView`

The forceInitialDefaultView property has been renamed to forceDefaultView and moved to be a top-level prop:

// Old
modalSettings: {
  forceInitialDefaultView: "search",
  // ...
}

// New
forceDefaultView: "search", // Now a top-level prop

Chat Button Changes

Removed Properties

`chatButtonType`

The chatButtonType property has been removed as button styling is now handled through CSS.

`chatButtonBgColor`

The chatButtonBgColor property has been removed. You can change the background color via CSS using the .ikp-chat-button__button class:

.ikp-chat-button__button {
  background-color: #4a5568;
}

`chatButtonBgColorDarkMode`

The chatButtonBgColorDarkMode property has been removed. You can change the background color for dark mode via CSS using the [data-theme='dark'] .ikp-chat-button__button selector:

[data-theme="dark"] .ikp-chat-button__button {
  background-color: #2d3748;
}

`isPositionFixed`

The isPositionFixed property has been removed. You can change the positioning via CSS by setting position: relative; on the .ikp-chat-button__container class:

.ikp-chat-button__container {
  position: relative;
}

`fixedPositionXOffset`

The fixedPositionXOffset property has been removed. You can change the horizontal positioning via CSS by setting right: 0; on the .ikp-chat-button__container class:

.ikp-chat-button__container {
  right: 0;
}

`fixedPositionYOffset`

The fixedPositionYOffset property has been removed. You can change the vertical positioning via CSS by setting bottom: 0; on the .ikp-chat-button__container class:

.ikp-chat-button__container {
  bottom: 0;
}

Renamed Properties

`chatButtonText`

The chatButtonText property has been renamed to label for improved clarity and consistency:

// Old
chatButtonSettings: {
  chatButtonText: "Chat with AI",
  // ...
}

// New
chatButtonSettings: {
  label: "Chat with AI",
  // ...
}

Custom Trigger Changes

Renamed Component

The CustomTrigger component has been renamed to provide more specific functionality:

ModalSearchAndChat - For both search and chat functionality
ModalSearch - For just search functionality
ModalChat - For just chat functionality

See here for more details.

Moved Properties

`isOpen`

The isOpen property has been moved inside modalSettings:

// Old
<InkeepCustomTrigger
  isOpen={isOpen}
  // ...
/>

// New
<InkeepModalSearchAndChat
  modalSettings={{
    isOpen: isOpen,
    // ...
  }}
  // ...
/>

`onOpen`

The onOpen property has been renamed to onOpenChange and moved inside modalSettings:

// Old
<InkeepCustomTrigger
  onOpen={handleOpen}
  // ...
/>

// New
<InkeepModalSearchAndChat
  modalSettings={{
    onOpenChange: handleOpenChange,
    // ...
  }}
  // ...
/>

`onClose`

The onClose property has been removed. You can now utilize onOpenChange (moved inside modalSettings) to handle both open and close events:

// Old
<InkeepCustomTrigger
  onClose={handleClose}
  // ...
/>

// New
<InkeepModalSearchAndChat
  modalSettings={{
    onOpenChange: (isOpen) => {
      if (!isOpen) {
        // Handle close
      }
    },
    // ...
  }}
  // ...
/>

API Keys

Production API keys for web integrations are now required to have Enforce referrer URL enabled for additional security. See here for details. API keys without this setting will be severely rate limited.

New Components

Intelligent Form Component: See here for details.
Embedded Search Component: See here for details.
Embedded Search and Chat Component: See here for details.

Migrating from @inkeep/uikit to @inkeep/cxkit-react

On this page