@vyui/core

Vy UI

Lynx-native UI primitives for Vue.

Vy UI brings a Radix-style primitives layer to the Vue-Lynx ecosystem. Build native mobile apps for iOS, Android, and Web from a single Vue codebase, with components you own and can modify.

⚠️ Status: alpha. Component names, props, and slots have held steady across recent releases — the breaking changes so far removed unused exports rather than reshaping APIs. What can still shift is underneath: Vue-Lynx labels itself pre-alpha. Pin your versions and read the changelog before upgrading.

Why Vy UI

Vue-Lynx is the Vue binding for Lynx, ByteDance's open-source native cross-platform framework (the same one powering parts of TikTok). It's a serious alternative to React Native for the 2M+ Vue developer community.

But the Lynx ecosystem currently has no extensive UI component library. There's no Radix, no shadcn/ui, no Vant equivalent for Vue-Lynx. Vy UI fills that gap:

• Headless primitives for behavior, accessibility, and composition

• Native-first — designed for Lynx's <view> and <text> rendering model, not retrofitted from web

• Styled components on top via @vyui/kit, with @vyui/core providing the underlying primitive layer

Architecture

Two runtime layers plus a CLI to distribute them, with more planned (see Roadmap):

@vyui/core    →  Runtime primitives, ship in your app bundle
@vyui/kit      →  Styled components built on top of @vyui/core
@vyui/cli      →  shadcn-style CLI — copy kit component source into your own project

@vyui/core — Primitives

The runtime library. Provides headless, accessible component logic for Vue-Lynx:

• Behavioral primitives: Dialog, Popover, Dropdown, Sheet, Tabs, Accordion

• Form primitives: Field, Label, Error, Validation

• Composables for focus management, keyboard navigation, and state

• Type-safe APIs designed for Lynx's native rendering model

Components expose state attributes (data-state, data-disabled, …) and namespaced structural markers (data-vyui-*) you can style and select against — see docs/data-attributes.md.

pnpm add @vyui/core

@vyui/kit — Styled components

Opinionated styled components layered on top of @vyui/core, published for Vue-Lynx apps that want ready-to-use Vy* components and theme defaults.

@vyui/cli — Own the components (shadcn-style)

A CLI that copies styled component source into your own project instead of installing it as a package — you own and edit the .vue + theme files, while the headless @vyui/core primitives stay an npm dependency (the shadcn/Radix model).

npx @vyui/cli init             # detect the Vue-Lynx project and wire up tokens + preset
npx @vyui/cli add button       # copy a component (and its dependencies) into your app

Components come from a versioned, style-namespaced registry generated from @vyui/kit source. See the CLI guide.

Quick start

Start a new app with everything wired (Tailwind preset, worklets, providers, overlay hosts):

npm create @vyui@latest my-app

Or add Vy UI to your own Vue-Lynx app:

pnpm add @vyui/core @vyui/kit

Then use the primitives directly — they're headless, so they render with your own styling and work without any further wiring:

<!-- App.vue -->
<script setup>
import { SliderRoot, SliderTrack, SliderRange, SliderThumb } from '@vyui/core'
import { ref } from 'vue'
const value = ref(50)
</script>

<template>
  <SliderRoot v-model="value" :max="100">
    <SliderTrack><SliderRange /></SliderTrack>
    <SliderThumb />
  </SliderRoot>
</template>

To use the styled @vyui/kit components (<VyButton>, <VyCalendar>, …) you also wire the Tailwind preset, theme stylesheet, and providers. That setup is covered step by step in the installation guide.

Local development

Working on Vy UI itself (not consuming it):

git clone https://github.com/KealanAU/vyui.git
cd vyui
pnpm install

# Run the styled-component showcase
pnpm --filter @vyui/kit-demo dev

Scan the LAN QR with Lynx Explorer for on-device preview, or open the printed main.web.bundle URL for the web preview. See CONTRIBUTING.md for the full workflow (the workspace source aliasing, MT-worklet pitfalls, and the PR checklist).

Project structure

