nergous-ui-vue

nergous-ui-vue — Vue 3

Token-driven component library for the nergous-ui-vue design system. Light/dark themes, three density levels, keyboard and accessibility support. Zero runtime dependencies beyond Vue 3.

The package includes components, composables, formatting helpers, design tokens and bundled fonts. Its entry point imports the token stylesheet automatically.

Preview

Actual Chromium screenshots of the included examples, using bundled fonts and local demo data. Click an image to inspect it at full size.

Admin shell — sidebar, member table, badges, search and pagination

Light theme	Dark theme

Buttons, inputs, selection controls, avatars, alerts, tabs and the form wizard. Screenshots are hosted in the repository and are not included in the npm archive.

Requirements

• Vue 3 (^3.5) — the only peer dependency.
• A bundler that understands .vue single-file components and .css imports (Vite, Rollup, webpack, …). Vite is the reference setup.

Install as a versioned source package

The package ships Vue SFC source, CSS, fonts and TypeScript declarations; a generated bundle is not required. Consumers need Vue 3.5+ and a Vue bundler plugin. Application routing, data access, authentication and backend integration stay in the consuming application.

For a local/unpublished release, run npm pack --ignore-scripts here and install the resulting archive with npm install /path/to/package.tgz in each consumer. After a registry release, install the package and commit the consumer lockfile:

npm install nergous-ui-vue

No automatic publishing is configured; packing is not publishing.

import { NButton, NModal, useTheme } from "nergous-ui-vue";
// The entry imports tokens. An explicit stylesheet import is also available:
import "nergous-ui-vue/styles";

See API contracts, migration, and development/release checks. index.d.ts documents all public components, props, events, scoped slots, composables and formatter return values. TypeScript-aware editors show these TSDoc descriptions on hover and during completion.

Usage

