Nyx Kit

Nyx Kit is a lightweight and flexible developer kit for building Vue applications. It provides a cohesive set of reusable components, utilities, and patterns designed for modern, performant, and scalable applications.

Documentation

For more detailed information, usage examples, and live demos of components, visit the Storybook documentation.

Brand identity: final logo and downloads. Archived explorations: SVG logo proposals and proposal 2 moodboard.

Storybook demo organization

Keep story entries beside their components. Place extracted demo components and story fixtures in that component’s storybook/ subfolder (for example, src/components/NyxCommandPalette/storybook/). These helpers are internal and must not be exported by the library. See the contributor convention.

GitHub Actions runs lint checks and unit tests on pull requests and pushes to main. See CI commands and behavior.

Installation

Available on npm: nyx-kit.

pnpm add nyx-kit

Plugin setup

// main.ts
import { createApp } from 'vue'
import { NyxKit, NyxColourMode } from 'nyx-kit'
import 'nyx-kit/style.css'
import App from './App.vue'

createApp(App)
  .use(NyxKit, {
    colourMode: {
      mode: NyxColourMode.Dark, // 'dark' | 'light' | 'adaptive'
    }
  })
  .mount('#app')

Colour mode

Three modes are available:

| Mode | Behaviour | |------|-----------| | NyxColourMode.Dark | Always dark — the default | | NyxColourMode.Light | Always light | | NyxColourMode.Adaptive | Clock-driven: light 06:00–20:00, dark otherwise |

Switch modes at runtime with the useNyxColourMode composable:

import { useNyxColourMode, NyxColourMode } from 'nyx-kit/composables'

const { mode, isDark, isLight, setMode } = useNyxColourMode()

setMode(NyxColourMode.Light)    // override for this session
setMode(NyxColourMode.Adaptive) // hand control back to the clock

The chosen mode is persisted to localStorage and restored on next load. The composable works without the plugin — NyxKit.install() is optional.

Programmatic confirmation dialog

Use NyxKit.confirm() to display a confirmation dialog and await the user's response:

import { NyxKit, NyxTheme } from 'nyx-kit'

const result = await NyxKit.confirm({
  theme: NyxTheme.Danger,
  title: 'Delete Item',
  message: 'Are you sure you want to delete this item? This action cannot be undone.',
  confirmText: 'Delete',
  cancelText: 'Cancel'
})

if (result.isSuccess) {
  // User clicked Confirm
  console.log('Confirmed!')
} else {
  // User clicked Cancel, pressed Escape, or clicked the backdrop
  console.log('Cancelled')
}

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | theme | NyxTheme | Primary | Theme for the confirm button | | title | string | '' | Modal header text | | message | string | (required) | Modal body content | | confirmText | string | 'Confirm' | Confirm button label | | cancelText | string | 'Cancel' | Cancel button label |

The method returns a NyxResult — use .isSuccess to check the outcome.

Select option content

NyxSelect supports an optional typed #option="{ option }" slot for flat and grouped options. option is NyxSelectOption<T>, using the same value type as options and v-model.

<NyxSelect v-model="selectedDiscussion" :options="options">
  <template #option="{ option }">
    <span class="discussion-option">
      <span class="discussion-option__title">{{ option.label }}</span>
      <span class="discussion-option__date">{{ dateFor(option.value) }}</span>
    </span>
  </template>
</NyxSelect>

Use a full-width flex row with min-width: 0 and ellipsis on the title, and flex-shrink: 0 on the date. Consumers own formatting and layout. Without a slot, the label renders as before. The closed control, native select, and search still use option.label; NyxSelect owns selection, keyboard navigation, and accessibility. See the select spec and the custom option content stories.

Tooltips

NyxTooltip accepts a numeric delay in milliseconds, defaulting to 150 for hover and click opening. Use :delay="0" for immediate opening. Closing and manual v-model updates are immediate. See the tooltip spec.

Accordion

NyxAccordion closes sibling sections by default. Set multiple to allow independent expansion. A v-model is optional: use a string ID in single mode or a string array in multiple mode. Panels animate open and closed with reduced-motion support.

<script setup lang="ts">
import { NyxAccordion } from 'nyx-kit'

const items = [
  { id: 'account', label: 'Account' },
  { id: 'privacy', label: 'Privacy' },
]
</script>

<template>
  <NyxAccordion :items="items">
    <template #item-account>Account details</template>
    <template #item-privacy>Privacy details</template>
  </NyxAccordion>
</template>

Use shared scoped header and default slots for repeated content, with header-${id} and item-${id} overrides. See the component specification for model rules and accessibility.

Command palette

NyxCommandPalette provides a standalone horizontally centered overlay with a stable search position, grouped fuzzy search, keyboard navigation, and typed result slots. Set inline to embed it. The consumer owns command actions and remote requests. Pass shortcut="SUPER+K" to enable Ctrl/⌘K toggling, or a custom chord; no shortcut is registered by default. Browser/OS-reserved shortcuts may take precedence. In Storybook, focus the preview canvas or open the story in a new tab before using a shortcut.

<script setup lang="ts">
import { ref } from 'vue'
import { NyxCommandPalette } from 'nyx-kit'
const open = ref(false)
const groups = [{ id: 'actions', label: 'Actions', items: [{ id: 'settings', label: 'Open settings', icon: 'settings' }] }]
const lastCommand = ref('')
</script>

<template>
  <button @click="open = true">Search commands</button>
  <NyxCommandPalette v-model:open="open" :groups="groups" shortcut="SUPER+K"
    @select="({ item }) => { lastCommand = item.id; open = false }" />
  <output>{{ lastCommand }}</output>
