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

``bash
npm install @kingsimba/nc-ui


or

yarn add @kingsimba/nc-ui

or

pnpm add @kingsimba/nc-ui
`

Quick Start

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

function App() {
return (



)
}
`

$3

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

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

function MyComponent() {
return (



)
}
`

> 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.

$3

- 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

$3

`tsx
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 (


)
}

// 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')
`

$3

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

`tsx
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 (



)
}
`

Read the complete App Framework guide →

Theming

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

`css
: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

`bash


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.