Inkeep light logo
Schedule a callSee it for my content
Ui componentsMigrate to cxkit

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:

npm uninstall @inkeep/uikit
npm install @inkeep/cxkit-react 
yarn remove @inkeep/uikit
yarn add @inkeep/cxkit-react
pnpm remove @inkeep/uikit
pnpm add @inkeep/cxkit-react

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.

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-js to @inkeep/cxkit-jsInkeep AI API Overview

On this page

Overview
Installation
Breaking Changes
Package Import Changes
Base Settings Changes
Removed Properties
integrationId
organizationId
userType
remoteErrorLogsLevel
consoleDebugLevel
customCardSettings
breadcrumbRules
stringReplacementRules
Renamed Properties
userId
userEmail
userName
userToken
logEventCallback
chatApiProxyDomain
analyticsApiProxyDomain
appendQueryParamsToUrls
stylesheets
stylesheetUrls
Modified properties
env
AI Chat Settings Changes
Removed Properties
isControlledMessage
includeAIAnnotations
aiAnnotationPolicies
Renamed Properties
botName
botAvatarSrcUrl
botAvatarDarkSrcUrl
userAvatarSrcUrl
quickQuestions
exampleQuestionsLabel
shouldHighlightFirstQuickQuestion
disclaimerSettings
handleMessageChange
getHelpCallToActions
FormConfig type
isChatSharingEnabled
shouldShowCopyChatButton
actionButtonLabels
context
guidance
Search Settings Changes
Removed Properties
isControlledSearchQuery
Renamed Properties
prefilledQuery
handleSearchQueryChange
tabSettings
shouldShowAskAICard
maximumHitsLimit
debounceTime
Modal Settings Changes
Removed Properties
isShortcutKeyEnabled
isAlignedToTop
isAlignedToRight
onShortcutKeyPressed
Renamed Properties
openShortcutKey
askAILabel
switchToSearchMessage
isModeSwitchingEnabled
forceInitialDefaultView
Chat Button Changes
Removed Properties
chatButtonType
chatButtonBgColor
chatButtonBgColorDarkMode
isPositionFixed
fixedPositionXOffset
fixedPositionYOffset
Renamed Properties
chatButtonText
Custom Trigger Changes
Renamed Component
Moved Properties
isOpen
onOpen
onClose
API Keys
New Components