Getting Started

A Vue 3 component library with a full Vue Vapor build and an animation-agnostic design: plain CSS by default, or bring your own animation library.

Install

vael-ui is published on npm. Install it with whichever package manager you use:

npmpnpmyarnbun

npm install vael-ui

Usage

Import the stylesheet once in your entry point (see Styling and cascade layers for base-style setup):

// main.ts
import 'vael-ui/style.css'

Then use any component: from 'vael-ui' for the classic VDOM build, or 'vael-ui/vapor' for the compiled Vapor build (Vue 3.6's no-virtual-DOM mode). Same props either way:

Vue DOMVapor

<script setup lang="ts">
import { Button, ConfigProvider } from 'vael-ui'
</script>

<template>
  <ConfigProvider :theme="{ primary: '#ea580c', radius: '12px' }">
    <Button @click="save">Save</Button>
  </ConfigProvider>
</template>

Vue Vapor support

Both builds ship from the same package and source. Pick whichever your app runs, or mix both (Vue 3.6 supports VDOM/Vapor interop). Every component page has the same toggle to compare them.

Dark mode

CSS-only: responds to <html data-theme="dark">, falling back to prefers-color-scheme. No toggle UI shipped; useColorScheme() handles persistence and OS-preference updates:

import { useColorScheme } from 'vael-ui'

const { mode, setMode } = useColorScheme({
  persist: {
    get: () => localStorage.getItem('theme'),
    set: (m) => localStorage.setItem('theme', m ?? ''),
  },
})

Directives

v-tooltip and v-scroll-mask aren't global by default. If you use either in more than one component, register them once:

// main.ts
import { createApp } from 'vue'
import { vTooltip, vScrollMask } from 'vael-ui'

const app = createApp(App)
app.directive('tooltip', vTooltip)
app.directive('scroll-mask', vScrollMask)
app.mount('#app')

v-tooltip also needs a <TooltipHost /> mounted once. In a Vapor app, import both directives from vael-ui/vapor instead.