orio-ui

Modern Nuxt component library with theme support

11,441

vue nuxt components theme ui-library nuxt-layer orio-ui

Install
`npm install orio-ui`
Latest Version:	1.36.0 (Oct 20, 2026)
Vue:	3
License:	MIT
Last Updated:	Oct 21, 2026
Links:	GitHub · npm

Maintainer: oriondor

Orio UI

A delightful, lightweight component library for Nuxt 3+ applications. Built with TypeScript, fully tested, and designed for modern web development.

⚡ AI agents

npx orio-ui agents

One command wires your AI coding agent (Claude Code, Cursor, Copilot, …) to orio-ui's shipped, version-pinned agent docs. Details in AI Agent Onboarding.

Features

✨ 68 Components - Beautiful, accessible components ready to use 🎨 Themeable - 6 built-in accent themes with light/dark mode support 🚀 Auto-imported - Works seamlessly with Nuxt's auto-import system 📦 Tree-shakeable - Only bundle what you use 🎯 TypeScript - Fully typed for great developer experience 🧪 Tested - 57 test suites for reliability 📱 Responsive - Mobile-first design approach ♿ Accessible - ARIA-compliant components 🌐 i18n - Built-in vue-i18n support with English defaults

Quick Start

Installation

npm install orio-ui

Setup

Add Orio UI to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["orio-ui"],
});

That's it! All components and composables are now auto-imported.

Usage

<template>
  <div>
    <orio-button variant="primary" @click="handleClick"> Click Me </orio-button>

    <orio-input v-model="email" label="Email" placeholder="you@example.com" />

    <orio-view-text type="title" size="large">
      Welcome to Orio UI
    </orio-view-text>
  </div>
</template>

<script setup>
const email = ref("");

// Composables are auto-imported too!
const { theme, setTheme } = useTheme();

function handleClick() {
  setTheme("teal");
}
</script>

What's Included

Components (68)

Form Controls

Input - Text input with label support
Textarea - Multi-line text input
NumberInput - Numeric input with increment/decrement (horizontal & vertical variants)
CheckBox - Custom checkbox with icon states
SwitchButton - Toggle switch component
DatePicker - Date selection with month/year options
DateRangePicker - Start and end date selection
Selector - Generic dropdown selector (single/multi-select)
TaggableSelector - Selector with taggable input
CheckboxGroup - Group of checkboxes with shared model
RadioButton - Radio button component
Tag - Styled tag/badge component
Badge - Status badge with variants
ListItem - Selectable list item

Interactive

Button - Primary, secondary, subdued variants with loading/icon support
NavButton - Navigation button component
Form - Form wrapper with validation support
Modal - Animated modal with origin morphing
Popover - Positioned popover with smart placement
Tooltip - Hover tooltip component
Banner - Notification banner component

Display

Icon - SVG icon system with 97 bundled icons
LoadingSpinner - Animated loading indicator
EmptyState - Empty state placeholder
DashedContainer - Dashed border container with icon
ControlElement - Form control wrapper
AnimatedContainer - Flex container with fade-in animation and optional sound

View

Text - Typography component with variants
Dates - Date range display formatter
Separator - Visual divider

Gallery

Carousel - Image carousel component

Upload

Upload - File upload component

Composables (18)

useTheme - Theme and color mode management
useModal - Modal state with animation origin tracking
useFuzzySearch - Fuzzy search powered by Fuse.js
useApi - Type-safe API request wrapper
useValidation - Form validation with error handling
useDecimalFormatter - Number formatting utilities
usePressAndHold - Press and hold interaction handler
useSound - Audio playback with CDN-hosted sounds

Theming

Built-in themes:

Navy (default) - Professional blue
Teal - Fresh cyan-green
Forest - Natural green
Wine - Deep burgundy
Royal - Rich purple-blue
Violet - Glowing electric violet
Normal - Neutral gray
Inverse - High contrast (adapts to mode)

All themes support light and dark modes. Fully customizable via CSS variables.

<script setup>
const { setTheme, setMode } = useTheme();

setTheme("violet");
setMode("dark");
</script>

