nc-ui

A high-performance, lightweight React UI component library and extensible application framework.

• 🤖 AI-Optimized: Comprehensive AI reference guide included
• 🚀 Small Footprint: Only ~75KB bundle size.
• 🏗️ Application Framework: Features a flexible, extensible framework for building windowed apps, with app-specific i18n
• 📱 Cross-Platform: Optimized for both desktop and mobile experiences.

Published on npm as @kingsimba/nc-ui

View Demo

Installation

npm install @kingsimba/nc-ui
# or
yarn add @kingsimba/nc-ui
# or
pnpm add @kingsimba/nc-ui

Quick Start

import { Button, ActivityIndicator } from '@kingsimba/nc-ui'
import '@kingsimba/nc-ui/styles.css'

function App() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Button variant="danger" size="small">Delete</Button>
      <Button loading>Saving...</Button>
      <ActivityIndicator size="large" />
    </div>
  )
}

Using Icons

Icons are imported from a separate entry point to keep the main bundle size small:

import { CloseIcon, EditIcon, TrashIcon } from '@kingsimba/nc-ui/icons'

function MyComponent() {
  return (
    <div>
      <CloseIcon size={24} />
      <EditIcon size={20} color="#3b82f6" />
      <TrashIcon size={18} />
    </div>
  )
}

See the live demo for interactive examples and complete API documentation for all components.

Components

nc-ui provides 23+ ready-to-use components. Click any component to see it in the interactive demo:

| Component | Description | |-----------|-------------| | ActivityIndicator | Loading spinner with size variants and overlay mode | | Alert | Dismissible notification banners with status variants | | AppDialog | Render any registered app inside a dialog overlay | | Battery | Visual battery level indicator | | Button | Primary action button with variants, sizes, and loading states | | ButtonGroup | Group related buttons with automatic styling | | Checkbox | Toggle selection with indeterminate state support | | CommonButtons | Pre-configured buttons (Close, Edit, Refresh, Trash) | | ComboBox | Searchable dropdown with autocomplete | | ContextMenu | Right-click menu with customizable items | | Dialog | Modal dialogs with header, footer, and action buttons | | Hyperlink | Styled anchor/link component | | Icons | 50+ SVG icons (separate import path) | | Input | Text input with validation states and prefix/suffix support | | ListGroup | Styled list items with selection and actions | | MonthRangePicker | Month range selector with validation (YY-M(M) or YYYY-M(M) format) | | MultiSelect | Multi-selection dropdown with tag display | | NavStack | Stack-based navigation for mobile-style settings UIs | | Notification | Toast-style notifications with auto-dismiss and stacking | | NumberInput | Numeric input with increment/decrement controls | | Slider | Range slider with value display | | Tabs | Tabbed navigation component | | Toggle | Switch/toggle with on/off states | | YamlTextArea | YAML editor with syntax highlighting and validation |

App Framework

nc-ui includes a complete framework for building panel-based applications that run in a right-side panel. Apps can have their own state management, isolated i18n translations, and integrate seamlessly with the container.

Key Features

• Panel Management: Apps run in a responsive panel (inline on desktop, overlay on mobile)
• Lifecycle Control: Launch, background, and close apps programmatically
• Isolated i18n: Each app can have its own translations using createAppI18nFactory
• Title Bar API: Control navigation, title, toolbar via useApp() hook
• Code Splitting: Lazy-load apps for optimal performance

Quick Example

import React from 'react'
import { appRegistry, runningAppsStore, useApp } from '@kingsimba/nc-ui'
import { MyAppIcon } from './MyAppIcon'

// 1. Create your app component
function MyApp() {
  const { setTitle, close } = useApp()
  
  return (
    <div>
      <h1>My App</h1>
      <button onClick={close}>Close</button>
    </div>
  )
}

// 2. Register the app (with lazy loading)
const LazyMyApp = React.lazy(() => 
  import('./MyApp').then(m => ({ default: m.MyApp }))
)

appRegistry.register({
  id: 'my-app',
  titleKey: 'apps.myApp.name',
  icon: MyAppIcon,
  component: LazyMyApp,
  width: 400,
})

// 3. Launch the app
await runningAppsStore.launchApp('my-app')

App-Specific i18n

Each app can have isolated translations that won't conflict with other apps:

import { createAppI18nFactory } from '@kingsimba/nc-ui'
import { I18nextProvider } from 'react-i18next'

const myAppI18n = createAppI18nFactory({
  en: { title: 'My App', save: 'Save' },
  zh: { title: '我的应用', save: '保存' },
})

export function MyApp() {
  return (
    <I18nextProvider i18n={myAppI18n}>
      <MyAppContent />
    </I18nextProvider>
  )
}

Read the complete App Framework guide →

Theming

The library uses CSS variables with nc- prefix. Override them in your app:

:root {
  --nc-primary: #your-brand-color;
  --nc-danger: #your-danger-color;
  /* ... see theme.css for all variables */
}

/* Light theme - add .light class to :root */
:root.light {
  --nc-primary: #your-light-primary;
}

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Run linting
npm run lint

Adding Components

1. Create your component in src/components/
2. Add styles to src/styles/theme.css with nc- prefix
3. Export it from src/index.ts

Project Structure

src/
├── components/          # UI components
│   ├── Button.tsx
│   └── ActivityIndicator.tsx
├── styles/
│   └── theme.css        # All component styles with nc- prefix
├── lib/
│   └── utils.ts         # Utility functions (cn helper)
└── index.ts             # Main entry - exports all components

CSS Naming Convention

All CSS classes and variables use nc- prefix to avoid conflicts:

• Variables: --nc-primary, --nc-button-bg, etc.
• Classes: .nc-button, .nc-activity-indicator, etc.
• Modifiers: .nc-primary, .nc-small, .nc-loading, etc.