,# @vialiq/web-components
Buildable and publishable Lit web component library for the Vi design system.
## Goals
- ESM-only output
- Per-component subpath exports (no forced all-in import)
- Self-styled components with CSS embedded in JS
- Themeable via Flux UI token fallbacks
## Install
```bash
npm install @vialiq/web-components lit
```
## Integration Guide
Since these components are built using standard Custom Elements APIs, they are compatible with any web framework or vanilla web stack.
### Subpath Exports & Tree-Shaking
To keep your bundle sizes minimal, import only the components you need:
```ts
// Good: Imports only the button component
import '@vialiq/web-components/button';
// Good: Imports only the input component
import '@vialiq/web-components/input';
```
If you prefer to import all components, or if you need helper classes and TypeScript types, you can import from the main package entrypoint:
```ts
import { registerIcons, ViButton } from '@vialiq/web-components';
```
### Framework Guides
#### 1. React
React 19 supports Custom Elements natively. If you are using React <19, you must set properties and custom events manually via `ref` or use custom wrapper packages.
**React 19 Example:**
```tsx
import React from 'react';
import '@vialiq/web-components/button';
import '@vialiq/web-components/input';
export function SearchForm() {
return (
);
}
```
#### 2. Vue
Vue supports custom elements seamlessly out-of-the-box. Register the tags so Vue's compiler knows not to treat them as Vue components:
**vite.config.ts:**
```ts
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag.startsWith('vi-'),
},
},
}),
],
});
```
**Vue Component Template:**
```html
Register
```
#### 3. Angular
To use Custom Elements in Angular, you must add the `CUSTOM_ELEMENTS_SCHEMA` to the `schemas` array of the `@Component` (for standalone components) or `@NgModule` where they are consumed.
**Standalone Component Setup:**
```typescript
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@Component({
selector: 'app-search-form',
standalone: true,
templateUrl: './search-form.component.html',
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class SearchFormComponent {
searchQuery = '';
onInput(event: Event) {
const customEvent = event as CustomEvent<{ value: string }>;
this.searchQuery = customEvent.detail.value;
}
}
```
**search-form.component.html Template:**
```html
Search
```
#### 4. Next.js (SSR / React Server Components)
Custom Elements must register on the browser's `window` object. Next.js and server-side rendering environments require lazy-loading or dynamic imports to ensure registration occurs client-side.
```tsx
'use client';
import { useEffect } from 'react';
export default function MyClientComponent() {
useEffect(() => {
// Import dynamically on the client
import('@vialiq/web-components/button');
}, []);
return Save;
}
```
---
## Component API & Detailed Examples
### Button ([vi-button](./src/button/vi-button.ts))
The [ViButton](./src/button/vi-button.ts) is a versatile button component that wraps a native `