Agent instructions: [/skills.md](/skills.md).
Component index: [/llms.txt](/llms.txt).

# Button (/llms.mdx/docs/components/button/content.md)

## Import [#import]

```ts
import '@eosjs/ui/button';
```

## Introduction [#introduction]

Button is a framework-agnostic Web Component aligned with the EOS semantic color and sizing system. It works with React, Vue, Angular, and plain HTML without a framework adapter.

## Basic Usage [#basic-usage]

<Demo id="components-button-demos-index" of={Basic} source={BasicSource} title="Basic usage" layout="bare" />

## Variants [#variants]

Button supports semantic colors, visual variants, three sizes, loading, disabled, and icon-only states. The example groups these axes separately so each color and state can be compared without duplicating every combination.

<Demo id="components-button-demos-variant" of={Variants} source={VariantsSource} title="Variants" />

## API [#api]

<Api name="Button" />

### Attributes [#attributes]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `default \| primary \| secondary \| success \| warning \| danger` | `primary` | Semantic color |
| `variant` | `solid \| bordered \| light \| flat \| ghost \| primary \| secondary \| tertiary \| outline \| danger \| dangerSoft` | `solid` | Visual treatment |
| `size` | `sm \| md \| lg` | `md` | Button size: 32/36/40px high |
| `disabled` | `boolean` | `false` | Prevent interaction |
| `loading` | `boolean` | `false` | Show progress and prevent interaction |
| `icon-only` | `boolean` | `false` | Use a square button at the selected size |
| `full-width` | `boolean` | `false` | Stretch the button to the host width |
| `type` | `button \| submit \| reset` | `button` | Native button type |
| `aria-label` | `string` | - | Accessible name for icon-only buttons |

### Events [#events]

| Event | When it fires | Event object |
| --- | --- | --- |
| `click` | The button is activated | Native `MouseEvent` |

### Slots [#slots]

Icons are passed through named slots; the component does not depend on a framework icon library:

```html
<eos-button>
  <svg slot="start" viewBox="0 0 16 16" aria-hidden="true"><!-- icon --></svg>
  Save
  <svg slot="end" viewBox="0 0 16 16" aria-hidden="true"><!-- icon --></svg>
</eos-button>

<eos-button icon-only aria-label="Settings">
  <svg slot="start" viewBox="0 0 16 16" aria-hidden="true"><!-- icon --></svg>
</eos-button>
```

### Framework integration [#framework-integration]

#### React [#react]

```tsx
import { useEffect, useRef } from 'react';
import '@eosjs/ui';

export function MyButton() {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    const element = ref.current;
    const onClick = (event: Event) => {
      console.log('clicked:', event.type);
    };
    element?.addEventListener('click', onClick);
    return () => element?.removeEventListener('click', onClick);
  }, []);

  return <eos-button ref={ref}>Click me</eos-button>;
}
```

#### Vue 3 [#vue-3]

```vue
<template>
  <eos-button @click="handleClick">Click me</eos-button>
</template>

<script setup>
import '@eosjs/ui';

function handleClick(event) {
  console.log('clicked:', event.type);
}
</script>
```

#### Angular [#angular]

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@eosjs/ui';

