feat: add alpine-ts example (WIP)

[niLPotential]

📝 Description

Adds an example project using Zag with Alpine.js.

examples/alpine-ts contains a nitro app compatible with e2e tests.
lib contains the adapter logic mostly similar to other frameworks.
lib/plugin.ts contains a usePlugin hook which connects a Zag machine to Alpine.js as a plugin.
scripts contains the client scripts and server/routes contains the jsx for SSR.

⛳️ Current behavior (updates)

None

🚀 New behavior

// script.ts
import * as component from "@zag-js/component";
import Alpine from "alpinejs"
import { usePlugin } from "../lib"

// component-name should be kebab-case
Alpine.plugin(usePlugin("component-name", component)
Alpine.start()

<!-- index.html -->
<div id="root" x-data x-component-name="{ ...props }">
  <div x-component-name:part-name="{ ...partProps }" />
  <div x-component-name:another-part-name />
  <button x-on:click="$componentName().method()>Click</button>

  <div id="nested" x-component-name.modifier="{ ...props }">
    <div x-component-name:part-name.modifier="{ ...partProps }" />
    <button x-on:click="$componentName('modifier').method()>Click</button>
    <!-- this triggers method of root component from inside nested component -->
    <button x-on:click="$componentName().method()>Click</button>
  </div>
</div>

The name passed in when defining the plugin is used through out for directives and magic.
Names and Values of directives should be kebab-case.
The expression, when present, is passed as arguments to the getComponentProps function.
Other api methods are available by calling the corresponding magic. Name of magic is camelCase.
When components need to be more specific (such as when nesting), optional modifiers can be used.
x-data must be defined for components to work.

💣 Is this a breaking change (Yes/No):

No

📝 Additional Information

Last updated: 2025/11/29

route	implemented	e2e	notes
/accordion	✅	✅	-
/angle-slider	✅	✅	-
/async-list	✅	✅	-
/autoresize	✅	✅	-
/avatar	✅	✅	-
/bottom-sheet	✅	❌	closing animation does not start, jamming the component
/carousel	✅	✅	-
/carousel-auto-size	✅	-	-
/carousel-mutation	✅	-	-
/checkbox	✅	✅	-
/checkbox-controlled	✅	-	-
/clipboard	✅	✅	-
/collapsible	❌	❌	-
/color-picker	✅	✅	-
/combobox	✅	✅	-
/combobox-multiple	✅	✅	-
/context-menu	✅	✅	-
/context-menu-nested	✅	✅	-
/date-picker	❌	❌	-
/dialog	✅	-	-
/dialog-mutation	✅	-	-
/dialog-nested	✅	✅	handles nesting with modifiers
/editable	✅	✅	-
/file-upload	✅	✅	-
/file-upload-with-rejections	✅	-	-
/floating-panel	✅	-	-
/hover-card	✅	✅	-
/image-cropper	❌	❌	-
/listbox	✅	✅	-
/listbox-grid	✅	-	-
/marquee	✅	-	-
/menu	✅	✅	-
/menu-hide-with-detached	❌	-	-
/menu-nested	❌	-	-
/menu-options	✅	✅	-
/menu-overflow	✅	-	-
/navigation-menu	❌	❌	-
/number-input	✅	⚠	test 27 and 29 is flaky due to performance; passes when adding delay between types
/pagination	✅	✅	-
/password-input	✅	✅	-
/pin-input	✅	✅	-
/popover	❌	❌	-
/popper	✅	-	-
/presence	✅	-	-
/progress	✅	-	-
/qr-code	✅	-	pattern overflows frame
/qr-code-form	✅	-	pattern overflows frame
/radio-group	✅	✅	-
/range-slider	✅	-	-
/rating-group	✅	✅	-
/scroll-area	✅	-	-
/scroll-area-nested	❌	-	-
/segment-control	✅	-	-
/select	✅	✅	hovering through options is laggy
/signature-pad	❌	-	x-for does not trigger inside <svg>
/slider	✅	✅	-
/splitter	❌	❌	-
/steps	✅	✅	-
/switch	✅	✅	-
/tabs	✅	✅	-
/tags-input	✅	✅	-
/timer-countdown	✅	-	-
/timer-stopwatch	✅	-	-
/toast	❌	❌	-
/toggle-group	✅	✅	-
/toggle	✅	-	-
/tooltip	✅	✅	-
/tour	❌	❌	-
/tree-view	❌	❌	-

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6610d93

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
zag-nextjs	Ready	Preview	Nov 29, 2025 11:42am
zag-solid	Ready	Preview	Nov 29, 2025 11:42am
zag-svelte	Error		Nov 29, 2025 11:42am
zag-vue	Ready	Preview	Nov 29, 2025 11:42am
zag-website	Error		Nov 29, 2025 11:42am