https://github.com/soybeanjs/soybean-ui

A powerful and elegant Vue 3 component system with headless primitives and ready-to-use styled wrappers.
https://github.com/soybeanjs/soybean-ui
radix-vue shadcn-ui uikit unocss vue3
Last synced: about 1 month ago
JSON representation
A powerful and elegant Vue 3 component system with headless primitives and ready-to-use styled wrappers.
Host: GitHub
URL: https://github.com/soybeanjs/soybean-ui
Owner: soybeanjs
Created: 2022-12-20T13:14:46.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2026-05-10T07:13:34.000Z (about 1 month ago)
Last Synced: 2026-05-10T07:31:07.203Z (about 1 month ago)
Topics: radix-vue, shadcn-ui, uikit, unocss, vue3
Language: TypeScript
Homepage: https://ui.soybeanjs.cn
Size: 13 MB
Stars: 174
Watchers: 2
Forks: 14
Open Issues: 15
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project

README

          


  

    

  



# SoybeanUI

English | [中文](./README.zh-CN.md)

[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

[![github stars](https://img.shields.io/github/stars/soybeanjs/soybean-ui)](https://github.com/soybeanjs/soybean-ui)

SoybeanUI is an elegant, modern, accessible and high-quality UI component library with shadcn-like design for Vue 3, built on top of a robust headless foundation. It provides a comprehensive set of accessible, customizable, and performant components.

## 📚 Architecture

SoybeanUI is built on a strict **two-layer separation** model:

```

┌─────────────────────────────────────────┐

│           @soybeanjs/ui (src/)          │

│  S-prefixed components   (SButton…)     │

│  UnoCSS classes · tailwind-variants     │

│  provideXUi(ui)  ──────────────────┐    │

└────────────────────────────────────┼────┘

                                     │ style injection

┌────────────────────────────────────▼────┐

│        @soybeanjs/headless (headless/)  │

│  Logic · State · A11y · Keyboard nav    │

│  useUiContext() reads injected classes  │

│  Zero styles — works with any CSS       │

└─────────────────────────────────────────┘

```

### Packages

| Package                 | Role                              | Components                        |

| ----------------------- | --------------------------------- | --------------------------------- |

| **@soybeanjs/headless** | Logic, state, a11y. Zero styles.  | 95 component dirs, 25 composables |

| **@soybeanjs/ui**       | Styled wrappers. UnoCSS + `tv()`. | 91 `S`-prefixed components        |

**Data flow is strictly one-way**: `headless` → `src`. The styled layer never imports from headless's internals — it injects style tokens via `provideXUi(computedUi)` which headless components read through `useUiContext()`.

Some multi-slot headless components also expose `Compact` aggregators, such as `AccordionCompact` and `TableCompact`. They keep item iteration and default content/icon composition inside headless, while the UI layer stays focused on styling and prop forwarding.

Current Compact-style coverage also includes flows such as card, date-field, dialog, editable, hover-card, layout, navigation-menu, pagination, popover, and stepper, when those structures are stable enough to live in headless.

### Style Injection

Every multi-slot headless component exposes a `provide{Name}Ui` function. The styled wrapper computes classes using `tailwind-variants` and injects them:

```ts

// In the styled wrapper (src/)

const ui = computed(() =>

  mergeVariants(

    accordionVariants({ size: props.size }), // tv() output

    props.ui, // user overrides

    { root: props.class } // class prop

  )

);

provideAccordionUi(ui); // headless reads this via useAccordionUi()

```

### Theme System

- **`ThemeColor`** — 8 semantic colors: `primary` · `destructive` · `success` · `warning` · `info` · `carbon` · `secondary` · `accent`

- **`ThemeSize`** — 6 sizes: `xs` · `sm` · `md` · `lg` · `xl` · `2xl` (base 16px at `md`)

- **`ConfigProvider`** — sets global `dir`, `locale`, `nonce`, and default `tooltip` config for the entire component tree, including RTL layout switching

- **`cn()`** — Tailwind-aware class merge (`clsx` + `tailwind-merge`), used for conflict-free class composition

### Locale Support

`ConfigProvider` supports the following locale bundles:

| Code    | Language            |

| ------- | ------------------- |

| `zh-CN` | Simplified Chinese  |

| `zh-TW` | Traditional Chinese |

| `en`    | English             |

| `ar`    | Arabic              |

| `ja`    | Japanese            |

| `ko`    | Korean              |

| `de`    | German              |

| `fr`    | French              |

| `es`    | Spanish             |

| `pt-BR` | Portuguese (Brazil) |

| `ru`    | Russian             |

| `tr`    | Turkish             |

| `id`    | Indonesian          |

Only `en` and `zh-CN` are pre-registered by default. `registerLocale` supports two registration styles:

- Pass a `LocaleRegistry` object. Built-in locale files from `@soybeanjs/headless/locale/{code}` already export this shape, including `dir` metadata.

- Pass a locale key plus `LocaleMessages` for a lightweight custom locale.

The shorthand `registerLocale(key, messages)` form uses the key as the locale name and falls back to `ltr`. Use the object form when you need explicit metadata such as `rtl`.

```ts

import { en, registerLocale } from '@soybeanjs/headless/locale';

import type { LocaleMessages } from '@soybeanjs/headless/locale';

import ar from '@soybeanjs/headless/locale/ar';

registerLocale(ar);

const customMessages: LocaleMessages = {

  ...en.messages,

  pagination: {

    ...en.messages.pagination,

    nextPage: 'Next →',

    prevPage: '← Prev'

  }

};

registerLocale('custom', customMessages);

```

### Package Exports

**@soybeanjs/headless** ships fine-grained sub-paths:

```ts

import { AccordionRoot } from '@soybeanjs/headless'; // all components

import { useControllableState } from '@soybeanjs/headless/composables'; // 25 composables

import { transformPropsToContext } from '@soybeanjs/headless/shared'; // pure TS utils

import { createMonth } from '@soybeanjs/headless/date'; // shared date helpers

import * as Headless from '@soybeanjs/headless/namespaced'; // namespace object

import type { AccordionUiSlot } from '@soybeanjs/headless/accordion'; // per-component

import type { UiClass } from '@soybeanjs/headless/types'; // shared type surface

```

**@soybeanjs/ui** exports:

```ts

import { SButton, SAccordion } from '@soybeanjs/ui'; // all components

import '@soybeanjs/ui/styles.css'; // pre-built UnoCSS stylesheet

// Also: @soybeanjs/ui/nuxt · @soybeanjs/ui/resolver

```

## 🛠 Development Workflow

If you contribute new public components, exports, or API descriptions, keep generated surfaces in sync through the official scripts instead of editing generated files by hand.

```bash

pnpm sui headless                 # sync headless component names and namespaced exports

pnpm sui ui                       # sync ui component names

pnpm sui api                      # regenerate docs api json and locale baseline data

pnpm sui api-locales              # refresh api locale template data only

pnpm sui changelog                # regenerate docs changelog json and locale baseline data

pnpm sui api-translate -- --locale zh-CN

pnpm sui changelog-translate -- --locale zh-CN

```

The docs site now renders component docs through `UsageCode`, `PlaygroundGallery`, and `ComponentApi`. Component detail pages and `/releases` also read generated changelog data from `docs/src/generated/changelog/` and `docs/src/generated/changelog-locales/`.

Public API or demo delivery changes should keep docs, playground examples, and generated API data aligned. Changelog mapping, release presentation, and changelog locale template changes should keep generated changelog data aligned as well.

## 📦 Installation

### Using the Styled UI Library (Recommended)

If you want ready-to-use components with a modern design:

```bash

pnpm add @soybeanjs/ui

```

### Using the Headless Library

If you want to build your own design system from scratch:

```bash

pnpm add @soybeanjs/headless

```

## 🚀 Usage

### @soybeanjs/ui

1. **Import Styles**

   Import the CSS file in your main entry file (e.g., `main.ts`):

```ts

import '@soybeanjs/ui/styles.css';

```

2. **Global Registration (Optional)**

   You can register components globally or import them on demand.

3. **On-demand Import (Recommended)**

   We recommend using `unplugin-vue-components` for auto-importing components.

```ts

// vite.config.ts

import Components from 'unplugin-vue-components/vite';

import UiResolver from '@soybeanjs/ui/resolver';

export default defineConfig({

  plugins: [

    Components({

      resolvers: [UiResolver()]

    })

  ]

});

```

4. **Nuxt Module**

```ts

// nuxt.config.ts

export default defineNuxtConfig({

  modules: ['@soybeanjs/ui/nuxt']

});

```

### @soybeanjs/headless

The headless components provide the functionality without the styles.

For data-driven multi-slot patterns, prefer the exported `Compact` variant when it exists. It is the headless entry point for opinionated composition, while the regular parts remain available for fully manual assembly.

```vue

import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';

  

    

      Is it accessible?

      Yes. It adheres to the WAI-ARIA design pattern.

    

  

```

## ✨ Features

- **Accessible**: Follows WAI-ARIA patterns for roles, focus management, and keyboard navigation.

- **RTL ready**: Switch supported components between LTR and RTL layouts with `ConfigProvider`.

- **Headless-first**: Logic and styles are fully separated — use `@soybeanjs/headless` alone to build any design system.

- **Type Safe**: Written in strict TypeScript. All props, emits, slots, and context values are typed.

- **Customizable at every level**: Override individual slot classes via the `ui` prop, or swap the entire style layer.

- **Lightweight & Tree-shakable**: Import only the components you use. Each component is individually tree-shakable.

- **Nuxt ready**: First-class Nuxt module with auto-registration (`@soybeanjs/ui/nuxt`).

- **unplugin support**: Auto-import resolver for `unplugin-vue-components` (`@soybeanjs/ui/resolver`).

## 💝 Credits

- [reka-ui](https://github.com/unovue/reka-ui)

- [oku-ui](https://github.com/oku-ui/primitives)

- [shadcn-vue](https://github.com/unovue/shadcn-vue)

- [shadcn/ui](https://github.com/shadcn/ui)

- [nuxt-ui](https://github.com/nuxt/ui)

- [unocss](https://github.com/unocss/unocss)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/soybeanjs/soybean-ui

Awesome Lists containing this project

README