Documentation

Live Demo & Documentation

AI Agent Onboarding

Orio UI ships a routing index and per-component invariants/gotchas files designed for AI coding agents (Claude Code, Cursor, Copilot, etc.) so they can discover and integrate components without re-reading the whole codebase. The files are version-pinned to your installed orio-ui — upgrade the package and the agent sees the new API automatically.

What ships inside `node_modules/orio-ui/dist/`

agents/ROUTING.md — full routing index (every component and composable, grouped by category, with a one-line purpose).
agents/component-worker.md — optional subagent definition. Picks the right component for a vague request, reads its agent doc, then implements the integration in your app.
agents/component-finder.md — optional read-only subagent. Locates a component for a vague request and returns paths without writing code.
agents/snippet.md — the CLAUDE.md snippet appended by npx orio-ui agents.
agents/components/<Name>.md and agents/composables/<name>.md — per-entry invariants, gotchas, and a quick-reference snippet, in a mirror of the source tree.

Wire it into your project

Run once in your project root:

npx orio-ui agents

It appends the snippet below to your CLAUDE.md, creating the file if missing (no-op when already wired). Or paste it yourself — into CLAUDE.md, AGENTS.md, .cursorrules, or any agent instruction file your tooling reads:

## orio-ui

orio-ui ships agent-ready docs inside the package itself. Before answering
anything about orio-ui components/composables, read
`node_modules/orio-ui/dist/agents/ROUTING.md` — it routes to per-component
agent docs and optional subagents. Don't explore the package source blindly.

Optional: install the subagents

If your AI tooling supports subagents (e.g. Claude Code's .claude/agents/), copy the shipped definitions in once and forget about them:

mkdir -p .claude/agents
cp node_modules/orio-ui/dist/agents/component-worker.md .claude/agents/
cp node_modules/orio-ui/dist/agents/component-finder.md .claude/agents/

After that, requests like "add a date range picker to the booking form" or "where is the toast component?" are routed automatically to the right subagent, which already knows the orio-ui routing table and reads the matching agent doc before writing code.

Re-copy after orio-ui upgrades so the routing table in the subagent definition tracks the installed version. (Pin this to your project's postinstall script if you want it automated.)

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/oriondor/orio-ui.git
cd orio-ui

# Install dependencies
npm install

# Run documentation site
npm run dev

# Run tests
npm test

# Build library
npm run build

# Run documentation
npm run docs:dev

Project Structure

orio-ui/
├── src/
│   ├── runtime/
│   │   ├── components/   # 68 Vue components
│   │   ├── composables/  # 18 composables
│   │   ├── assets/css/   # Theme CSS files
│   │   └── utils/        # Icon registry
│   └── module.ts         # Nuxt Module definition
├── tests/                # Vitest unit tests
├── docs/                 # VitePress documentation
└── build.config.ts       # Module build configuration

Running Tests

# Run all tests
npm test

# Run tests once
npm run test:unit

# Watch mode
npm run test:watch

TypeScript Support

Orio UI is written in TypeScript and provides full type definitions:

import type { TextTypes, TagStyle } from "orio-ui/composables";
import type { OriginRect, ModalProps } from "orio-ui/composables";
import type { IconName } from "orio-ui/composables";

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT © oriondor

Changelog

See CHANGELOG.md for version history.

Credits

Built with:

Nuxt 3 - Vue framework
VueUse - Vue composables collection
Fuse.js - Fuzzy search library
VitePress - Documentation
Vitest - Testing framework

Made with ❤️ for the Nuxt community

Related Packages

@thespielplatz/tsp-tools-theme

tsp.tools design-system theme as a Nuxt layer (Nuxt UI v4 + Tailwind v4): amber-...

3,240

nuxt nuxt-layer theme dark-mode design-system nuxt-ui tailwindcss tsp

@nuxtjs/design-tokens-edge

'Vue-native zero-runtime CSS-in-JS solution.

2,128 51

nuxt theme kit

@nuxt-themes/config-edge

Toolkit for authoring Nuxt Themes

1,406 30