# @greypan/web-ui
> Lit-based web components for React, Vue, and vanilla JS
English | [简体中文](./README.CN.md)
## Demo
[View components used by vue](https://pan-z2l0ahvi.github.io/mono/vue-web-ui-demo/)
[View components used by react](https://pan-z2l0ahvi.github.io/mono/react-web-ui-demo/)
## Install
```bash
npm install @greypan/web-ui
```
Requires `lit` as a dependency.
## Quick Start
```js
import '@greypan/web-ui'
// import '@greypan/web-ui/components/button'
```
```html
Click me
```
## Framework Setup
### Cross-framework API conventions
`web-ui-*` elements expose three surfaces. The **DOM / JavaScript API is the source of truth**: Properties use
camelCase, Attributes use kebab-case, Events use kebab-case.
| Surface | Naming | Examples |
| --------- | ---------- | --------------------------------------------- |
| Property | camelCase | `open`, `sidebarCollapsed`, `noScrollLock` |
| Attribute | kebab-case | `open`, `sidebar-collapsed`, `no-scroll-lock` |
| Event | kebab-case | `open-change`, `sidebar-collapsed-change` |
- **Boolean attributes** follow native HTML presence semantics: absent → `false`, presence → `true`. A framework
binding that writes `disabled="false"` produces the string `"false"`, which is truthy — **bind dynamic booleans as
properties** (camelCase), not attributes, so `false` is written as a real property.
- **Vue**: dynamic binding must go to **Properties** with camelCase names (`:sidebarCollapsed="x"`, `:open="x"`).
A kebab-case binding like `:sidebar-collapsed="x"` is written as a string attribute and cannot express `false`;
use the camelCase property. The `.prop` modifier is only valid with the camelCase name
(`:sidebarCollapsed.prop="x"`). String/number values may stay on kebab-case attributes (`:max-height="120"`).
`v-model` is supported on value-bearing controls (`web-ui-input`, `web-ui-select`, `web-ui-autocomplete`, …) and
compiles to the element `value` property + `input` event.
- **React**: React 19 writes DOM properties for custom-element props, so use camelCase props (`open={open}`,
`noScrollLock`, `value={value}`). Never pass complex data (objects, arrays) through attribute strings — bind
them as properties. Kebab-case JSX props on a custom element are written as attributes.
### React
Requires `@types/react >= 19` as optional peer dependency.
```ts
// vite.config.ts
import unpluginWebComponents from '@greypan/unplugin-web-components/vite'
export default {
plugins: [unpluginWebComponents({ tagPrefix: 'web-ui', packageName: '@greypan/web-ui', sideEffects: true })]
}
// env.d.ts
import '@greypan/web-ui/types/react'
```
```tsx
import '@greypan/web-ui'
function App() {
return (
<>
alert('clicked')}>
Click
console.log(e.currentTarget.value)} />
)
}
```
#### React custom-element events and boolean properties
React 19 registers Custom Element events using the suffix of the JSX `on` key unchanged. Event names are
case-sensitive: bind `open-change` as `onopen-change`, not `onOpenChange`. Standard `input`, `change`, `focus`,
and `blur` events use React's conventional `onInput`, `onChange`, `onFocus`, and `onBlur` handlers — their
`currentTarget` is typed as the component instance, so `value` and `checked` are read cast-free. The `target`
follows React SyntheticEvent semantics (`EventTarget`) and is not narrowed. Kebab-case custom events carry their
`CustomEvent` detail typed. Boolean properties follow native HTML semantics: absence is `false` and presence is
`true`.
```tsx
setOpen(event.detail.open)}
/>
setValue(event.currentTarget.value)} />
```
When a component moves a child into its Portal Shadow DOM (such as a `web-ui-dropdown` menu item), React's
root-delegated synthetic `onClick` cannot receive that child's event. Bind a native listener directly through a
`ref` instead:
```tsx
const itemRef = useRef(null)
useEffect(() => {
const item = itemRef.current
if (!item) return
const close = () => setOpen(false)
item.addEventListener('click', close)
return () => item.removeEventListener('click', close)
}, [])
Paste and close
```
### Vue
Requires `vue >= 3.5` as optional peer dependency.
```ts
// vite.config.ts
import vue from '@vitejs/plugin-vue'
import unpluginWebComponents from '@greypan/unplugin-web-components/vite'
export default {
plugins: [
vue({
template: { compilerOptions: { isCustomElement: tag => tag.startsWith('web-ui-') } }
}),
unpluginWebComponents({ tagPrefix: 'web-ui', packageName: '@greypan/web-ui', sideEffects: true })
]
}
// env.d.ts
import '@greypan/web-ui/types/vue'
```
```vue
Click
```
Boolean properties must be bound with the **camelCase property name**, not the kebab-case attribute. Vue writes
attribute bindings as strings, and boolean attributes follow presence semantics — so `:sidebar-collapsed="false"`
produces the string `"false"`, which is truthy. Binding the camelCase name (`:sidebarCollapsed="false"`, or the
`.prop` modifier) makes Vue write the DOM property directly:
```vue
```
Vue events are typed cast-free: `@input`/`@change` on value-bearing components resolve to the component emit, so
`$event.target` is the component instance and `value`/`checked` are read directly. `$event.detail` keeps the
`CustomEvent` payload type for kebab-case events like `open-change`. Named handlers annotate with
`WebUiEvent`; use `WebUiEventName` when a value or generic represents an
event name, because it accepts only the component's string `$events` keys. `@click`/`@focus` and other native
events not declared as emits remain bindable on any `web-ui-*` element.
### Attribute and event boundaries
`web-ui-*` elements are the public DOM boundary. `id`, `class`, `style`, global HTML attributes, and `data-*` stay on
the custom-element host; they are not copied into its Shadow DOM. Components expose native-element attributes only when
they document an explicit semantic mapping. For example, `web-ui-button` maps `type` to its inner button and accepts
only `button`, `submit`, or `reset` (invalid values become `button`).
ARIA attributes are explicit: use the component's documented naming attributes, not a blanket `aria-*` pass-through.
Components own their role and interaction state. Browser-native composed events such as `click`, `input`, and `change`
remain the primary interaction API. Kebab-case custom events such as `open-change` describe user-originated component
state changes; assigning a property programmatically does not emit them.
### Form-associated controls
All form controls participate in native `FormData`, constraint validation, `form.reset()` and browser form-state restoration. The control captures its reset default once, after declarative attributes have been applied on its first connection. Later runtime property updates do not redefine that default. A disabled ancestor `fieldset` disables validation and interaction without mutating the control's public `disabled` property. For checkbox/radio groups, the group is the single submission, reset and restoration owner; managed child controls do not submit or restore an independent state.
## All Components
| Category | Component |
| -------------------- | --------------------------------------------------------- |
| **Form Controls** | [``](#web-ui-input) |
| | [``](#web-ui-textarea) |
| | [``](#web-ui-input-number) |
| | [``](#web-ui-select) |
| | [``](#web-ui-autocomplete) |
| | [``](#web-ui-slider) |
| | [``](#web-ui-checkbox) |
| | [``](#web-ui-radio) |
| | [``](#web-ui-switch) |
| | [``](#web-ui-segmented) |
| | [``](#web-ui-checkbox-group) |
| | [``](#web-ui-radio-group) |
| **Buttons** | [``](#web-ui-button) |
| | [``](#web-ui-button-group) |
| **Overlay / Modal** | [``](#web-ui-dialog) |
| | [``](#web-ui-drawer) |
| **Floating** | [``](#web-ui-popover) |
| | [``](#web-ui-tooltip) |
| | [``](#web-ui-context-menu) |
| **Menu** | [``](#web-ui-dropdown) |
| | [``](#web-ui-dropdown-item) |
| | [``](#web-ui-dropdown-divider) |
| | [``](#web-ui-dropdown-header) |
| **Data Display** | [``](#web-ui-avatar) |
| | [``](#web-ui-badge) |
| | [``](#web-ui-empty) |
| | [``](#web-ui-icon) |
| | [``](#web-ui-spinner) |
| **Layout & Utility** | [``](#web-ui-layout) |
| | [``](#web-ui-back-top) |
| | [``](#web-ui-svg-draw-lines) |
| | [``](#web-ui-theme) |
| **Notification** | [``](#web-ui-toast) |
| **Sub-items** | [``](#web-ui-option) |
| | [``](#web-ui-segmented-trigger) |
## API Reference
### Form Controls
Form controls implement `static formAssociated = true` and integrate with native `