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. Vue-Lynx itself is pre-alpha. APIs will change. Not production-ready.

---

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 packages today, 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/core — Primitives

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

• Behavioral primitives: Dialog, Popover, Dropdown, Tooltip, 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.

Quick start

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
│   ├── shared-build-config/   # shared Vite build config
│   └── testing-utils/         # shared test helpers
└── apps/
    └── examples/
        ├── kit-demo/           # styled-component showcase
        ├── docs-playground/   # docs example bundle
        └── …

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)
• 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 — defineVyuiConfig 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)

In progress

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

Planned

• Starter templates — a create-vyui / template repo that wires the Tailwind preset, providers, and overlay hosts in one step (the setup ceremony is the biggest onboarding cost today)

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 the planned @vyui/cli and vyui.dev/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.