@livestorm/ui-vue

v2.0.5

Published

6 days ago

Livestorm UI components for Vue 3

0High
0Medium
0Low

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: self-host it, or import the optional Google Fonts shortcut once (import '@livestorm/ui-vue/fonts'). 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-* 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";
@import "@livestorm/ui-icons/icons-tailwind-utilities.css";

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

[!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.

Layout components read the viewport from a shared helper with sensible defaults. Install the responsive plugin only if you want to override the breakpoint flags, or read $responsive in your own templates:

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

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

Components render a few built-in labels themselves (the dialog and banner close buttons, the "Copied!" tooltip, the side menu's "More"). Out of the box they come in English or French, picked from <html lang>. An app running i18next with Livestorm's keys keeps control automatically; any other i18n stack can take over with a translator function:

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

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

On an SSR server, provide the translator on the app instance instead — setTranslator is process-wide state shared by concurrent requests, and without a translator the server falls back to English (it cannot read <html lang>). For a non-English SSR app this is the difference between hydrating correct labels and keeping English aria-labels:

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

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

Return the key itself (or null) to fall back to the built-in labels. The keys used: general_close, general_dialog_title, general_misc_copied-text, room_bottom-bar_controls-label_more.

Every component is a named export:

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

<template>
  <UiButton variant="cta" color="primary" icon="i-ls-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

| Import | Contents | | --- | --- | | @livestorm/ui-vue | All components and utilities | | @livestorm/ui-vue/style | Base stylesheet (import once) | | @livestorm/ui-vue/fonts | Optional: loads Inter from Google Fonts (skip it if you self-host) | | @livestorm/ui-vue/components-vite | registerComponents for global registration | | @livestorm/ui-vue/integrations | Toast helpers (openToast, ... — call client-side only: toast state is per-process on a server) and translation wiring (setTranslator, UI_VUE_TRANSLATOR) | | @livestorm/ui-vue/layouts | Layout components such as the toast container | | @livestorm/ui-vue/utils | Helpers (useCopyToClipboard, useRouteQueryModel, ...) — the one entry that requires vue-router | | @livestorm/ui-vue/responsive | Optional responsive plugin |

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 CONTRIBUTING.md for architecture, conventions and the release process.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme