Theming

Theme system

Every InkUI component accepts an optional theme prop of type InkUITheme. By default, all components use darkTheme.

If you used npx @inkui-cli/inkui add, import from the shared _core.ts that was copied into your project:

import { darkTheme, lightTheme } from './components/ui/_core';
import { Spinner } from './components/ui/spinner';
 
// Default (dark)
<Spinner label="Loading..." />
 
// Light theme
<Spinner label="Loading..." theme={lightTheme} />

If you installed via npm (npm install @inkui-cli/spinner), import from the package:

import { darkTheme, lightTheme } from '@inkui-cli/core';

Theme shape

interface InkUITheme {
  colors: {
    primary: string;
    secondary: string;
    success: string;
    warning: string;
    error: string;
    info: string;
    muted: string;
    text: string;
    textInverse: string;
    border: string;
    focus: string;
    selection: string;
  };
  border: 'single' | 'double' | 'rounded' | 'bold' | 'ascii';
}

Built-in themes

InkUI ships two themes out of the box:

// Dark theme (default)
const darkTheme: InkUITheme = {
  colors: {
    primary: 'cyan',
    secondary: 'magenta',
    success: 'green',
    warning: 'yellow',
    error: 'red',
    info: 'blue',
    muted: 'gray',
    text: 'white',
    textInverse: 'black',
    border: 'gray',
    focus: 'cyan',
    selection: 'blue',
  },
  border: 'single',
};
 
// Light theme
const lightTheme: InkUITheme = {
  colors: {
    primary: 'blue',
    secondary: 'magenta',
    success: 'green',
    warning: 'yellow',
    error: 'red',
    info: 'cyan',
    muted: 'gray',
    text: 'black',
    textInverse: 'white',
    border: 'gray',
    focus: 'blue',
    selection: 'cyan',
  },
  border: 'rounded',
};

Custom theme

Create your own theme by spreading the defaults and overriding what you need:

import { darkTheme } from './components/ui/_core';
import type { InkUITheme } from './components/ui/_core';
 
export const myTheme: InkUITheme = {
  ...darkTheme,
  colors: {
    ...darkTheme.colors,
    primary: '#F472B6',   // pink instead of cyan
    border: '#3F3F46',
  },
  border: 'rounded',
};

Color values are passed directly to Ink's <Text color=""> — named colors (cyan, green), hex (#F472B6), or rgb(r,g,b). No chalk, no ANSI escape codes.

Global theme provider

For consistency across your whole CLI app, create a theme context:

import React, { createContext, useContext } from 'react';
import { darkTheme } from './components/ui/_core';
import type { InkUITheme } from './components/ui/_core';
 
const ThemeContext = createContext<InkUITheme>(darkTheme);
 
export function ThemeProvider({
  theme,
  children,
}: {
  theme: InkUITheme;
  children: React.ReactNode;
}) {
  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
}
 
export const useTheme = () => useContext(ThemeContext);

Visual theme builder

Run the interactive theme builder in your terminal to pick colors and export a ready-to-use theme file:

npx @inkui-cli/inkui theme

Border styles

The border token controls box-drawing characters across Table, Dialog, Panel, and other bordered components:

Value	Characters
`single`	`┌─┐│└┘`
`double`	`╔═╗║╚╝`
`rounded`	`╭─╮│╰╯`
`bold`	`┏━┓┃┗┛`
`ascii`	`+-+\|+-+`