Nubisco UI

Vue 3 component library: clean, accessible, and themeable.

Table of Contents

• Nubisco UI
  • Table of Contents
  • Quick Start
    • Local Development Linking
    • Basic Usage
    • Vite Configuration
    • Importing Styles
    • Icon Support
  • Why Nubisco UI?
  • Features
  • Components
    • Layout
    • Form Controls
    • Data Display
  • Grid System
  • TypeScript Support
  • Documentation
  • Contributing
  • Security
  • Support this project
  • Acknowledgements
  • License

Quick Start

npm install @nubisco/ui
# or
pnpm add @nubisco/ui
# or
yarn add @nubisco/ui

Local Development Linking

To use an unreleased build locally, link it using pnpm's link: protocol:

# 1. Build the library
cd path/to/nubisco/ui && pnpm build

# 2. Reference it in your consumer's package.json
# "@nubisco/ui": "link:../path/to/nubisco/ui"

# 3. Install
pnpm install

After changing components in the library, run pnpm build again to pick up the changes.

Icon support: If your consumer project uses NbIcon directly (not via a pre-built dist import), add the icons Vite plugin to your config. If you're importing from the pre-built dist, this is not needed because icons are bundled.

Basic Usage

<script setup>
import { NbGrid, NbPanel, NbButton } from '@nubisco/ui'
import '@nubisco/ui/dist/ui.css'
</script>

<template>
  <NbGrid dir="col" gap="md">
    <NbPanel>
      <h1>Hello World</h1>
    </NbPanel>
    <NbButton>Click me</NbButton>
  </NbGrid>
</template>

Vite Configuration

Add the fonts plugin to load the bundled typefaces (Plus Jakarta Sans + Fira Code), and configure SCSS so design tokens are available across all your stylesheets:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fonts } from '@nubisco/ui/plugins/fonts'

export default defineConfig({
  plugins: [vue(), fonts()],
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use '@nubisco/ui/variables';`,
      },
    },
  },
})

Importing Styles

Option 1: Pre-built CSS (recommended for most projects):

import '@nubisco/ui/dist/ui.css'

Option 2: SCSS (recommended for full customization):

@use '@nubisco/ui/styles' as *;

Icon Support

Icons are bundled in the pre-built dist. If you import from source (not dist/ui.css), add the icons Vite plugin:

import { icons as iconsPlugin } from '@nubisco/ui/plugins/icons'

export default defineConfig({
  plugins: [vue(), fonts(), iconsPlugin(process.cwd())],
})

Note: Import the plugin from @nubisco/ui/plugins/icons — it contains Node.js-only code that cannot run in the browser.

Why Nubisco UI?

Most component libraries impose styling opinions that are hard to override. Nubisco UI follows a geometry-first approach where UI elements follow a grid and proportional spacing. Components are clean, accessible, and fully customisable through a comprehensive SCSS token system.

• Clean, flat design: purposeful defaults without visual gimmicks; easy to brand
• TypeScript-first: all props, events, and slots are fully typed and exported
• Tree-shakeable: ESM output with named exports; only pay for what you use

Features

• Dual build output: ES module and CommonJS bundles included
• SCSS source: full access to design tokens and variables for deep customization
• Responsive Grid: flexbox grid system with five configurable breakpoints
• Adaptive Icon System: SVG icons loaded via virtual module with zero runtime cost
• TypeScript: fully typed codebase with exported types and declaration maps

Components

Layout

| Component | Description | | :-------- | :-------------------------------------------------------- | | NbGrid | Responsive flexbox grid system with breakpoints | | NbPanel | Surface container with configurable background and border | | NbModal | Dialog overlay with focus trap and backdrop |

Form Controls

| Component | Description | | :-------------- | :--------------------------------------------------------------------------------- | | NbButton | Button with 5 variants (primary, secondary, ghost, danger, success), loading state | | NbTextInput | Text input with label and validation support | | NbNumberInput | Number input with stepper controls and min/max/step constraints | | NbSelect | Dropdown select with search, multiple selection, and virtual scroll | | NbCheckbox | Styled checkbox with label and indeterminate state | | NbRadio | Radio button group with vertical/horizontal layout | | NbSlider | Range slider with single value and range modes | | NbColorStrip | Color strip with single/multi-select |

Data Display

| Component | Description | | :----------- | :-------------------------------------------- | | NbBadge | Status badge/pill with 7 colour variants | | NbIcon | SVG icon component with virtual module loader | | NbJsonTree | Collapsible JSON tree viewer |

Grid System

The NbGrid component provides a flexbox-based layout system with named breakpoints:

| Name | Min-width | | :---- | :-------- | | sm | 320px | | md | 672px | | lg | 1056px | | xl | 1312px | | xxl | 1584px |

<NbGrid dir="row" gap="md" :grid="{ s: 12, m: 6 }">
  <NbGrid dir="col">Column 1</NbGrid>
  <NbGrid dir="col">Column 2</NbGrid>
</NbGrid>

TypeScript Support

All component props, events, and composable types are exported:

import type {
  NbGridProps,
  GridType,
  Breakpoint,
  GridColumns,
} from '@nubisco/ui'

Documentation

Full documentation is available at docs.nubisco.io/ui, including:

• Installation
• Components
• Grid System
• Contributor License Agreement (CLA)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, coding standards, and pull request guidelines.

All contributions require agreement to the Individual CLA: docs/CLA-INDIVIDUAL.md. By opening a pull request, you confirm your agreement under the terms in the pull request template.

Security

For security vulnerabilities, please see SECURITY.md for responsible disclosure procedures.

Support this project

If Nubisco UI is useful in your projects, consider sponsoring development. Maintaining components, design system decisions, and support takes significant time. GitHub Sponsors helps ensure long-term maintenance.

• ❤️ Sponsor via GitHub
• ⭐ Star the repository

Acknowledgements

Nubisco UI draws inspiration from IBM Carbon Design System for certain component interaction patterns and documentation structure. Carbon is the work of IBM and its contributors, licensed under Apache 2.0.

License

MIT