Kortix UI

@kortix/ui: the Kortix React components and the session chat, themed by CSS variables, for your own app.

@kortix/ui is the React component library that the Kortix web app renders. The same package serves Kortix Apps, white-label hosts and your own app, so a button, a modal or a chat thread looks and behaves the same everywhere. Components are Tailwind CSS v4 class strings that read CSS variables. You re-theme them by overriding the variables, never by copying a component.

Install

react and react-dom 18 or later are peer dependencies. Install the rest by what you use:

After the first npm release:

npm i @kortix/ui @kortix/sdk @tanstack/react-query

Add the styles

Load the styles once, in your app’s main stylesheet or entry file. Pick the row for your host.

@import 'tailwindcss';
@import '@kortix/ui/tailwind.css';

@import 'tailwindcss';
@import 'tw-animate-css';
@import '@kortix/ui/tokens.css'; /* optional: or set every variable yourself */
@import '@kortix/ui/theme.css';
@plugin 'tailwind-scrollbar';
@plugin 'tailwind-scrollbar-hide';

import '@kortix/ui/styles.css';

• Dark mode is the dark class on <html>. Add or remove it to switch themes. useIsDark() returns the current state.
• Both paths style the page itself: body paints --background and --foreground, borders default to --border, native controls follow the theme (color-scheme), text selection reads --selection, and interactive elements show the pointer cursor. You add no base rules of your own.
• @kortix/ui/fonts.css loads the Roobert font, for Kortix-owned surfaces only. Every other host renders the system font stack (--font-sans-system).

Mount the providers

Mount these once, at the root of your app:

import { UiProvider, type UiLinkComponent } from '@kortix/ui';
import { IconProvider } from '@kortix/ui/icon-provider';
import { Toaster } from '@kortix/ui/toast';
import { Link } from 'react-router-dom';

// Any router: `UiProvider` passes anchor props with `href`.
const RouterLink: UiLinkComponent = ({ href = '', ...props }) => <Link to={href} {...props} />;

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <UiProvider strings={{ confirm: 'Confirm', cancel: 'Cancel' }} link={RouterLink}>
      <IconProvider>
        {children}
        <Toaster />
      </IconProvider>
    </UiProvider>
  );
}

Theme it for your brand

Every color, radius and font is a CSS variable from tokens.css. To white-label, override the variables after the import, in your own :root for light and .dark for dark. These variables carry the brand:

:root {
  --kortix-blue: oklch(0.585 0.22 277);
  --ring: oklch(0.585 0.22 277);
  --radius: 0.5rem;
  --font-sans-system: 'Inter', ui-sans-serif, sans-serif;
}
.dark {
  --kortix-blue: oklch(0.62 0.2 277);
  --ring: oklch(0.62 0.2 277);
}

After this override, a checked Switch and the brand Button render indigo, and focus rings follow. The default Button stays ink until you change --foreground and --background. The white-label demo (apps/whitelabel-demo/src/app/globals.css) is the reference.

A host without Tailwind can also skip tokens.css and set every variable itself. The rules:

• Override variables. Never fork or restyle a component: a forked copy stops receiving fixes.
• Pass your logo through UiProvider useBrand, so KortixLogo renders your marks.
• Do not load fonts.css. Set your font in --font-sans-system.

Components

Each component is one subpath, @kortix/ui/<file>. The live catalog at kortix.com/design-system renders every one in light and dark, with its usage rules.

Compose before you create. Use Modal for a dialog, Hint for a tooltip, Loading for a spinner, Badge for a chip and ConfirmDialog before a destructive action. Never call sonner’s toast() directly, and never use an icon with animate-spin as a spinner. Icons come from @phosphor-icons/react.

Add a chat

SessionThread renders the whole chat of one session from one useSession result: the transcript, the streaming turn, tool calls, the runtime state, permission and question prompts, the typed send error, and the composer with slash commands, the model and agent pickers and Stop.

import { useSession } from '@kortix/sdk/react';
import { SessionThread } from '@kortix/ui/chat';
import { errorToast } from '@kortix/ui/toast';

export function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const session = useSession(projectId, sessionId);
  return (
    <div className="h-dvh">
      <SessionThread session={session} onError={(message) => errorToast(message)} />
    </div>
  );
}

The parent sets the height, and the thread fills it. Everything reads off session: there is no second chat hook and no transport to write.

The thread follows the transcript rules of the Kortix web app. When a provider error interrupts a turn, the harness resumes it with its own [auto-recovery] prompt: the thread shows no bubble for that prompt and no error row for the failure it continued. If the chain still ends in failure, one error row shows, with how many automatic retries ran. The composer shows the / for commands hint only when the session has a command. In the model picker, ArrowUp and ArrowDown move the highlight and Enter picks it.

For a layout of your own, compose the parts from the same useSession result: MessageList, MessageView, Composer, PermissionPrompt, QuestionPrompt, ModelPicker and AgentPicker, all from @kortix/ui/chat. Markdown renders a streaming message and holds back half-written code fences and tables, so the text does not flicker.

Render the transcript yourself

To draw every part with your own components, skip @kortix/ui/chat and use the headless kit in @kortix/sdk/react: useChatTurns and renderParts. renderParts requires one renderer per part kind, so a new kind fails your build, not your UI. See Build a chat UI.

For agents

The package ships a skill at packages/ui/skills/kortix-ui/SKILL.md, and every Kortix session loads it as the kortix-ui skill. It tells an agent how to set up the package, which component to compose, which primitives are banned, and how to verify a page. Point your own coding agent at it before it writes UI with @kortix/ui.

Next steps