Use named imports from the barrel only — global registration via app.use() is intentionally not supported (named imports give editor autocomplete and make a page's real dependencies visible).

<script setup>
import { NButton, NBadge, useToast } from "nergous-ui-vue";

const toast = useToast();
</script>

The entry imports styles automatically. To load only the stylesheet, use import "nergous-ui-vue/styles".

Themes and density

<script setup>
import { useTheme } from "nergous-ui-vue";

const { theme, density, toggle, setTheme, setDensity } = useTheme();
// theme   → ref("light" | "dark")
// density → ref("compact" | "comfortable" | "spacious")
</script>

<template>
  <button @click="toggle">Toggle theme</button>
  <button @click="setDensity('compact')">Compact</button>
</template>

useTheme sets data-theme and data-density on <html> and persists both to localStorage. Every color and spacing value comes from CSS variables, so theming and density apply automatically to your own components when you use the tokens. State is a module-level singleton, so every useTheme() caller shares the same reactive theme/density.

Density has three levels — compact, comfortable (default) and spacious — selected via [data-density="…"] rules in tokens.css.

Anti-flash on first paint (optional)

To avoid a flash of the wrong theme before your JS runs, set the data-theme/data-density attributes on <html> from an inline script in your HTML head, reading the same localStorage keys useTheme uses. Those keys are exported so you don't hardcode them:

import { THEME_STORAGE_KEY, DENSITY_STORAGE_KEY } from "nergous-ui-vue";
// THEME_STORAGE_KEY   === "nergous-ui-vue-theme"
// DENSITY_STORAGE_KEY === "nergous-ui-vue-density"

<script>
    var root = document.documentElement;
    var theme = "light";
    var density = "comfortable";
    try {
        theme = localStorage.getItem("nergous-ui-vue-theme") ?? theme;
        density = localStorage.getItem("nergous-ui-vue-density") ?? density;
    } catch (_) {
        // Storage can be unavailable.
    }
    root.dataset.theme = ["light", "dark"].includes(theme) ? theme : "light";
    root.dataset.density = ["compact", "comfortable", "spacious"].includes(density)
        ? density
        : "comfortable";
</script>

Toasts

Render <NToaster /> once near the app root, then push messages from anywhere:

<script setup>
import { NToaster, useToast } from "nergous-ui-vue";

const toast = useToast();
</script>

<template>
  <NToaster />
  <button @click="toast.success('Saved', 'Profile updated')">OK</button>
  <button @click="toast.error('Error', 'Could not save')">Fail</button>
</template>

useToast() returns the reactive toasts list plus:

• success(title, msg) / error(title, msg) / warning(title, msg) / info(title, msg) — tone shortcuts.
• push(opts) — opts is a string (title only) or { tone, title, msg, duration }; returns the new toast's id.
• dismiss(id) — remove a toast early.

Auto-dismiss timing depends on tone: errors linger longest (7 s), warnings 5 s, ok/info 3.6 s, unless you pass an explicit duration (0 disables auto-dismiss). Timers pause while the pointer or focus is inside the toaster, so messages don't vanish mid-read (WCAG 2.2.1).

Formatting

createFormat(locale) builds locale-bound formatters on top of plain Intl — no hardcoded language; the host app passes the active BCP-47 locale:

<script setup>
import { createFormat } from "nergous-ui-vue";

const { formatDateTime, formatDateShort, formatRelative, formatNumber } =
    createFormat("en-US");
// formatDateTime("2025-03-12T10:00:00Z") → "03/12/2025, 10:00 AM"
// formatDateShort(...) → "Mar 12, 2025" · formatRelative(...) → "2 minutes ago"
// formatNumber(1284) → "1,284"
</script>

Invalid/empty values render as an em dash (—). toDate(value) uses the native Date parser and returns a valid Date or null; prefer ISO 8601 strings for portable parsing. The helper is also exported standalone from the barrel.

createFormat(locale, { timeZone }) renders dates in a display time zone (for example the site's zone instead of the browser's). formatBytes(1536) gives locale units ("1.5 kB", "1,5 КБ"), and plural(count, forms) picks a form by Intl.PluralRules, with # standing for the count: plural(5, { one: "# файл", few: "# файла", many: "# файлов", other: "# файла" }).

Localization

Every built-in label defaults to English. Set the language once for the app and each label resolves as: explicit prop → provided dictionary → English default.

import { createApp } from "vue";
import { createLocale, ruMessages } from "nergous-ui-vue";

createApp(App).use(createLocale(ruMessages)).mount("#app");

Pass a partial object to override a few keys ({ "dialog.close": "Закрыть окно" }), or a ref/getter to switch language at runtime. provideLocale(messages) does the same for one component subtree, and useMessages() reads the effective dictionary in your own components. The Messages type lists every key; function keys such as "table.selection" build text from counts.

Components

Layout and data (admin shell)

A complete admin shell is assembled in examples/AdminApp.vue (sidebar + topbar

• KPIs + table with bulk actions + drawer + modal + command palette).

Large forms. When a record outgrows a drawer or modal, reach for the two big-form shells: NWizard (a stepped create flow) and NAnchoredForm (a single scrollable edit page with a sticky table of contents). examples/App.vue shows both behind an NSegmented switch. The useScrollSpy(containerRef, { offset }) composable — which powers NAnchoredForm — is also exported for anchored pages you wire yourself; it returns { active, scrollTo } and keys off data-spy attributes on the scroll container's children. Pass { scroller: "ancestor" } when the page (or the nearest scrolling ancestor) scrolls instead, so a long form keeps normal page flow.

Lists. NToolbar + NMultiSelect + NFilterChips + NDataTable + NPagination cover a filtered server list; useColumnVisibility with NColumnPicker lets users hide columns, and useSortable with NSortHandle adds drag and keyboard reordering. useHotkeys registers layout-independent shortcuts, and installEnterSubmit() lets Enter press the [data-enter-submit] button of the current form or dialog.

Example

<script setup>
import { ref } from "vue";
import {
    NCard,
    NBadge,
    NInput,
    NSegmented,
    NButton,
    NModal,
} from "nergous-ui-vue";

const open = ref(false);
const q = ref("");
const role = ref("editor");
</script>

<template>
  <NCard>
    <NBadge tone="ok" dot>Active</NBadge>
    <NInput v-model="q" icon="search" placeholder="Search" />
    <NSegmented v-model="role" :options="[
      { value: 'admin', label: 'Admin' },
      { value: 'editor', label: 'Editor' },
    ]" />
    <NButton variant="primary" icon="plus" @click="open = true">Create</NButton>

    <NModal v-model="open" title="New member">
      Form content…
      <template #footer="{ close }">
        <NButton variant="secondary" block @click="close">Cancel</NButton>
        <NButton variant="primary" block @click="close">Save</NButton>
      </template>
    </NModal>
  </NCard>
</template>

Tokens

Every value lives in styles/tokens.css as a CSS variable (--accent, --surface, --radius-md, --sp-4, …). Use them in your own components to stay inside the system; they react to the active theme and density for free:

.my-block {
  background: var(--surface);
  border-radius: var(--radius-lg);
  padding: var(--sp-4);
}

Selects inside forms and dialogs

Use the options prop and v-model; native <option> children are not supported. Option clicks suppress the wrapping label's default activation so picking an option closes the list without reopening it. Popups are teleported outside scrolling bodies, within their owning overlay when one exists. Escape closes an open select before dismissing the dialog. Style component classes, not consumer ancestor selectors.

NSelectWithSearch defaults to searchPlaceholder="Search…" and noResultsText="No results". Pass localized strings at the call site. NDataTable accepts rowClass(row) for consumer-defined row highlighting; NToaster centers single-line notifications vertically.

Demos

• examples/App.vue — a showcase of the base components.
• examples/AdminApp.vue — a full admin app built on the shell components (sidebar, topbar, table, KPIs, dropzone, command palette, modal, drawer, toasts).

Examples live in the repository and are excluded from the npm package. Replace their ../index.js import with nergous-ui-vue when copying into a consumer.

Copy either one into a fresh Vite project as the root App.vue to see the library in action.

— MIT