Configuration

Global registration

Register the full library once at app bootstrap:

Copied

import SaxDesignVue from 'sax-design-vue'

app.use(SaxDesignVue)

For tree-shaking, register only the components you need — see Using Components.

Color tokens

Sax Design Vue has a complete color token system, not just --sax-primary. Color tokens store three comma-separated RGB channels, rather than a complete CSS color value. This is intentional: components can derive transparent states from one token, for example rgba(var(--sax-primary), 0.12).

Use 25, 91, 255, not #195bff, rgb(25 91 255), or hsl(...), when overriding one of the color tokens below:

Copied

:root {
  --sax-primary: 37, 99, 255;
  --sax-success: 34, 197, 94;
  --sax-danger: 239, 68, 68;
}

html.dark {
  --sax-primary: 96, 165, 250;
}

Token	Default channels	Role
--sax-primary	25, 91, 255	Brand and primary actions.
--sax-success	70, 201, 58	Success feedback.
--sax-warn	255, 186, 0	Warning feedback.
--sax-danger / --sax-error	255, 71, 87	Destructive and error feedback.
--sax-info	144, 147, 153	Neutral information feedback.
--sax-dark / --sax-light	30, 30, 30 / 244, 247, 248	Semantic dark and light surfaces.
--sax-color / --sax-white / --sax-black	17, 18, 20 / 255, 255, 255 / 0, 0, 0	Base foreground and absolute neutrals.
--sax-gray-1 … --sax-gray-4	249, 252, 253 … 230, 233, 234	Neutral scale.
--sax-divider / --sax-text / --sax-background	206, 208, 212 / 44, 62, 80 / 255, 255, 255	Shared divider, text, and legacy background tokens.

Surface token families are also runtime-configurable: --sax-text-color, --sax-text-color-regular, --sax-text-color-secondary, --sax-text-color-placeholder, --sax-text-color-disabled; --sax-bg-color, --sax-bg-color-page, --sax-bg-color-overlay; --sax-border-color with -light, -lighter, -extra-light, -dark, -darker; and --sax-fill-color with the same level suffixes plus -blank. Use RGB channels for every color token; --sax-fill-color-blank remains the semantic value transparent.

Each semantic color also exposes --sax-<type>-light-1 through -light-9 and --sax-<type>-dark-2 (type is primary, success, warn, danger, error, info, dark, or light). These tonal levels are generated by Sass during the theme build. If runtime theming needs a tonal level to match a changed base color, override that level explicitly too.

The dark stylesheet overrides surface, text, border, and fill tokens. The documentation site uses the same token system — use the navbar theme toggle to preview it.

Component language

Component-generated copy — including calendar months and weekdays, date/time controls, pagination, upload states, empty states, action buttons, and accessibility labels — reads from the locale supplied to SConfigProvider. English is the default. Use the built-in Chinese locale for Chinese UI:

Copied

<script setup lang="ts">
import { zhCn } from 'sax-design-vue/locales'
</script>

<template>
  <s-config-provider :locale="zhCn">
    <app />
  </s-config-provider>
</template>

Use en from the same entry for explicit English. The locale object is reactive, so changing the value passed to locale updates component-generated text without recreating the component tree. User-provided labels, slots, and placeholders remain under application control.

Shape and motion tokens

Use the global tokens below to keep component geometry and motion consistent. --sax-radius is the master corner radius: core inputs, menus, popups, trees, buttons, pagination, and other shared controls inherit from it through the scale variables.

Copied

:root {
  /* Change one value to reshape the shared component scale. */
  --sax-radius: 10px;

  /* Change one value to speed up or slow down shared interactions. */
  --sax-motion-duration: 180ms;
  --sax-motion-easing: cubic-bezier(0.2, 0.8, 0.2, 1);
}

Variable	Default	Purpose
--sax-radius	12px	Master radius for standard surfaces and controls.
--sax-radius-xs / --sax-radius-sm / --sax-radius-md	derived	Compact control radii, derived from the master radius.
--sax-radius-lg / --sax-radius-xl / --sax-radius-2xl / --sax-radius-3xl	derived	Large containers, emphasized surfaces, and expressive legacy shapes.
--sax-radius-pill / --sax-radius-circle	9999px / 50%	Semantic values for pill and circular controls.
--sax-radius-loader-orb-a / -b / -c	derived shape presets	Optional overrides for the three asymmetric loader illustrations.
--sax-radius-avatar / --sax-radius-checkbox	35% / 32%	Optional shape overrides for avatar and checkbox visual variants.
--sax-motion-duration	0.25s	Shared transition duration.
--sax-motion-duration-fast / --sax-motion-duration-slow / --sax-motion-duration-loop / --sax-motion-duration-long	0.18s / 0.43s / 0.7s / 1s	Optional durations for compact state changes, entrances, looped animation, and long list transitions.
--sax-motion-easing	cubic-bezier(.645,.045,.355,1)	Default shared easing curve.
--sax-motion-easing-emphasized / --sax-motion-easing-standard	built-in curves	Optional easing overrides for entrance and state-change motion.

Pill and circle shapes intentionally use their semantic tokens so they remain pill-shaped and circular. The legacy --sax-border-radius-* and --sax-transition-* variables remain available. They now resolve through these global tokens, so existing overrides continue to work.

Per-component configuration

Each component page documents:

• Props — typed configuration (color, size, variants)
• Events — v-model and interaction callbacks
• Slots — composition and custom content
• Example + code — live preview with copy-ready snippets

Start from the default example, then jump to the API table at the bottom of the page.

Auto-import (Vite)

Vite already resolves sax-design-vue from node_modules; no alias is needed. Install unplugin-vue-components, then use a small resolver for S-prefixed components. Import Sax styles once from your application entry file.

Copied

import { defineConfig } from 'vite'
import Components from 'unplugin-vue-components/vite'

const SaxDesignVueResolver = (name: string) => {
  if (!name.startsWith('S')) return

  return { name, from: 'sax-design-vue' }
}

export default defineConfig({
  plugins: [
    Components({
      resolvers: [SaxDesignVueResolver],
    }),
  ],
})

// src/main.ts
import 'sax-design-vue/theme-chalk/index.css'
import 'sax-design-vue/theme-chalk/dark/css-vars.css'

This resolver imports components from the package root; it does not need a filesystem path. Alternatively, import components directly from sax-design-vue for full control.

Nuxt

See Usage with Nuxt for SSR-specific notes.