</template>

viewportMode accepts NyxCommandPaletteViewportMode.Always, .WhileSearching, or .AfterInteraction (default). The default reveals results on the first nonblank query and keeps them visible after clearing until the overlay closes. Reopening with an empty query starts hidden. When hidden, use the footer reveal button or press Enter or Arrow Down in search to show results without selecting. Import the enum from nyx-kit or nyx-kit/types. Overlay, viewport, and result transitions respect reduced motion.

Customize footer content through the footer slot; result counts and reset-search actions are opt-in consumer content.

Conversation search works with the same API: include a to field on each item, use ignoreFilter: true for server results, and call router.push(item.to) in the select handler. The ConversationSearch story demonstrates this flow.

Selection does not close the palette automatically. Bind v-model for the last activated ID and v-model:search-term for query control. Import nyx-kit/style.css once. See the component specification and Components/Navigation/NyxCommandPalette in Storybook for slots, remote search, and accessibility.

Markdown

NyxMarkdown renders read-only Markdown with semantic HTML, Nyx typography, tables, and typed Vue inline slots for consumer-owned citations. Pass the complete accumulated string through content while streaming. Raw HTML stays text, images are omitted, and links allow only HTTP(S) or document fragments.

<script setup lang="ts">
import { NyxMarkdown } from 'nyx-kit' // also available from nyx-kit/components
</script>

<template>
  <NyxMarkdown content="**Hello** from NyxMarkdown." />
</template>

Import nyx-kit/style.css once in your application. See the component specification and InlineExtensions story for typed recognizers and real citation buttons.

ESLint

Nyx Kit ships a shareable ESLint flat config. To adopt the same rules in your project:

1. Install the peer dependencies

pnpm add -D eslint eslint-plugin-vue @vue/eslint-config-typescript eslint-plugin-oxlint

2. Extend the config

// eslint.config.ts
import nyxConfig from 'nyx-kit/eslint'

export default [
  ...nyxConfig,
  {
    // your project-specific overrides
  },
]

The config includes:

• 120-character maximum for code, comments, and Vue template lines (URL-containing lines are exempt)
• eslint-plugin-vue — Vue 3 essential rules
• @vue/eslint-config-typescript — TypeScript recommended rules
• eslint-plugin-oxlint — disables ESLint rules that oxlint handles (use alongside oxlint for faster linting)

Test-framework rules (@vitest/eslint-plugin, eslint-plugin-playwright) are not included — add those yourself if needed.

Features

• Modular and extensible – Use only what you need, with easy customization.
• Consistent and themeable – Provides a unified design system with full theming support.
• Optimized for Vue 3 – Built with modern best practices for performance and efficiency.
• Lightweight and fast – Designed to be minimal and performant, avoiding unnecessary bloat.

Goals

• Provide a simple and elegant developer experience
• Focus on flexibility without unnecessary complexity
• Maintain lightweight and performant solutions

Status

Nyx Kit is currently in early development. The foundational components and utilities are being defined, and API stability may change. As the project evolves, more features, documentation, and best practices will be introduced.

Planned Features & Components

Component Extensions

• NyxInput
  • type="number": Add a stepper to increment/decrement value.
  • type="datetime": Support a custom date/type system (module?).
  • type="color": Support a custom color picker (module?).
• NyxTable: Add sorting.
• NyxSlider: Add direction (row,column), add shape (thumb), add track highlight between min and value.

New Core Components

• NyxDropdown: A menu for selecting one option from a list.
• NyxToast: A temporary notification popup.
• NyxSkeleton: A placeholder loading animation for components.
• NyxRadioGroup: A set of radio buttons for multiple-choice selection.
• NyxColorPicker: A color selection tool.
• NyxAudioPlayer: A customizable audio player.
• NyxVideoPlayer: A customizable video player.
• NyxTree: A hierarchical list component for nested structures.
• NyxDraggable: A drag & drop helper component.

New Modular Components

NyxChronos - Date & Time

• NyxDateTimePicker: A combined date and time selection component, allowing users to pick both values in a single interface. Supports presets, custom formatting, and time zone handling.
• NyxCalendar: A versatile and interactive calendar component for displaying events, scheduling tasks, and managing dates.

NyxCodex - Rich Content

• NyxEditor: A full-featured rich text (WYSIWYG) editor, allowing users to format text, insert media, and manage content seamlessly. Supports markdown, HTML, or raw text modes, with plugins for advanced features like mentions, tables, and code blocks.
• NyxDocViewer: A document viewer for PDF, DOC, DOCX, and potentially other file formats. Enables smooth document navigation, zooming, search functionality, and optional annotation or commenting features.
• NyxWhiteboard: A collaborative, free-drawing canvas.

NyxWarp - Productivity / Launcher / PowerUser

• NyxLaunchpad: A grid or list of shortcuts to different sections of your app. Similar to macOS Launchpad or the Windows Start menu.

NyxNexus - Collaboration / Social

• NyxChat: A lightweight chat/messaging component.
• NyxCommentBox: A threaded comment system for discussions.

NyxPrism - Data Visualization

• NyxChart: A wrapper for visualizing data (bar, line, pie, etc.).
• NyxHeatmap: A specialized chart for visualizing trends.
• NyxTimeline: A component for displaying events in chronological order.

NyxVault - Files and Folders

• NyxFileManager: A flexible and intuitive file and asset management component for organizing, browsing, and handling files within an application.
• NyxFileUpload: A drag-and-drop or button-based file uploader. Supports multiple file selection, progress tracking, and optional preview functionality.

NyxTerra - Geospatial / Mapping Tools

• NyxMap: An interactive map component (e.g., for locations).