vyui/
├── packages/
│   ├── core/                  # @vyui/core — runtime primitives (published)
│   ├── kit/                   # @vyui/kit — styled components on top of core
│   ├── cli/                   # @vyui/cli — shadcn-style init/add CLI + registry
│   ├── create-vyui/           # @vyui/create — starter template (npm create @vyui)
│   ├── shared-build-config/   # shared Vite build config
│   └── testing-utils/         # shared test helpers
├── apps/
│   ├── docs/                  # vyui.dev docs site + the hosted registry (public/r)
│   └── examples/
│       ├── kit-demo/          # styled-component showcase
│       ├── cli-demo/          # app built from CLI-copied components
│       ├── docs-playground/   # docs example bundle
│       └── …
├── styles/                    # registry style overlays (rounded, shadcn, …)
└── fixtures/                  # type-lock consumer fixtures

Roadmap

Where the project is today and where it's headed. Everything is pre-1.0, so even shipped pieces are still subject to change.

Shipped

• @vyui/core — headless primitives, published on npm
• @vyui/kit — styled components on top of core, published on npm
• @vyui/cli — shadcn-style CLI for adding components to a downstream project (vyui init, vyui add button, list, view, styles, info, check)
• Component registry — <style>/* JSON manifests (inlined source, @vyui/core dependencies, file destinations) generated by tools/gen-registry.ts
• Style namespacing (à la shadcn default) — pick a style at init; styles layer tokens, UI theme deltas, and optional full-file overlays over the kit base
• Documentation site (vyui.dev) with generated API tables and live examples
• Theme system / design tokens — one config object feeds both the Tailwind preset (build) and the runtime, so the emitted classes can't drift from the selected variant
• <VyIcon> primitive — resolves any Iconify icon (bring your own @iconify-json set; nothing is bundled)
• @vyui/create — starter template (npm create @vyui@latest) that wires the Tailwind preset, worklet allowlist, providers, and overlay hosts in one step

In progress

• Cross-target verification (iOS, Android, Web) — behavior is proven on some targets but not yet uniformly validated across all three

Contributing

Contributions welcome — especially:

• Primitive implementations and behavioral edge cases

• Lynx-specific platform adjustments (iOS, Android, Web targets)

• Styled component templates for @vyui/kit and the future registry

• Documentation, examples, and starter templates

See CONTRIBUTING.md for the local-development workflow (including how @vyui/core and @vyui/kit are source-aliased into the demo apps, the MT-worklet pitfalls list, and the PR checklist).

Acknowledgements

Vy UI stands on the shoulders of excellent prior work. None of this would exist without the projects below — much of the primitive design, theming approach, distribution model, and Lynx-specific scaffolding was learned by reading, porting, and adapting from them.

Primary references

• Radix UI — Pioneered the headless primitives model and the multi-part component pattern (Root / Trigger / Content / etc.) that Vy UI follows. MIT.

• Nuxt UI — The Tailwind Variants + createTv theming model in @vyui/kit, the slot-based component theme files under packages/kit/src/theme/*, and the apps/docs site itself all draw heavily on Nuxt UI's approach. MIT.

• shadcn/ui — Defined the CLI + registry distribution model that @vyui/cli and the vyui.dev/r/* registry manifests are modeled on. MIT.

• Lynx UI — ByteDance's reference component set for Lynx. The patterns for working around Lynx's <view> / <text> constraints, MT-worklet pitfalls, and the rasterized <svg> model were learned in part from reading Lynx UI's source. Apache-2.0.

• Vue-Lynx — The Vue binding for Lynx that this entire library targets. Without it, Vy UI has nothing to render to. Apache-2.0.

Honourable mentions

• Park UI — Proved the layered primitives + styled-on-top + CLI distribution model is portable across primitive libraries.

• Headless UI and Ariakit — Earlier explorations of the headless-primitives space that shaped the ecosystem.

• Tailwind CSS and Tailwind Variants — The utility + variants system @vyui/kit is built on.

• Iconify and icones.js.org — The icon ecosystem Vy UI's <Icon> primitive resolves against.

Attribution

Some styled component templates may be ported from or inspired by other MIT projects. Where this is the case, original license terms and attribution are preserved in each component file.

License

MIT © 2026 Kealan Clarke and Vy UI contributors

Built with respect for the open-source ecosystem that made this possible.