@livestorm/ui-vue

@livestorm/ui-vue

A modern, strongly-typed Vue 3 component library for Livestorm’s design system.

Browse the components →

Table of Contents

• Requirements
• Installation
• Tailwind CSS setup
• App setup
• Using components
• Entry points
• Contributing

Requirements

• Vue 3.5+, a peer dependency provided by your app.
• vue-router 5+, an optional peer dependency. Everything works without it — install it only if you use one of these router-aware features:
  • the to prop on UiButton, UiListItem, UiActionBarItem and UiSideMenu items, which renders a <router-link> (each also accepts a plain href link instead);
  • the confirmTo action of toasts (confirmHref is the plain-link alternative);
  • the logo link of UiPageHeader when showLogo is enabled;
  • the @livestorm/ui-vue/utils entry point: its useRouteQueryModel helper is built on the router, so importing this entry requires vue-router to be installed.
• Tailwind CSS 4, since components are styled with Tailwind utility classes.
• The Inter font, which components are designed for. The package never loads it for you: load it yourself, or import the optional self-hosted shortcut once (import '@livestorm/ui-vue/fonts', Inter Variable served from the inter-ui dependency). Without Inter, components fall back to the system font stack.

Installing the package also pulls in @livestorm/ui-tokens (design tokens) and @livestorm/ui-icons (icon utilities).

Installation

pnpm add @livestorm/ui-vue

Tailwind CSS setup

Components use Tailwind utility classes (including the i-ls-* / i-ph-* icon classes), so your app needs to run Tailwind and scan the library. In your Tailwind entry CSS:

@import "tailwindcss";
@import "@livestorm/ui-tokens/output/supernova/index.css";
@plugin "@livestorm/ui-icons/tailwind";
@import "@livestorm/ui-icons/base.css";

/* Generate the utility classes used by ui-vue components */
@source "../node_modules/@livestorm/ui-vue/dist";

The icon plugin serves the custom Livestorm set (i-ls-<name>) and Phosphor (i-ph-<name>, regular and -fill weights). Icon names must appear as complete literals in scanned sources — never compose them at runtime.

[!WARNING] Components rely on the design-token utilities these two imports produce (bg-actions-primary-idle, i-ls-*, ...). Those class names live in the component code, not in the shipped stylesheet, so if your own theme resets the token namespace (for example --color-*: initial in an @theme), Tailwind silently stops generating them and components render unstyled — no error, no warning. Keep the Livestorm token imports alongside your palette instead of resetting all colors.

Then import the library base styles once (body defaults, transitions, animations):

import '@livestorm/ui-vue/style'

The body defaults ship inside @layer base, so anything your app declares — layered or not — takes precedence over them.

App setup

No runtime plugin is required. Create your app, import components, done:

import { createApp } from 'vue'
import { registerComponents } from '@livestorm/ui-vue/components-vite'
import '@livestorm/ui-vue/style'
import App from './App.vue'

const app = createApp(App)

registerComponents(app)    // optional: register all Ui* components globally

app.mount('#app')

Server-side rendering works out of the box: pages render with a desktop layout on the server, then adapt to the real screen size as soon as they load in the browser. No configuration and no hydration warnings. Overlay components (dialogs, dropdowns, menus, popovers, tooltips) render through client-only teleports and hydrate with no extra setup.

import Responsive from '@livestorm/ui-vue/responsive'

app.use(Responsive, {
  computed: {
    mobile: state => state.width < 900, // override the built-in flag
  },
})

import { setTranslator } from '@livestorm/ui-vue/integrations'

setTranslator((key) => myI18n.t(`ui-vue.${key}`))

import { UI_VUE_TRANSLATOR } from '@livestorm/ui-vue/integrations'

app.provide(UI_VUE_TRANSLATOR, (key) => myI18n.t(`ui-vue.${key}`))

Every component is a named export:

import { UiButton, UiTextField, UiInputSelect } from '@livestorm/ui-vue'

<template>
  <UiButton variant="cta" color="primary" icon="i-ph-check">
    Click me
  </UiButton>
</template>

Props, variants and events for each component are documented in the hosted Storybook, where every story is interactive. TypeScript definitions ship with the package, so editors autocomplete props and catch mistakes.

If you registered components globally with registerComponents(app), you can use <UiButton> in any template without importing it. A custom prefix is supported too:

registerComponents(app, 'Ls')    // <LsButton>, <LsTextField>, ...

Entry points

The package ships prebuilt ES modules, so no special bundler configuration is needed. The original sources are included as well, if your setup prefers to compile the components itself.

Contributing

This package lives in Livestorm's entropy monorepo, under packages/ui-vue. See that directory's AGENTS.md for architecture, conventions and the release process.