@Component({
  selector: 'app-button',
  template: '<eos-button (click)="onClick($event)">Click me</eos-button>',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ButtonComponent {
  onClick(event: MouseEvent) {
    console.log('clicked:', event.type);
  }
}
```

#### Native HTML [#native-html]

```html
<script type="module">
  import '@eosjs/ui';
  document.querySelector('eos-button').addEventListener('click', (event) => {
    console.log('clicked:', event.type);
  });
</script>

<eos-button>Click me</eos-button>
```

### CSS custom properties [#css-custom-properties]

The component consumes EOS semantic variables. Define them on the theme root or the `eos-button` host to provide Light/Dark values; the component keeps its implementation details inside Shadow DOM.

```css
/* Define theme values centrally on :root or [data-theme]. */
:root {
  /* Figma semantic tokens: slash is represented by a hyphen in CSS. */
  --accent-accent: #006fee;
  --accent-accent-foreground: #fcfcfc;
  --accent-accent-hover: #3592f9;
  --default-default: #ebebec;
  --default-default-foreground: #18181b;
  --surface-surface-secondary: #efeff0;
  --border: #dedee0;
  --focus-ring: #006fee;
}
```


# Card Stack (/llms.mdx/docs/components/card-stack/content.md)

## Import [#import]

```ts
import '@eosjs/ui/card-stack';
```

## Card Stack [#card-stack]

The previous card peeks out on the left, the current card is largest and on top, and the next card peeks out on the right at a smaller size. During a mouse drag or touch swipe, the dragged card shrinks while its neighbour grows toward the centre. At a quarter of the card width, the dragged card moves below the incoming card; the new neighbour gradually appears behind it as dragging continues. Release to settle the card into the opposite side of the stack. A shorter drag springs back. Swipe right to return to the previous card. Desktop users can also use the 44px buttons or focus the stack and press the arrow keys.

<Demo id="components-card-stack-demos-index" of={Basic} source={BasicSource} title="10,000-card data source" layout="center" />

## API [#api]

<Api name="CardStack" />

Set `itemCount` and assign `renderItem(index)` on the DOM element. The callback must return an `HTMLElement`. The component mounts three adjacent cards at rest and at most one incoming card during a transition, so the caller can keep a large array, paginated cache, or other indexed source without creating one DOM node per record. Call `refresh()` after changing data at the current index. Prefetch neighbouring image URLs in your data layer if their loading time matters.

```ts
const stack = document.querySelector('eos-card-stack');
stack.itemCount = records.length;
stack.renderItem = (index) => createCard(records[index]);
stack.addEventListener('change', (event) => console.log(event.detail.currentIndex));
```

| Member | Description |
| --- | --- |
| `item-count` | Number of items in the external source |
| `initial-index` | Zero-based initial card; read only after connection |
| `loop` | Wrap navigation at the ends |
| `currentIndex` | Current zero-based index |
| `next()`, `prev()`, `goTo(index)` | Navigate; adjacent moves animate |
| `refresh()` | Recreate the visible three-card window |
| `change` | `CustomEvent` with `{ currentIndex, previousIndex }` |
| `--card-stack-height` | Stack height, default `420px` |
| `--card-stack-card-width` | Card width, default `320px` |

The component uses EOS semantic surface, border, foreground, focus, and motion rules in both themes. Content returned by `renderItem` should use the same tokens. Interactive controls inside a card are excluded from drag initiation; add `data-no-swipe` to any other interactive region.

At the first card, the left side is empty and the next card peeks out on the right. At the last card, the right side is empty. Add `loop` only if you want the ends to wrap and all three positions to stay populated.


# Carousel (/llms.mdx/docs/components/carousel/content.md)

## Import [#import]

```ts
import '@eosjs/ui/carousel';
```

## Introduction [#introduction]

Carousel presents a sequence of slides with native keyboard navigation, touch gestures, optional autoplay, and clickable progress indicators. Slides are passed through the default slot, so each slide can contain any HTML or Web Component content.

When the operating system requests reduced motion, autoplay stays paused and slide transitions become effectively instant. Manual navigation remains available.

## Basic Usage [#basic-usage]

<Demo id="components-carousel-demos-index" of={Basic} source={BasicSource} title="Basic usage" layout="center" />

## API [#api]

<Api name="Carousel" />

### Attributes [#attributes]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | Automatically advance through the slides |
| `interval` | `number` | `2000` | Autoplay interval in milliseconds; values below 1000 are clamped |
| `loop` | `boolean` | `false` | Continue from the first slide after the last slide |
| `show-navigation` | `boolean` | `true` | Show previous and next controls |
| `initial-index` | `number` | `0` | Initial zero-based slide index |
| `indicator-position` | `top \| bottom \| left \| right` | `bottom` | Position of the progress indicators |
| `indicator-style` | `default \| dots \| tiktok` | `default` | Visual style of the progress indicators |
| `virtual-threshold` | `number` | `8` | Enable three-slot rendering after this many slides |

### Events [#events]

| Event | When it fires | `event.detail` |
| --- | --- | --- |
| `change` | The active slide changes | `{ currentIndex, previousIndex }` |
| `slide-active` | A slide becomes active | `{ index, slide, mediaType }` |
| `slide-click` | A slide is clicked | `{ index }` |

### Methods [#methods]

Carousel exposes imperative controls through its DOM element:

```ts
const carousel = document.querySelector('eos-carousel');

carousel.play();
carousel.pause();
carousel.next();
carousel.prev();
carousel.goTo(2);
```

### Slots [#slots]

Use the default slot for any slide content:

```html
<eos-carousel autoplay loop interval="3000">
  <img src="/cover-01.jpg" alt="Mountain landscape" />
  <img src="/cover-02.jpg" alt="Coastal landscape" />
</eos-carousel>
```

### CSS custom properties [#css-custom-properties]

| Property | Default | Description |
| --- | --- | --- |
| `--carousel-height` | `400px` | Height of the carousel host |
| `--progress-bar-height` | `3px` | Indicator height in pixels |
| `--progress-bar-gap` | `3px` | Gap between indicators |
| `--progress-bar-color` | `rgba(255, 255, 255, 0.3)` | Inactive indicator color |
| `--progress-bar-active-color` | `rgba(255, 255, 255, 1)` | Active indicator color |
| `--control-bg` | `rgba(0, 0, 0, 0.3)` | Navigation control background |
| `--control-hover-bg` | `rgba(0, 0, 0, 0.5)` | Navigation control hover background |

### Framework integration [#framework-integration]

Carousel is a standard custom element. The same markup works in React, Vue, Angular, and native HTML; framework listeners receive the native DOM and CustomEvent APIs.

```html
<eos-carousel autoplay loop interval="3000">
  <div>Slide one</div>
  <div>Slide two</div>
</eos-carousel>
```


# Image (/llms.mdx/docs/components/image/content.md)

## Import [#import]

```ts
import '@eosjs/ui/image';
```

## Introduction [#introduction]

Image is a framework-agnostic Web Component for responsive media. It preserves the native image model while adding lazy loading, BlurHash placeholders, loading feedback, and explicit fallback states.

## Basic Usage [#basic-usage]

Use the controls in this example to inspect the supported image states and layout options.

<Demo id="components-image-demos-basic" of={Basic} source={BasicSource} title="Basic usage" layout="center" />

## Fallback [#fallback]

Use the `error` slot to provide recovery-oriented content when the image cannot be loaded.

<Demo id="components-image-demos-fallback" of={Fallback} source={FallbackSource} layout="center" />

## Responsive and circular images [#responsive-and-circular-images]

`responsive` lets the image follow the available inline size. `circle` clips the image to a circle while preserving the declared dimensions.

<Demo id="components-image-demos-responsive" of={Responsive} source={ResponsiveSource} layout="center" />

## API [#api]

<Api name="Image" />

### Attributes [#attributes]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | Image URL or BlurHash string |
| `src-type` | `url \| blurhash` | `url` | How to interpret `src` |
| `alt` | `string` | — | Alternative text for the image |
| `width` / `height` | `string` | — | Host dimensions; defaults to 100px and can be sized below 100px |
| `loading` | `lazy \| eager` | `eager` | Whether to wait for viewport visibility |
| `crossorigin` | `string` | — | Native cross-origin image setting |
| `object-fit` | `cover \| contain \| fill \| none \| scale-down` | `cover` | Native image fitting mode |
| `placeholder` | `string` | — | Placeholder URL or BlurHash |
| `placeholder-type` | `url \| blurhash` | `url` | How to interpret the placeholder |
| `placeholder-fill` | `boolean` | `false` | Keep the placeholder as a background layer |
| `show-delay` | `string` | `0` | Delay before revealing a loaded image, in milliseconds |
| `responsive` | `boolean` | `false` | Make the image follow its container width |
| `circle` | `boolean` | `false` | Clip the image to a circle |

### Events [#events]

`load` and `error` use native event names. `progress` is the component's structured network-progress event.

| Event | When it fires | `event.detail` |
| --- | --- | --- |
| `load` | The image is ready to display | — |
| `error` | The image failed to load | — |
| `progress` | Network data is received | `{ loaded, total, src }` |

### Slots [#slots]

```html
<eos-image src="/cover.jpg" style="width: 320px; height: 200px">
  <span slot="loading">Preparing image…</span>
  <span slot="error">Image unavailable</span>
</eos-image>
```


# Image Group (/llms.mdx/docs/components/image-group/content.md)

## Import [#import]

```ts
import '@eosjs/ui/image-group';
```

## Image Group [#image-group]

Use the image group for related images that belong to one visual collection. It delegates image rendering to eos-image while the group controls layout, focus, and count overflow.
The `grid` and `pair` layouts keep tiles square based on the rendered row count and center an incomplete last row. An empty group takes no layout space.
The default tile gap is 4px and the corner radius is 5px. Customize them with `--eos-image-group-gap` and `--eos-image-group-radius`.

<Demo id="components-image-group-demos-index" of={Basic} source={BasicSource} title="Image group layouts" layout="center" />

## API [#api]

### Properties [#properties]

<Api name="ImageGroup" from="./api.ts" />

Each item is rendered by `eos-image`; see [Image attributes](/components/image#attributes) for the complete image property reference.

### Events [#events]

| Event | When it fires | event.detail |
| --- | --- | --- |
| image-click | A tile is activated | index and item |


# Component catalog (/llms.mdx/docs/components/content.md)

EOS components are framework-agnostic custom elements. Each reference includes live examples and the public API available to your application.

## General [#general]

- [Button](/docs/components/button): actions with semantic variants, events, and CSS variable theming.
- [Select](/docs/components/select): searchable selection with four-side placement and virtualized options.

## Data display [#data-display]

- [Card Stack](/docs/components/card-stack): swipeable cards with reversible pointer-driven transitions.
- [Carousel](/docs/components/carousel): content navigation with indicators, touch gestures, and optional autoplay.
- [Image](/docs/components/image): responsive media with lazy loading, BlurHash, and loading states.
- [Image Group](/docs/components/image-group): compact, responsive collections of related images.
- [Scene](/docs/components/scene): a coordinate space for positioned overlays and interactive points.
- [Scrollbar](/docs/components/scrollbar): a custom scrollbar that can attach to an existing scroll container.

## Feedback [#feedback]

- [Progress Bar](/docs/components/progress-bar): segmented progress for steps, loading, and navigation.


# ProgressBar (/llms.mdx/docs/components/progress-bar/content.md)

## Introduction [#introduction]

ProgressBar represents progress across a finite number of segments. It supports horizontal and vertical placement, three visual variants, clickable segments, and imperative progress animation.

## Basic Usage [#basic-usage]

<Demo id="components-progress-bar-demos-index" of={Basic} source={BasicSource} title="Basic usage" layout="center" />

## API [#api]

<Api name="ProgressBar" />

### Attributes [#attributes]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `total` | `number` | `0` | Number of segments |
| `current` | `number` | `0` | Zero-based active segment index |
| `variant` | `default \| dots \| tiktok` | `default` | Visual style of the indicator |
| `position` | `top \| bottom \| left \| right` | `bottom` | Indicator orientation |
| `loading` | `boolean` | `false` | Show a loading animation on the active segment |
| `scrubbable` | `boolean` | `false` | Select the segment under the pointer when a drag is released |
| `aria-label` | `string` | `Progress` | Accessible name for the segment navigation |

### Methods [#methods]

```ts
import '@eosjs/ui/progress-bar'; // registers only this component

const progress = document.querySelector('eos-progress-bar');

progress.startProgress({
  duration: 3000,
  onComplete: () => console.log('segment complete'),
});
progress.setProgress(45);
progress.setLoading(true);
progress.stopProgress();

// External playback clock: no second RAF is started inside the component.
progress.segmentLabels = ['Start', 'Day one', 'Museum', 'Summary'];
progress.setState(2, 45); // segment index, percent in that segment
progress.setAttribute('scrubbable', '');
```

`setProgress()` and `setState()` stop the internal animation clock and retain the supplied fraction. Steady-state updates use the cached active fill and change only its transform. Changing `current` updates segment states; changing `total` rebuilds the segments. Moving the element between containers retains its nodes and progress.

Segments are native buttons. Arrow keys, Home and End move focus; Enter and Space select. `segmentLabels` supplies localized accessible labels. `getSegment(index)` exposes a button for tooltip anchoring or CSS parts; `getSegmentIndexAt(clientX, clientY)` resolves the nearest visible segment.


### Events [#events]

| Event | When it fires | `event.detail` |
| --- | --- | --- |
| `segment-click` | A segment is clicked, activated by keyboard, or selected on drag release | `{ index }` |

### CSS custom properties [#css-custom-properties]

| Property | Default | Description |
| --- | --- | --- |
| `--progress-bar-height` | `4px` | Segment height for horizontal indicators |
| `--progress-bar-gap` | `4px` | Gap between segments |
| `--progress-bar-color` | `var(--eos-color-border)` | Inactive segment color |
| `--progress-bar-active-color` | `var(--eos-color-accent)` | Active and completed segment color |
| `--progress-bar-hit-size` | `44px` | Pointer target height (width for vertical bars) |

CSS parts: `segment`, `track`, `fill`. Customize colors with the public properties; both light and dark semantic themes are supported. Dense playback navigation can reduce the hit size at the host while enabling scrubbing.

### Browser regression checks [#browser-regression-checks]

`packages/ui/tests/progress-bar.browser.js` is a browser expression for a page where EOS UI is registered. It checks first manual update, stable DOM under repeated updates, bounds, lifecycle, keyboard, pointer scrubbing, animation ownership and both themes. It leaves `#eos-progress-verification` for screenshot review; remove the fixture afterwards. The loop timing it returns measures synchronous API updates only, not frame rate or end-to-end rendering performance.

## Source Organization [#source-organization]

Following Button, Image, and CardStack, files are separated by responsibility:

- `progress-bar.ts`: state, lifecycle, native interaction, and animation.
- `progress-bar.css.ts`: exports `PROGRESS_BAR_STYLES` for theme tokens, variants, orientation, and reduced motion.
- `index.ts`: class export; `src/entries/progress-bar.ts` provides selective registration.

Styles are inserted when the shadow DOM is created. Progress updates reuse existing nodes without reinserting styles or rendering the template.


# Scene (/llms.mdx/docs/components/scene/content.md)

## Import [#import]

```ts
import '@eosjs/ui/scene';
```

## Basic usage [#basic-usage]

`eos-scene` provides a content area and a shared coordinate space for its `eos-scene-item` children. Items can contain any slotted content, such as markers, labels, cards, or masks.

<Demo id="components-scene-demos-index" of={Basic} source={BasicSource} title="Scene with multiple overlays" layout="center" />

Click a marker to open its callout. Click it again to close it. The example reuses the Litang landscape image from the Image docs. Use the external `+` and `−` buttons to scale the demo container, or drag the image to move it. The markers stay aligned to their image coordinates.

## Coordinates and resizing [#coordinates-and-resizing]

`x` and `y` are normalized coordinates from 0 to 1, with the origin at the top left of the scene. They are resolved against the scene's content area, so items remain aligned to the same relative point when the scene or its parent changes size or position. They do not depend on the document or viewport position. The demo controls apply transforms to an outer wrapper; `eos-scene` only provides the coordinate space.

When positioning items over an image, match the scene aspect ratio to the image content so `object-fit: cover` does not crop the coordinate space. `anchor` chooses which edge, corner, or center of an item aligns with its coordinate. Use `z-index` to order overlapping items.

## Attributes [#attributes]

### `eos-scene` [#eos-scene]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | string | `Scene content` | Accessible name for the scene content |

The scene also supports `--eos-scene-aspect-ratio` (default `16 / 9`) and `--eos-scene-radius` (default `16px`).

### `eos-scene-item` [#eos-scene-item]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `x` / `y` | number | `0.5` | Normalized scene coordinates from 0 to 1 |
| `anchor` | `center \| top-left \| top \| top-right \| right \| bottom-right \| bottom \| bottom-left \| left` | `center` | Align this edge, corner, or center to the coordinate |
| `z-index` | number | `1` | Stacking order among scene items |

Native events from buttons, links, and other slotted content keep their original event names and objects.


# Scrollbar (/llms.mdx/docs/components/scrollbar/content.md)

## Import [#import]

```ts
import '@eosjs/ui/scrollbar';
```

## Introduction [#introduction]

Scrollbar provides a consistent custom track and thumb for horizontal or vertical scrolling. Attach it to a native scroll container to keep the thumb synchronized, or drive it manually for virtualized content.

## Basic Usage [#basic-usage]

<Demo id="components-scrollbar-demos-index" of={Basic} source={BasicSource} title="Basic usage" layout="center" />

## API [#api]

<Api name="Scrollbar" />

### Attributes [#attributes]

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `horizontal \| vertical` | `horizontal` | Scroll direction |
| `auto-hide` | `boolean` | `false` | Fade out when the scrollbar is idle |
| `thumb-color` | `string` | `var(--eos-color-foreground-muted)` | Thumb color |
| `track-color` | `string` | `var(--eos-color-border)` | Track color |
| `thumb-size` | `string` | `6` | Thumb thickness in pixels |
| `thumb-min-size` | `string` | `30` | Minimum thumb length in pixels |
| `border-radius` | `string` | `3` | Track and thumb radius in pixels |

### Methods [#methods]

| Method | Description |
| --- | --- |
| `attach(element)` | Bind to a scrollable element |
| `detach()` | Remove the current binding |
| `setVirtualScroll(options)` | Set a virtual content size, viewport size, and offset |
| `clearVirtualScroll()` | Return to DOM-driven scrolling |

```ts
const scrollbar = document.querySelector('eos-scrollbar');

scrollbar.setVirtualScroll({
  contentSize: 100000,
  viewportSize: 600,
  scrollOffset: 1200,
});
```

### Events [#events]

| Event | When it fires | `event.detail` |
| --- | --- | --- |
| `scroll-change` | The scroll position changes | `{ position, ratio, scrollOffset? }` |

### Slots [#slots]

Scrollbar has no content slots. Place it adjacent to the scroll container it controls and call `attach(element)` after both elements are connected.


# Select (/llms.mdx/docs/components/select/content.md)

## Introduction [#introduction]

Select keeps its compact pill trigger in the form layout. When opened, its compass panel floats beside the trigger and automatically chooses the side with the most room. The pointer stays fixed on the selected row while the option list scrolls and snaps that row to the center.

The component is a native Web Component and can be used from React, Vue, Angular, or plain HTML. Its built-in positioning logic handles side selection, boundary collision, and position updates as the page scrolls or resizes. The component virtualizes long option lists and mounts only the visible rows plus a small overscan.

## Interactive example [#interactive-example]

This example contains 10,000 options. Use the placement controls to preview four compass layouts. The compact trigger stays centered in the preview; the panel is constrained by the page viewport and can extend beyond the demo card. **Restore** returns placement to automatic.

<Demo id="components-select-demos-index" of={Basic} source={BasicSource} title="Four side placement" layout="center" />

## Basic usage [#basic-usage]

```html
<eos-select id="country" aria-label="Country" placeholder="Choose a country"></eos-select>
```

```ts
import '@eosjs/ui/select'; // Register only Select

const select = document.querySelector('#country');
select.options = [
  { value: 'fr', label: 'France', prefix: '🇫🇷' },
  { value: 'de', label: 'Germany', prefix: '🇩🇪' },
  { value: 'it', label: 'Italy', prefix: '🇮🇹' },
  { value: 'jp', label: 'Japan', prefix: '🇯🇵' },
];
select.value = 'it';
select.addEventListener('change', (event) => {
  const { value, option } = event.detail;
  console.log(value, option.label);
});
```

## API [#api]

### Properties and attributes [#properties-and-attributes]

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `readonly EosSelectOption[]` | `[]` | Options with `value`, `label`, optional `prefix` and `disabled`. Set as a JavaScript property. |
| `value` | `string` | `''` | Selected option value. |
| `open` | `boolean` | `false` | Whether the floating panel is open. |
| `disabled` | `boolean` | `false` | Disables the trigger and selection. |
| `placeholder` | `string` | `Select an option` | Text shown before a value is selected. |
| `full-width` | `boolean` | `false` | Makes the trigger fill its containing block. |
| `placement` | `auto \| top \| right \| bottom \| left` | `auto` | Preferred floating panel side. `auto` chooses the side with the most available space. |
| `boundary` | `Element \| Element[] \| Rect` | Viewport | Optional collision boundary. Set it as a JavaScript property; multiple boundaries are intersected. |
| `aria-label` | `string` | `Select an option` | Accessible name for the combobox. |
| `aria-labelledby` | `string` | — | ID reference for an external visible label. |

### Events [#events]

| Event | Detail | Description |
| --- | --- | --- |
| `change` | `{ value: string, option: EosSelectOption }` | Fires when a different option is committed. It bubbles and is composed across the shadow boundary. |

### Keyboard interaction [#keyboard-interaction]

- `Enter` or `Space` opens the panel; while open, it commits the active option.
- Up/down placements use `ArrowLeft` / `ArrowRight`; left/right placements use `ArrowUp` / `ArrowDown`. Both keep the active option centered in the compass.
- `Home` and `End` move to the first or last enabled option.
- `Escape` closes the panel and returns focus to the trigger; `Tab` closes it while continuing normal focus movement.
- Typing characters searches option labels by prefix.

### Large option lists [#large-option-lists]

Options are stored as data, while only the visible viewport rows and three rows of overscan are rendered. The active or selected row snaps to the center after scrolling. Keep option values unique and provide stable labels. For datasets that change, replace the `options` property with the updated array.

### Placement and themes [#placement-and-themes]

The panel uses built-in positioning logic for automatic placement, preferred placement with fallback, viewport shifting, available-size constraints, live updates, and custom collision boundaries. Left/right placements use a vertical compass arc; top/bottom placements use a horizontal arc with a matching tick axis and virtual scroll direction. EOS keeps the pointer and selection capsule fixed at the compass center. The `placement` property requests a side; the component can fall back when there is insufficient room. Its default `auto` chooses the side with the most available space. The `boundary` property constrains collision handling to an element or rectangle. The trigger remains in normal layout, so opening the list does not push form content. Light and dark surfaces use EOS semantic theme tokens. Reduced-motion preferences shorten the transitions.

## Framework integration [#framework-integration]

Register the element once, then assign `options` as a property. In React, attach a native event listener in an effect; in Vue, use a template ref or listen to the composed `change` event. The component itself has no framework runtime dependency.

```tsx
import { useEffect, useRef } from 'react';
import '@eosjs/ui/select';

export function CountryField() {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    const select = ref.current;
    if (!select) return;
    select.options = [{ value: 'jp', label: 'Japan' }];
    const onChange = (event: Event) => {
      console.log((event as CustomEvent).detail.value);
    };
    select.addEventListener('change', onChange);
    return () => select.removeEventListener('change', onChange);
  }, []);

  return <eos-select ref={ref} aria-label="Country" />;
}
```


# Getting started (/llms.mdx/docs/getting-started/content.md)

## Installation [#installation]

Install the package with your preferred package manager:

```bash
npm install @eosjs/ui
yarn add @eosjs/ui
pnpm add @eosjs/ui
```

## Selective imports [#selective-imports]

Import the components used by each page. Entries register their elements and export component classes and public types:

```ts
import '@eosjs/ui/button';
import '@eosjs/ui/image';
import '@eosjs/ui/carousel';
import type { EosImageGroupItem } from '@eosjs/ui/image-group';
import type { CardStackRenderer } from '@eosjs/ui/card-stack';
```

| Entry | Automatically registered |
| --- | --- |
| `@eosjs/ui/button` | Button |
| `@eosjs/ui/card-stack` | CardStack |
| `@eosjs/ui/carousel` | Carousel, ProgressBar |
| `@eosjs/ui/image` | Image |
| `@eosjs/ui/image-group` | ImageGroup, Image |
| `@eosjs/ui/progress-bar` | ProgressBar |
| `@eosjs/ui/scrollbar` | Scrollbar |

Carousel and ImageGroup register internal dependencies. Slotted components must still be imported by the caller. Repeated imports and mixing selective imports with the root entry do not register elements twice. `@eosjs/ui/config` exports configuration without loading components.

`import '@eosjs/ui'` remains compatible and registers every component. Type-only imports do not register elements; `@eosjs/ui/jsx-types` is unchanged. Runtime entries are safe to import without a browser; element creation and rendering still happen on the client.

> These entries have not been published yet. Use a built, locally linked package for now; existing npm releases do not include the new entries.

## Framework integration [#framework-integration]

### React [#react]

```tsx
import { useEffect, useRef } from "react";
import "@eosjs/ui";

export function App() {
  const buttonRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const button = buttonRef.current;
    const onClick = (event: Event) => console.log("Clicked:", event);
    button?.addEventListener("click", onClick);
    return () => button?.removeEventListener("click", onClick);
  }, []);

  return <eos-button ref={buttonRef}>Try the button</eos-button>;
}
```

### Vue 3 [#vue-3]

```vue
<template>
  <eos-button @click="handleClick">Try the button</eos-button>
  <eos-carousel autoplay loop :interval="3000">
    <div>Slide one</div>
    <div>Slide two</div>
  </eos-carousel>
</template>

<script setup>
import '@eosjs/ui';

const handleClick = (event) => console.log('Clicked:', event);
</script>
```

### Angular [#angular]

In Angular, add `CUSTOM_ELEMENTS_SCHEMA` to use EOS custom elements:

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import "@eosjs/ui";

@Component({
  selector: "app-root",
  template: `
    <eos-button>Try the button</eos-button>
    <eos-carousel autoplay loop [attr.interval]="3000">
      <div>Slide one</div>
      <div>Slide two</div>
    </eos-carousel>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppComponent {}
```

### Native HTML [#native-html]

```html
<script type="module">
  import "@eosjs/ui";

  document.querySelector("eos-button").addEventListener("click", (event) => {
    console.log("Clicked:", event);
  });
</script>

<eos-button>Try the button</eos-button>
<eos-carousel autoplay loop interval="3000">
  <div>Slide one</div>
  <div>Slide two</div>
</eos-carousel>
```

## Component methods and events [#component-methods-and-events]

```ts
const carousel = document.querySelector("eos-carousel");
carousel.play();
carousel.pause();
carousel.next();
carousel.prev();
carousel.goTo(2);

carousel.addEventListener("change", (event) => {
  console.log("Current index:", event.detail.currentIndex);
});
```

## Styling [#styling]

Components expose EOS semantic CSS variables for host-level customization:

```css
eos-button {
  --eos-color-accent: #006fee;
  --eos-color-accent-hover: #338af3;
  --eos-color-accent-foreground: #fcfcfc;
  --eos-color-focus-ring: #006fee;
}
```


# EOS UI Documentation (/llms.mdx/docs/content.md)

# EOS UI Documentation [#eos-ui-documentation]

Explore the EOS UI components and guides.

[Get started](/docs/getting-started): install EOS UI and build your first interface.


# llms.txt (/llms.mdx/docs/llms/content.md)

The <a href="/llms.txt" target="_blank" rel="noreferrer">raw llms.txt</a> file lists available guides and component references. It is also linked from the [skills.md agent guide](/docs/skills).

## Machine-readable documentation [#machine-readable-documentation]

- [llms.txt](/llms.txt): compact index of guides and components.
- <a href="/llms-full.txt" target="_blank" rel="noreferrer">llms-full.txt</a>: all published component documentation in one response.
- [Markdown component references](/llms.mdx/docs/components/content.md): one page per guide or component.

For Chinese references, use the localized index at <a href="/zh/llms.txt" target="_blank" rel="noreferrer">llms.txt</a>.


# Playground (/llms.mdx/docs/playground/content.md)

## Component playground [#component-playground]

Use the component pages to interact with live examples, inspect source code, and switch the preview appearance.

- [Button](/docs/components/button)
- [Carousel](/docs/components/carousel)

Each demo is rendered by the shared EOS `Demo` component, which keeps the preview boundary stable while the surrounding Fumadocs page changes.


# skills.md (/llms.mdx/docs/skills/content.md)

The <a href="/skills.md" target="_blank" rel="noreferrer">raw skills.md</a> file gives coding agents a short workflow for using EOS UI. The entry is also available in Chinese at <a href="/zh/skills.md" target="_blank" rel="noreferrer">skills.md</a>.

## Recommended workflow [#recommended-workflow]

1. Find a component in the [LLM documentation index](/llms.txt).
2. Read its Markdown reference for attributes, events, methods, and examples.
3. Check the [getting started guide](/docs/getting-started) before importing components.
4. Use EOS semantic tokens and support both Light and Dark themes.
5. Respect keyboard access and reduced-motion preferences.

Use [llms.txt](/llms.txt) for the component index or <a href="/llms-full.txt" target="_blank" rel="noreferrer">llms-full.txt</a> when you need all references together.


# Documentation example (/llms.mdx/docs/test/content.md)

# Documentation example [#documentation-example]

This page verifies that the EOS documentation content pipeline is working.