---
url: https://rsmple.github.io/eco-vue-js/guide/getting-started.md
description: >-
  Install eco-vue-js, wire Tailwind v4, vue-query and the global containers
  (modals, notifications, tooltips), and import components.
---

# Getting started

## Install

```sh
npm i eco-vue-js @tanstack/vue-query
```

Peer dependencies: `vue` ≥ 3.5, `@tanstack/vue-query` ≥ 5. `vue-router` is optional — only needed for components that take a `to` prop.

## Styles

The kit ships Tailwind v4 classes, not compiled CSS. Import its Tailwind base right after Tailwind in your app's stylesheet — it adds the theme tokens, variants and plugins, and registers the kit's components as a Tailwind source:

```css
@import "tailwindcss";
@import "eco-vue-js/tailwind-base/base.css";
```

Dark mode follows a `dark` class on an ancestor (usually `<html>`). Colors, fonts and field sizes are CSS variables — see [Theming](./theming) to change them.

### Markdown

Rendered markdown is styled inside a `.w-markdown` container: headings, lists, tables, inline code, and code blocks with numbered `.line`s. Sizes are in `em`, so the content follows the container's font size, and colors come from the color roles. Import it after the base:

```css
@import "eco-vue-js/tailwind-base/markdown.css";
/* Optional: GitBook blocks — hints, colored text, expandable sections, embedded videos */
@import "eco-vue-js/tailwind-base/css/markdown/blocks.css";
```

Add `enable-mobile` to the container to keep text on the page's inner margin below `sm` while code blocks and tables reach the screen edges, or `w-report` for print: code wraps and lines don't highlight on hover.

## Query client

List, select and async components fetch through `@tanstack/vue-query`. Install the plugin and hand the same client to the kit, so model actions running outside `setup` can reach it:

```ts
import {QueryClient, VueQueryPlugin} from '@tanstack/vue-query'
import {defaultQueryRetry, setQueryClient} from 'eco-vue-js/dist/utils/queryClient'

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {retry: defaultQueryRetry},
  },
})

setQueryClient(queryClient)

app.use(VueQueryPlugin, {queryClient})
```

`defaultQueryRetry` retries a query twice when asking again may help: the server was unreachable, answered 5xx, 408 or 429. Other 4xx, cancelled requests and errors thrown by the query function fail at once. A query that must skip more composes it with `isRetryableError` or the same function:

```ts
options: {
  retry: (failureCount, error) => error.response?.status !== 504 && defaultQueryRetry(failureCount, error),
}
```

The queries themselves are declared per model — see [Data layer](/guide/data-layer).

## App layout

Sticky list headers and columns, full-width rows, dropdowns and modals position themselves from a few CSS variables that describe the app's frame. Set them on `body`, with the values your header and side bars actually take at each breakpoint — all default to `0px`:

```css
body {
  --header-height: 3.5rem;
  --nav-bar-width: 0px;
  --actions-bar-width: 0px;
  --inner-margin: 1rem;

  @apply sm:[--actions-bar-width:3.5rem] xl:[--nav-bar-width:15rem];
}
```

[App shell](./app-shell) explains each variable and sets up the header, nav and actions bars around the content.

## Global containers

Modals, menus, notifications and tooltips render into containers mounted once at the root of the app — `WModal` renders the modals and every `WButtonMore` menu. `WShineEffect` is optional: it drives the moving shine on action buttons. `WNotify` shows the toasts; their history opens from `WNotifyCenterButton` in the actions bar (see [Notify](/components/notify#notify-center)). `WQueryStatus` shows one message with Retry when queries on screen fail to load (see [Query status](/components/query-status)).

```vue
<template>
  <RouterView />

  <WTooltipContainer />
  <WNotify />
  <WQueryStatus />
  <WModal />
  <WShineEffect />
</template>

<script setup lang="ts">
import WModal from 'eco-vue-js/dist/components/Modal/WModal.vue'
import WNotify from 'eco-vue-js/dist/components/Notify/WNotify.vue'
import WQueryStatus from 'eco-vue-js/dist/components/QueryStatus/WQueryStatus.vue'
import WShineEffect from 'eco-vue-js/dist/components/Shine/WShineEffect.vue'
import WTooltipContainer from 'eco-vue-js/dist/components/Tooltip/WTooltipContainer.vue'
</script>
```

## Texts

A few texts the components show on their own are in English: the Back, Next, Close, Cancel and submit buttons of a stepper, a confirm's Cancel and Accept, the question before a modal with unsaved changes closes, the warning about invalid fields, the From and To of a date picker, No data on an empty chart, the error and Retry of a list page, a [query boundary](/components/query-boundary) or the [query status](/components/query-status), and the heading, messages and buttons of a [page error](/components/page-error). Replace them once, before the app mounts. A getter is read as the text renders, so a translation follows the locale:

```ts
import {setTexts} from 'eco-vue-js/dist/utils/texts'

setTexts({
  back: () => i18n.global.t('modal.back'),
  next: () => i18n.global.t('modal.next'),
  close: () => i18n.global.t('modal.close'),
  cancel: () => i18n.global.t('modal.cancel'),
})
```

A prop such as `submitText` or a confirm's `acceptText` still names its own button.

Dates, times, durations and numbers are formatted in `en-GB` until `setLocale` sets another locale — see [Formatting](/utilities/formatting#dates):

```ts
import {setLocale} from 'eco-vue-js/dist/utils/locale'

setLocale(() => i18n.global.locale.value)
```

## Importing

Import each component, utility and icon by its own path — there is no barrel import:

```ts
import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import {Notify} from 'eco-vue-js/dist/utils/Notify'
import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'
```

See [Conventions](./conventions) for the patterns the rest of the docs assume.

## AI assistants

The package carries these docs as Markdown, for the version it is: point an assistant at `node_modules/eco-vue-js/docs/llms.txt`, for example with a line in the app's `CLAUDE.md` or `AGENTS.md`:

```md
UI kit docs: node_modules/eco-vue-js/docs/llms.txt — read the page for a component before using it.
```

This site also serves them for the latest version: [llms.txt](https://rsmple.github.io/eco-vue-js/llms.txt) indexes every page, and [llms-full.txt](https://rsmple.github.io/eco-vue-js/llms-full.txt) has all of them in one file.

## Eslint config

The package also ships the shared eslint config used by its consumers:

```js
import plugin from 'eco-vue-js/eslint/plugin'

export default [
  ...plugin.configs.recommended({
    tsConfig: ['tsconfig.node.json', 'tsconfig.vue.json'],
  }),
]
```

---

---
url: https://rsmple.github.io/eco-vue-js/guide/app-shell.md
description: >-
  Set up the frame of an eco-vue-js app with WNavBar, WHeaderBar and WActionsBar
  — the CSS variables that describe the fixed bars, the content padding, filters
  and search in the bars, dark mode and a centred layout.
---

# App shell

Kit apps share one frame: a fixed header on top (`WHeaderBar`), a nav on the left (`WNavBar`) and an actions bar on the right (`WActionsBar`), with the page content between them. The bars are `position: fixed` and don't push anything aside — the app describes the frame in a few CSS variables, pads its content by them, and every component that needs to know where the content box is (sticky list headers and columns, full-width rows, dropdowns, modals) reads the same variables.

This site is built that way: its layout is [`DocsLayout.vue`](https://github.com/rsmple/eco-vue-js/blob/main/docs/.vitepress/theme/DocsLayout.vue) and its shell styles are at the top of [`style.css`](https://github.com/rsmple/eco-vue-js/blob/main/docs/.vitepress/theme/style.css).

## Frame variables

Set them on `body`. Each one is the space a part of the frame takes *in layout* at the current breakpoint, so all default to `0px`:

| Variable | What it is |
| --- | --- |
| `--header-height` | Height of the header. |
| `--nav-bar-width` | Space taken by the nav — `0px` below `xl`, where the nav is an overlay opened from the header. |
| `--actions-bar-width` | Space taken by the actions bar — `0px` on phones, where it is hidden. |
| `--inner-margin` | Horizontal padding of the content. |
| `--left-margin`, `--right-margin` | Space outside the frame when it is centred on a wide screen — see [Centred frame](#centred-frame). |
| `--w-actions-bar-width` | Width of the actions bar itself, at every breakpoint. |
| `--actions-bar-filter-width` | Width of the filter panel that slides out of the actions bar on `sm` and up — see [Filters](#filters-and-search). |

The bars' own widths come from two theme tokens, so they are also Tailwind sizes: the nav's content uses `w-nav-bar-width` to keep its width while the nav collapses.

```css
@import "tailwindcss";
@import "eco-vue-js/tailwind-base/base.css";

@theme {
  --spacing-nav-bar-width: 15rem;
  --spacing-actions-bar-width: 3.5rem;
}

body {
  --header-height: 3.5rem;
  --nav-bar-width: 0px;
  --actions-bar-width: 0px;
  --inner-margin: 1rem;
  --w-actions-bar-width: var(--spacing-actions-bar-width);
  --actions-bar-filter-width: 24rem;

  @apply
    bg-surface text-accent
    sm:[--inner-margin:1.5rem]
    sm:[--actions-bar-width:var(--spacing-actions-bar-width)]
    xl:[--nav-bar-width:var(--spacing-nav-bar-width)];
}

/* The bars have no background of their own: the class is a hook for the app's surface. */
.w-nav-bar {
  @apply bg-surface shadow-md xl:shadow-none;
}

.w-actions-bar {
  @apply bg-surface shadow-md sm:shadow-none;
}
```

The breakpoints aren't a free choice: `WNavBar` docks from `xl` (1280px) and turns into an overlay below it, and `useIsMobile()` reports `isMobile` below `sm` (640px) and `isTablet` below `xl` — the same widths the variables switch at.

### The content box

From the frame variables the kit derives the content box on every element, and exposes each as a Tailwind size:

| Variable | Utility size | Value |
| --- | --- | --- |
| `--w-left-inner` | `---left-inner` | Left edge of the content: left margin + nav + inner margin. |
| `--w-right-inner` | `---right-inner` | The same on the right, with the actions bar. |
| `--w-width-inner` | `---width-inner` | Width of the content: `100vw` minus both. |
| `--w-top-inner` | — | Header height plus the height of a sticky list header above. |
| `--w-height-inner` | `---height-inner` | Height left under them. |

The frame variables are sizes too: `pt---header-height`, `pl---nav-bar-width`, `px---inner-margin`. Inside a modal, the modal replaces the content box with its own, so the same classes work there.

An element that should stay in view while a wide list scrolls sideways sticks to the content's left edge and takes its width — the search input in the [list recipe](../recipes/list-with-fields) does this:

```vue
<WInput class="sticky left---left-inner w---width-inner" />
```

## Layout component

The root layout mounts the three bars and pads the content by the frame:

```vue
<template>
  <WNavBar @update:is-open="isNavOpen = $event">
    <div class="w-nav-bar-width no-scrollbar h-full overflow-y-auto overscroll-contain">
      <WNavItem
        to="/projects"
        title="Projects"
        :icon="markRaw(IconFolder)"
      />

      <WNavItem
        to="/settings"
        title="Settings"
        :icon="markRaw(IconSettings)"
      />
    </div>
  </WNavBar>

  <WHeaderBar
    :title="title"
    class="pl---nav-bar-width pr---actions-bar-width"
  />

  <main class="pt---header-height pl---left-inner pr---right-inner">
    <RouterView />
  </main>

  <Transition
    enter-active-class="transition-[translate]"
    leave-active-class="transition-[translate]"
    enter-from-class="translate-x-full"
    leave-to-class="translate-x-full"
  >
    <WActionsBar v-if="!isMobile || isNavOpen">
      <template #top>
        <WButtonAction
          to="/projects/new"
          title="New project"
          :icon="markRaw(IconAdd)"
        />
      </template>

      <template #footer>
        <WToggleTheme
          v-model="theme"
          center
          class="mb-4"
        />
      </template>
    </WActionsBar>
  </Transition>
</template>

<script setup lang="ts">
import {markRaw, ref, watch} from 'vue'
import {RouterView} from 'vue-router'

import {useIsMobile} from 'eco-vue-js/dist/utils/mobile'
import {Theme} from 'eco-vue-js/dist/utils/utils'

import WActionsBar from 'eco-vue-js/dist/components/ActionsBar/WActionsBar.vue'
import WButtonAction from 'eco-vue-js/dist/components/Button/WButtonAction.vue'
import WHeaderBar from 'eco-vue-js/dist/components/HeaderBar/WHeaderBar.vue'
import WNavBar from 'eco-vue-js/dist/components/Nav/WNavBar.vue'
import WNavItem from 'eco-vue-js/dist/components/Nav/WNavItem.vue'
import WToggleTheme from 'eco-vue-js/dist/components/Toggle/WToggleTheme.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'
import IconFolder from 'eco-vue-js/dist/assets/icons/IconFolder'
import IconSettings from 'eco-vue-js/dist/assets/icons/IconSettings'

defineProps<{
  title?: string
}>()

const {isMobile} = useIsMobile()

const isNavOpen = ref(false)

const theme = ref(Theme.LIGHT)

watch(theme, value => document.documentElement.classList.toggle('dark', value === Theme.DARK), {immediate: true})
</script>
```

What each part does:

* **[`WNavBar`](/components/nav-bar)** docks at `xl`. Below it, it collapses and adds a menu button in the header's top-left corner — the header leaves that corner free on its own. It emits `update:is-open` when the overlay opens or closes.
* **[`WHeaderBar`](/components/header-bar)** spans the whole width; the `pl`/`pr` classes keep its title and buttons between the bars. The title is the `title` prop or the `#title` slot, and the `#right` slot goes before the search button.
* **[`WActionsBar`](/components/actions-bar)** holds icon buttons: `WButtonAction` in the `#top` and `#bottom` slots, with `to` for routes or `tag="a"` with `href` for links, and settings in `#footer`. On phones it is off-screen, so it slides in together with the open nav.
* **Dark mode** is a `dark` class on an ancestor, usually `<html>`. [`WToggleTheme`](/components/toggle#theme-toggle) only switches a `Theme` value — applying and persisting it is up to the app.

## Filters and search

Pages put their own content into the bars without touching the layout:

* **[`WActionsBarFilter`](/components/actions-bar#filters)** — its default slot becomes a filter panel that slides out of the actions bar, and the bar gets a filter button with the `count` prop as its badge. The panel is `--actions-bar-filter-width` wide from `sm` up, and covers the screen next to the bar on phones.
* **[`WHeaderBarSearch`](/components/header-bar#search)** — its default slot is shown in place of the header's title row, and the header gets a search button that opens it. The slot receives `visible`, `show` and `hide`; the `shown` prop opens it right away.

Both render nothing where they are placed, and remove their content from the bar when the page unmounts.

```vue
<template>
  <WActionsBarFilter :count="activeFilterCount">
    <ProjectFilters v-model="filters" />
  </WActionsBarFilter>

  <WHeaderBarSearch>
    <template #default="{hide}">
      <WInput
        v-model="search"
        type="search"
        no-margin
        @blur="hide"
      />
    </template>
  </WHeaderBarSearch>

  <WList ... />
</template>
```

## Pages without a bar

Everything measures from inherited variables, so a route without a bar only needs the bar left out and its variable reset on an element that wraps the header and the content — for a page with no actions bar, `[--actions-bar-width:0px]`. The header and every component inside then use the full width.

## Centred frame

On very wide screens the frame can keep a maximum width and centre itself. Set the space outside it as `--left-margin` and `--right-margin`: `WNavBar` and `WActionsBar` offset themselves by them, and `---left-inner` and `---right-inner` already include them. The header needs them added to its padding:

```css
@theme {
  --spacing-frame-max-width: 92rem;
}

body {
  --left-margin: max(0px, (100vw - var(--spacing-frame-max-width)) / 2);
  --right-margin: var(--left-margin);
}
```

```vue
<WHeaderBar class="pl-[calc(var(--left-margin)+var(--nav-bar-width))] pr-[calc(var(--right-margin)+var(--actions-bar-width))]" />
```

---

---
url: https://rsmple.github.io/eco-vue-js/guide/conventions.md
description: >-
  Rules every eco-vue-js consumer follows — import paths, markRaw for component
  props, inherited disabled/readonly/skeleton state, semantic types, and typing
  list extension components.
---

# Conventions

These patterns hold across the whole kit. Most mistakes when using it come from breaking one of them.

## Import by path

Components live at `eco-vue-js/dist/components/<Folder>/<Name>.vue`, their types at `eco-vue-js/dist/components/<Folder>/types`, utilities at `eco-vue-js/dist/utils/<file>` and icons at `eco-vue-js/dist/assets/icons/<IconName>` (no extension).

```ts
import type {FieldProps} from 'eco-vue-js/dist/components/List/types'
import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import IconEdit from 'eco-vue-js/dist/assets/icons/IconEdit'
```

## Wrap components passed as props in `markRaw`

Props that take a component — icons, list fields, menus, bulk actions, option components — expect a raw component, so Vue does not make it reactive:

```vue
<WButtonMoreItem
  text="Edit"
  :icon="markRaw(IconEdit)"
/>
```

## Disabled, readonly and skeleton are inherited

Inputs and buttons read `disabled`, `readonly` and `skeleton` from the nearest parent that provides them with `useProvideDisabled`, `useProvideReadonly` or `useProvideSkeleton` from `eco-vue-js/dist/utils/provide` when the prop is left unset. A [form](/components/form) passes its states to its fields through the scope instead. Only pass the prop to override the inherited state — passing `false` forces the control enabled even inside a disabled form.

## Semantic types, not colors

Components take a `semanticType` (`primary`, `secondary`, `positive`, `negative`, `warning`, `info`) from `eco-vue-js/dist/utils/SemanticType` instead of color classes. The classes behind each type are set once per app with the `setSemanticType*Map` functions, which is how an app rebrands the kit.

## Type list extensions with the kit's types

Components plugged into `WList` — fields, menus, bulk actions, filters — must declare their props with the kit's types instead of restating the shape. When the kit adds a prop, a restated shape silently drifts and breaks on the next upgrade:

```ts
import type {MenuEmits, MenuProps} from 'eco-vue-js/dist/components/List/types'

defineProps<MenuProps<Plant>>()
defineEmits<MenuEmits<Plant>>()
```

See the [List with fields](../recipes/list-with-fields) recipe for the full pattern.

---

---
url: https://rsmple.github.io/eco-vue-js/guide/data-layer.md
description: >-
  Fetch data for the kit's lists and selects — ApiClientInstance for requests
  and auth, createRestModelApi for a model's queries and actions that keep every
  cached copy in sync, list filters kept in the URL, and handleApiError for
  failed requests.
---

# Data layer

Lists, infinite lists and async selects don't fetch anything themselves. They take a query hook — `useQueryFn` — and call it for each page or lookup. The kit's data utilities build those hooks on top of `@tanstack/vue-query`:

* `ApiClientInstance` sends the requests and handles auth.
* `createRestModelApi` declares a model's queries and the actions that change it, keeping every cached copy of an item in sync.
* `createUseQueryParams` keeps the filters a user sets on a list in the URL.
* `handleApiError` reports a failed request in a notification and in the form that sent it.

The [query client](/guide/getting-started#query-client) has to be installed first.

## API client

One client per backend, in its own module:

```ts
import {ApiClientInstance} from 'eco-vue-js/dist/utils/ApiClient'

export const apiClient = new ApiClientInstance({
  baseUrl: '/api/v1',
  refreshUrl: '/jwt/update/',
  credentials: import.meta.env.DEV ? 'include' : 'same-origin',
})
```

`get`, `post`, `patch` and `delete` resolve with `{data, status}` and take a config with:

* `params` — the query string. Arrays of ids or strings are joined with commas, objects are sent as JSON, and empty values are left out.
* `signal` — pass the one vue-query gives the query function, so a query that is no longer needed cancels its request.
* `noAuth` — sends the request without an auth check, e.g. for the login.

URLs start and end with a slash — `/products/` or `` `/products/${ id }/` `` — and are typed that way. `addInstance(baseUrl)` gives a client for another prefix that shares the auth.

A failed request rejects with an `ApiError`, whose `response` has the `status` and the error body in `data`. A cancelled one rejects with `ApiErrorCancel`, which error handlers skip. When the server can't be reached, or a gateway answers 502, 503 or 504 in its place, the request rejects with `ApiErrorUnavailable`, a subclass of `ApiError` with no `status` for a network failure.

`useAvailable()` returns a ref that turns false on such a failure and true again on the server's next answer. Hand it to `watchServerRecovery`, with a cheap request as the probe, to bring back what failed during an outage. vue-query's `refetchOnReconnect` only follows the browser's own connection, so it never notices a server coming back:

```ts
import {watchServerRecovery} from 'eco-vue-js/dist/utils/queryClient'

watchServerRecovery(queryClient, apiClient.useAvailable(), () => apiClient.get('/profile/'))
```

While the server is unreachable, the probe is sent every few seconds, and at once when the browser comes back online or the tab is shown. Once the server answers again, the failed queries on screen are fetched again. Their error states, such as a list's Retry, a [page error](/components/page-error) or the [query status](/components/query-status) message, stay in place until then. A probe answered right away means the server is up and only some endpoints fail, so their queries wait for Retry instead of being fetched again and again.

### Auth

The client supports two kinds of auth:

* **Cookie session** (the default). The server sets an `exp` cookie, readable from JS, with the session's expiry in seconds. Before each request the client checks it. Once it has passed, the client calls `refreshUrl` — or your own `tokenRefresh` — and then sends the request. A 401 also refreshes and retries once, except for requests sent with `noAuth`. A refresh that fails with `ApiErrorUnavailable` keeps the session and rejects the request; any other failed refresh logs out. Open tabs share the refresh, so only one of them calls the server. Without an `exp` cookie the client counts as logged out and rejects every request not sent with `noAuth`.
* **Bearer token.** With `tokenGetter`, the client adds `Authorization: Bearer <token>` to each request and counts as logged out when it returns nothing.

`useAuth()` returns a ref of the logged-in state, for a guard that shows the login page. `logout()` clears the session. `onFailure`, or `setOnFailure` later, is called with every failed response, e.g. to redirect on 403.

## Models

`createRestModelApi` declares every query of one model — an item, a paginated list, a list of options, a settings object — together with the actions that change it:

```ts
import {createRestModelApi} from 'eco-vue-js/dist/utils/restModelApi'
import {isId} from 'eco-vue-js/dist/utils/utils'

import {apiClient} from '@/api/ApiClient'

const PRODUCT_PATH = '/products/'

export const productModelApi = createRestModelApi({
  modelKey: 'Product',
  model: {} as Product,
  queries: {
    item: {
      scope: 'item',
      dataType: {} as Product,
      isQueryParams: isId,
      queryFn: ({queryKey, signal}) => apiClient
        .get<Product>(`${ PRODUCT_PATH }${ queryKey[2] }/`, {signal})
        .then(response => response.data),
    },

    paginated: {
      scope: 'paginated',
      dataType: {} as PaginatedResponse<Product>,
      isQueryParams: (value: unknown): value is QueryParamsProducts | undefined => value === undefined || value instanceof Object,
      queryFn: ({queryKey, signal}) => apiClient
        .get<PaginatedResponse<Product>>(PRODUCT_PATH, {signal, params: queryKey[2]})
        .then(response => response.data),
    },
  },
})
```

* `modelKey` names the model in the cache. Every query of the model is keyed under it, so all of them can be updated or invalidated together.
* `model` is the shape that every query of the model shares, and must have an `id`. It is used only for its type, so pass `{} as Product`.

Each query has:

* `scope` — what the query holds: `item` (one item), `list` (an array of items), `paginated` (a page, in `PaginatedResponse`), or `single` (anything else, such as settings). The first three hold items with an `id`, and actions keep them in sync. A `single` query is left alone.
* `isQueryParams` — a type guard for the query's params. Without it the query takes no params. The query only runs when its params pass the guard, so `isId` holds back an item query until there is an id. A guard that accepts `undefined` also takes `{}`, and both share one cache entry.
* `queryFn` — fetches the data. Its params are at `queryKey[2]`.
* `dataType` — the type of the query's data, again as `{} as Type`. Declare it whenever `queryFn` reads `queryKey`, and whenever a query returns a richer shape than `model`, such as the full item where the list returns a short one.
* `options` — default vue-query options for the query, e.g. `placeholderData`.

The query's name is the last part of its key. Several queries of one scope, such as two paginated endpoints with different filters, don't collide.

### Using the queries

Every query gives a hook at `<name>.use`:

```ts
const queryProduct = productModelApi.item.use(computed(() => props.productId ?? 0))
```

* `use(params, options?)` — runs the query and returns the vue-query result, with `setItem` and `removeItem` added. `params` can be a ref, and a change runs the query for the new params.
* `use.config(params)` — the query's options, for `queryClient.ensureQueryData` or `prefetchQuery` outside of a component.
* `use.setItem(item)` and `use.removeItem(id)` — write to the cache without a component.

The `use` of a `paginated` query is what [WList](/components/list), [WInfiniteList](/components/infinite-list) and the async [selects](/components/select) take as `useQueryFn`. When a row changes, the list's `setter` calls `setItem`, which updates the item in every cached query of the model.

### Actions

Actions are the requests that change the model, declared on the query they belong to:

```ts
item: {
  scope: 'item',
  // …
  actions: {
    update: ({set, invalidate}, id, payload: Partial<Product>) => apiClient
      .patch<Product>(`${ PRODUCT_PATH }${ id }/`, payload)
      .then(response => {
        set(response.data)
        invalidate('paginated')

        return response.data
      }),

    delete: (context, id) => apiClient
      .delete(`${ PRODUCT_PATH }${ id }/`)
      .then(() => () => null),
  },
},
```

They are called as `<name>.actions.<action>(params, payload)`, where `params` is left out for a query without them:

```ts
await productModelApi.item.actions.update(product.id, {name})
```

An action gets its query's params, its payload, and a context to change the cache with:

* `set(item)` — puts the item, or an array of items, in every cached query of the model that holds it — items, lists and pages alike. On an `item` query it also sets that query's data.
* `update(item => newItem)` — changes the cached items the action is about. On an `item` query that is the item with the id in the params. On a `list` or `paginated` query it is the items its bulk params select: `id__in`, or `id__not_in` and `slice_indexes` against the loaded pages with the same filters. Return `null` to remove an item. Call it before the request for an optimistic update: when the action rejects, the model's cache is restored.
* `invalidate(scope?)` — refetches the model's queries of that scope, or all of them, once the action succeeds.

An action can also return an updater instead of calling `update`, and it then resolves with nothing. `() => null` above drops the deleted product from every list. For another model, use its `invalidate(scope?)`, e.g. to refresh a dashboard after a product is added.

In the demo, the toggle's action changes the task at once, in both the list and the detail. Turn on failing requests to see the change rolled back.

```vue
<template>
  <div class="grid gap-6">
    <div class="grid gap-6 md:grid-cols-2">
      <div class="grid content-start gap-1">
        <span class="text-description text-sm">taskModelApi.paginated</span>

        <button
          v-for="task in queryTasks.data.value?.results"
          :key="task.id"
          class="flex items-center gap-2 rounded-lg px-2 py-1 text-left [&_svg]:square-4"
          :class="{'bg-surface-muted': task.id === selected}"
          @click="selected = task.id"
        >
          <WStatusIcon :has-value="task.done" />
          {{ task.title }}
        </button>

        <WSkeleton
          v-for="index in queryTasks.data.value ? 0 : 4"
          :key="index"
        />
      </div>

      <div class="grid content-start gap-3">
        <span class="text-description text-sm">taskModelApi.item</span>

        <span class="font-semibold">
          <WSkeleton v-if="!queryTask.data.value" />

          <template v-else>
            {{ queryTask.data.value.title }}
          </template>
        </span>

        <WToggle
          :model-value="queryTask.data.value?.done ?? false"
          title="Done"
          :skeleton="!queryTask.data.value"
          @update:model-value="toggle"
        />
      </div>
    </div>

    <div class="flex flex-wrap items-center gap-4">
      <WToggle
        v-model="server.fail"
        title="Requests fail"
      />

      <span
        v-if="error"
        class="tone-negative text-tone text-sm"
      >
        {{ error }}
      </span>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'
import WStatusIcon from 'eco-vue-js/dist/components/Status/WStatusIcon.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

import {server, taskModelApi} from './api/Task'

const selected = ref(1)
const error = ref<string>()

const queryTasks = taskModelApi.paginated.use({})
const queryTask = taskModelApi.item.use(selected)

const toggle = (done: boolean) => {
  error.value = undefined

  taskModelApi.item.actions.update(selected.value, {done})
    .catch(() => error.value = 'The update failed and was rolled back.')
}
</script>
```

The model behind it, with a stand-in for the server:

```ts [Task.ts]
import {reactive} from 'vue'

import {createRestModelApi} from 'eco-vue-js/dist/utils/restModelApi'
import {paginateList} from 'eco-vue-js/dist/utils/useDefaultQuery'
import {isId} from 'eco-vue-js/dist/utils/utils'

export type Task = {
  id: number
  title: string
  done: boolean
}

export type QueryParamsTasks = {
  page?: number
}

let tasks: Task[] = [
  {id: 1, title: 'Repot the monstera', done: false},
  {id: 2, title: 'Prune the roses', done: true},
  {id: 3, title: 'Sow the tomato seeds', done: false},
  {id: 4, title: 'Clean the greenhouse gutters', done: false},
]

/** Lets the demo make every request fail, to show the rollback. */
export const server = reactive({fail: false})

/** Stands in for a request to the API: answers after half a second, or fails. */
const respond = <Data>(handler: () => Data) => new Promise<Data>((resolve, reject) => {
  setTimeout(() => {
    if (server.fail) reject(new Error('Server error'))
    else resolve(structuredClone(handler()))
  }, 500)
})

export const taskModelApi = createRestModelApi({
  modelKey: 'Task',
  model: {} as Task,
  queries: {
    item: {
      scope: 'item',
      dataType: {} as Task,
      isQueryParams: isId,
      queryFn: ({queryKey}) => respond(() => tasks.find(task => task.id === queryKey[2])!),
      actions: {
        update: ({update, set}, id, payload: Partial<Task>) => {
          // Shows the change at once, in every cached query holding the task. Rolled back if the request fails.
          update(task => ({...task, ...payload}))

          return respond(() => {
            tasks = tasks.map(task => task.id === id ? {...task, ...payload} : task)

            return tasks.find(task => task.id === id)!
          })
            .then(task => set(task))
        },
      },
    },

    paginated: {
      scope: 'paginated',
      dataType: {} as PaginatedResponse<Task>,
      isQueryParams: (value: unknown): value is QueryParamsTasks | undefined => value === undefined || value instanceof Object,
      queryFn: ({queryKey}) => respond(() => paginateList(tasks, queryKey[2]?.page)),
    },
  },
})
```

## Filters in the URL

The filters a user sets on a list — a search, a type, a sort order — can be kept in the URL, so a reload or a shared link opens the list as it was. `createUseQueryParams` declares them with a parser for each, which turns the value from the URL back into its type:

```ts
import {createUseQueryParams} from 'eco-vue-js/dist/utils/api'
import {parseBoolean, parseIdList, parseString} from 'eco-vue-js/dist/utils/utils'

export const useQueryParamsProducts = createUseQueryParams({
  search: parseString,
  product_type__in: parseIdList,
  is_default: parseBoolean,
  ordering: parseString,
})

export type QueryParamsProducts = typeof useQueryParamsProducts['QueryParams']
```

Leave `page` and `size` out: the list adds them to each page's query itself.

On a page, the declaration reads the filters from the route and writes changes back to it:

```ts
const route = useRoute()
const {queryParams, updateQueryParams} = useQueryParamsProducts(route)
```

* `queryParams` is a reactive object parsed from the route's query. It goes to the list as `query-params`. The object is created once per declaration, so the pages that use one declaration share it.
* `updateQueryParams(value)` merges `value` into the URL with `router.replace`. An empty value removes its param. Bind it to the filters and to the list's `update:query-params`, which sets `ordering` when a column is sorted.
* `useQueryParamsProducts.useQueryParamsLocal(initial?)` gives the same pair without the URL, for filters that don't need to survive a reload, e.g. in a modal.

The parsers in `eco-vue-js/dist/utils/utils` are `parseString`, `parseBoolean`, `parseInteger`, `parseId`, `parseIdList`, `parseIntegerList`, `parseStringList` and `parseJson(guard)`. A declaration's `config` can be spread into another, to share filters between lists.

## Errors

`handleApiError` shows an error notification with the server's `detail` or `non_field_errors`. With a [form](/components/form), it also shows the error body's field errors under the fields they name. It skips cancelled requests and rejects again, so a caller can still react:

```ts
const submit = () => productModelApi.item.actions.update(id, payload)
  .then(() => emit('close:modal'))
  .catch(error => handleApiError(error, formRef.value))
```

The field errors are expected in the Django REST framework shape: `{name: ['This field is required.']}`.

## Lower-level helpers

* `createDefaultQuery(modelKey, scope, name, queryFn, isQueryParams?, options?)` from `eco-vue-js/dist/utils/useDefaultQuery` builds one query hook, the way `createRestModelApi` builds each of its queries.
* `makeQueryPaginated(modelKey, getter, setter?, pageLength?)` serves a paginated query from an array in memory, and `wrapUseQueryPaginated` pages the result of a query that returns the whole list. `paginateList` pages an array into a `PaginatedResponse`.
* `setQueryItem`, `setQueryItems`, `removeQueryItem`, `removeQueryItems` and `updateQueryItems` from `eco-vue-js/dist/utils/queryCache` change a model's cached items outside an action, e.g. on a message from a websocket. `snapshotQueries` saves the model's cache and returns a function that restores it.

---

---
url: https://rsmple.github.io/eco-vue-js/guide/theming.md
description: >-
  Theme eco-vue-js with a palette, color roles and w-* CSS variables — a live
  playground, presets, CSS to copy into an app, the tone and surface classes for
  app code, and theme links that open any docs page with a theme applied.
---

# Theming

The kit's look comes from three kinds of CSS variables:

* **Palette** — a primary color, four status colors, a neutral `gray-*` scale, the page background and text, and fonts. They are Tailwind theme tokens: an app overrides them in its own `@theme`.
* **Color roles** — what components actually paint with, named by purpose: main and muted text, surfaces, lines, focus. Each reads the palette by default, and an app can set any of them in `@theme` too.
* **`w-*` variables** — sizes and radii of fields, buttons and list headers. An app sets them on `body`, directly or with the matching utilities (`w-input-h-9`, `w-button-rounded-xl`).

All are plain CSS variables at runtime, so this site can swap them live: the whole site follows the playground below, including the header and every component page.

* **The theme in use** is at the top, with what to do with it. **Save as…** keeps it under a name in this browser; changes to a saved theme are saved into it as you make them, and the palette button in the header switches to it from any page. **Copy link** shares it: the link opens this page with the theme applied, and adds it to the other person's themes when it is a saved one. **Copy CSS** gives the stylesheet for an app.
* **Presets** are starting points, and **My themes** lists the saved ones. **Random** picks a primary color, status colors (negative, positive, warning, info) in the same style and weight, the neutral scale, size and radius that suit them, and a dark mode background that fits the style — lifted for Soft, almost black for Neon, whose shadows also glow in its primary — each at a lightness that passes the kit's contrast checks in both modes. A fill with black text can be bright, like warning, and goes brightest in Neon. A yellow or lime primary always is one, and the status colors turn bright with it. Bright fills stand out from a white page less than darker fills do, so their text and the focus ring are darkened to stay readable.
* **Ask an AI assistant** describes a look in words: it opens Claude or ChatGPT with a prompt that explains the tokens, or copies it for another assistant. The reply gives the theme as JSON and as a link; paste either one, or the whole reply, into the field below the buttons.
* **The fields below** adjust each token of the theme in use.

## Preview

## In an app

**Copy CSS** gives what goes in the app's stylesheet, after the kit's base:

```css
@import "tailwindcss";
@import "eco-vue-js/tailwind-base/base.css";

@theme {
  --color-primary: oklch(54% 0.15 250);
  --color-gray-50: oklch(98.4% 0.003 247.858);
  /* … the rest of the neutral scale */
}

body {
  --w-input-height: 2.25rem;
  --w-input-rounded: 0.5rem;
  /* … */
}
```

Only changed colors are listed, but every `w-*` variable is: this site sets its own sizes, and an app without them gets the kit's defaults instead (in the [shape table](#shape)).

### Light and dark mode

A color named `X` is its value in light mode and `X-dark` its value in dark mode — not a darker shade. The status colors and primary default their `-dark` to the light value, which works when the color is a mid-tone: dark enough for white text, light enough to stand out on a dark page. Set `-dark` when one value can't do both, as the `compact` preset does with a near-black primary that turns light gray in dark mode.

Swapping the neutral scale in the playground also sets the dark page background, `default-dark`, to the scale's `gray-900`, so both modes take its tint. In an app, set `default-dark` alongside the scale: the kit keeps it fixed, since some apps use it and `gray-900` as two different surfaces.

### Tones

The palette gives one color per tone, the fill. Everything else a tone needs is derived from it in the current mode:

* **Text and borders** on the page — the fill's lightness clamped to stay readable: at most 53% in light mode, at least 72% in dark.
* **Text on the fill** — black or white, whichever reads better by APCA, so a saturated purple or blue keeps white text where WCAG 2 would pick black.
* **Soft background** — 12% of the fill over the surface, as in info cards.

So a light brand color still gives readable links on white, and a yellow fill gets black text, without extra tokens. To pin one of them, set `--tone-text-{name}`, `--tone-line-{name}`, `--tone-on-{name}` or `--tone-soft-{name}` in an `@theme inline` block — for example `--tone-on-warning: var(--color-black-default)`.

### Roles

| Role | Classes | Default, light / dark | Paints |
| --- | --- | --- | --- |
| `text-accent` | `text-accent` | `black-default` / `default` | Main text |
| `text-description` | `text-description` | `gray-500` / `gray-400` | Muted text |
| `text-subtle` | `text-subtle` | `gray-400` / `gray-600` | Placeholders, disabled text, chart axes |
| `surface` | `bg-surface` | `default` / `default-dark` | Page and cards |
| `surface-subtle` | `bg-surface-subtle` | `gray-50` / `gray-850` | Barely raised areas: striped rows, empty chart cells, panels inside a card |
| `surface-muted` | `bg-surface-muted` | `gray-100` / `gray-800` | Secondary fills, hovered rows, tooltips |
| `surface-inset` | `bg-surface-inset` | `gray-200` / `gray-700` | Fills inside controls, chips |
| `surface-raised` | `bg-surface-raised`, `surface-raised` | `default` / `default-dark` lightened by 4% | Dropdowns and popovers — in dark mode a shadow hardly shows, so they are lighter than the page instead |
| `overlay` | `bg-overlay` | `default` 40% / `default-dark` 60% | Translucent bars over scrolling content |
| `backdrop` | `bg-backdrop` | `primary-light` 40% / `primary-darkest` 40% | Behind modals, bottom sheets and the mobile nav |
| `track` | `bg-track` | `gray-300` / `gray-700` | Unfilled tracks of sliders and progress bars, toggles and checkboxes when off |
| `track-strong` | `bg-track-strong` | `gray-400` / `gray-500` | The stronger track: neutral progress bars, slider and tab indicator parts |
| `line` | `border-line` | `gray-300` / `gray-700` | Field borders and dividers |
| `line-subtle` | `border-line-subtle` | `gray-200` / `gray-700` | Card and section borders |
| `line-raised` | `border-line-raised`, `outline-line-raised` | `gray-300` / `gray-700` | Edge of dropdowns, popovers and tooltips |
| `shadow` | `shadow-md`, `drop-shadow-md` | black 15% / black 50% | Shadow under dropdowns, modals, tooltips and toasts — a primary mix makes it a glow |
| `focus` | `border-focus`, `outline-focus` | `primary` / `primary-dark` | Focused field border and ring |
| `gradient-start`, `gradient-middle`, `gradient-end` | `from-gradient-start via-gradient-middle to-gradient-end` | `primary`, turned 30° and 60° towards pink / the same from `primary-dark` | The brand gradient |

A theme sets a role with `--role-{name}` and `--role-{name}-dark` in `@theme`:

```css
@theme {
  --role-line: var(--color-gray-400);
  --role-surface-muted-dark: oklch(25% 0.02 250);
}
```

The shadow's color is a role too, and `--w-shadow-lift` sets how far it falls: `0` centers it, so a theme can turn every `shadow-md` into a glow:

```css
@theme {
  --role-shadow-dark: color-mix(in oklab, var(--color-primary-dark) 45%, transparent);
}

body {
  --w-shadow-lift: 0rem;
}
```

On a dark page a glow shows about as bright as its alpha times its color's lightness, so a yellow or cyan glows much brighter than a purple at the same share. Dividing the alpha by the lightness evens that out — this matches 45% at lightness 0.6 for every hue:

```css
@theme {
  --role-shadow-dark: oklch(from var(--color-primary-dark) l c h / min(0.675, calc(0.27 / l)));
}
```

### Data palette

Categories — chart series, plant kinds, syntax colors — take the kit's data hues: `data-red`, `data-orange`, `data-amber`, `data-green`, `data-teal`, `data-cyan`, `data-blue`, `data-violet`, `data-fuchsia`, `data-pink` and `data-gray`. They are mid-tones like the status colors, so each works as a tone in both modes without `-dark` values (the Preview above shows them as fills and as soft chips).

An app names its categories after them, so a theme that retunes the palette retunes the categories too:

```css
@theme {
  --color-kind-fern: var(--color-data-green);
  --color-kind-succulent: var(--color-data-teal);
}
```

```html
<span class="tone-kind-fern text-tone">Fern</span>
<span class="tone-kind-succulent surface-soft text-tone">Succulent</span>
```

### In app code

Components use the same classes, and app code should too: a color written as a role or a tone follows the theme and the mode by itself, with no `dark:` pair.

```html
<!-- muted text and a divider -->
<p class="text-description border-b border-line-subtle">3 items</p>

<!-- tone text on the page -->
<p class="tone-negative text-tone">Required</p>

<!-- filled: plain text and descriptions inside become readable on the fill -->
<div class="tone-primary surface-fill">
  Plan <span class="text-description">renews monthly</span>
</div>

<!-- soft: tinted background, normal text, a tone icon -->
<div class="tone-info surface-soft">
  <IconInfo class="text-tone" />
  <p class="text-accent">Title</p>
</div>
```

| Class | Effect |
| --- | --- |
| `tone-{name}` | Sets the tone for the element and its children: `primary`, `negative`, `positive`, `warning`, `info`, any theme color (`tone-kind-fern`) or an arbitrary one (`tone-[#0f766e]`) |
| `text-tone` | The tone's readable shade, for text and icons on the page |
| `border-tone-line` | The tone's shade for borders and outlines on the page — nearer the fill than `text-tone`, as lines need less contrast than text |
| `bg-tone-fill`, `border-tone-fill`, `text-tone-on` | The fill, and the text that goes on it |
| `bg-tone-soft` | The tone's soft background |
| `surface-fill` | Fill background; `text-accent`, `text-description`, `text-subtle` and lines inside switch to the text-on-fill color |
| `surface-soft` | Soft background; roles inside stay as they are |
| `surface-muted` | Muted background; a soft tone set inside it mixes over it |
| `surface-raised` | Dropdown or popover background; a soft tone and `bg-surface` inside it follow it |
| `surface` | Page background and text, and resets roles a scope outside changed |
| `light`, `dark` | Forces a mode for the element and its children, as tooltips do with `dark` |

Roles take opacity like any color: `bg-surface-muted/50`, `outline-focus/20`.

### Migrating `dark:` pairs

The kit ships a codemod that rewrites light/dark palette pairs in an app's class strings to roles and tones:

```sh
npx eco-vue-color-roles                      # report what it would change in src/
npx eco-vue-color-roles --write src          # apply
npx eco-vue-color-roles --exact --write src  # only replacements that render the same colors
```

Without `--exact` it also moves near-duplicate grays to the role the kit uses and tone text to the readable shade derived from the fill. It ends with the pairs it found no role for, most frequent first. A frequent one usually means the app's surface or line differs from the kit's default. Set it as a role in the app's theme, then run again with `--theme`, so those pairs map too:

```css
@theme {
  --role-surface-dark: var(--color-gray-900);
}
```

```sh
npx eco-vue-color-roles --theme src/assets/styles/index.css --write src
```

## Theme links

A link to any page of this site can carry a theme in a `theme` query parameter. Opening it applies the theme, keeps it in the browser like one picked here, and drops the parameter from the address. **Copy link** above makes one for this page.

The parameter is a preset id, or a URL-encoded JSON object of tokens, with an optional `preset` the tokens override:

```
https://rsmple.github.io/eco-vue-js/guide/theming?theme=ocean
https://rsmple.github.io/eco-vue-js/components/select?theme={"preset":"compact","color-primary":"#e11d48","neutral":"stone"}
```

Encode the JSON with `encodeURIComponent` when building a link in code; browsers accept it unencoded when typed. Keys are the variable names without `--`, plus `neutral`, which takes a scale name: `zinc`, `slate`, `gray`, `neutral` or `stone`. An optional `name` saves the theme among the opener's themes under that name, numbered when it is taken; opening a theme that is saved already switches to it instead of saving a copy. Unknown keys are ignored, and so are values with `;`, `{`, `}`, `<`, `>`, `\`, `url(` or `@import`. Colors take any CSS color syntax, including `var(--color-gray-400)`; sizes any CSS length. Radii double as side padding, so a pill shape is half the height (`1.125rem` for `2.25rem`), not `9999px`.

To make a theme from a description — "a warm, rounded theme for a finance dashboard" — pick a neutral scale and a primary, adjust status colors only where they clash with it, and link to the page the theme should be seen on, or to this one to keep editing it. Mid-tone fills (OKLCH lightness 50–58%) work in both modes without `-dark` values.

### Presets

| Id | Look |
| --- | --- |
| `default` | The kit's violet on zinc, as this site ships |
| `ocean` | Blue primary, cyan info, slate neutrals |
| `forest` | Green primary, lime positive, stone neutrals, pill-shaped fields and buttons |
| `sunset` | Orange primary, rose negative, stone neutrals |
| `compact` | Monochrome: near-black primary that turns light in dark mode, no tint, 2rem fields and buttons, small radii |

### Palette

| Key | Default | Controls |
| --- | --- | --- |
| `color-primary` | `oklch(62% 0.17 286.8)` | Fills, links, focus and selection |
| `color-primary-dark` | `primary` | The same in dark mode |
| `color-primary-light` | `primary` 10% over `default` | List headers and the backdrop in light mode |
| `color-primary-darkest` | `primary-dark` 20% over `default-dark` | The same in dark mode |
| `neutral` | `zinc` | The `gray-*` scale: lines, fills, muted text |
| `color-default` | `#ffffff` | Page and card background in light mode |
| `color-default-dark` | `oklch(21% 0.006 285.885)`, zinc's 900 | Page and card background in dark mode |
| `color-black-default` | `#333333` | Main text in light mode |
| `color-negative` | `oklch(64% 0.2 24.1)` | Errors and destructive actions |
| `color-positive` | `oklch(69% 0.148 150)` | Success |
| `color-warning` | `oklch(85% 0.16 85)` | Warnings; black text on the fill |
| `color-info` | `oklch(63% 0.16 262.6)` | Information |
| `color-*-dark` | the light value | Each status color in dark mode |
| `color-data-*` | Tailwind's hues at mid lightness: white text on all but orange and amber; gray is the scale's 500 | [Data palette](#data-palette) |
| `role-*`, `role-*-dark` | see [Roles](#roles) | One role, per mode |
| `font-sans` | `MontSerrat, system-ui, sans-serif` | Text font. Only MontSerrat is loaded on this site; other families must be installed on the viewer's machine |

### Shape

| Key | Site value | Kit default | Controls |
| --- | --- | --- | --- |
| `w-input-height` | `2.25rem` | `2.75rem` | Inputs and selects; the options inside them follow |
| `w-input-rounded` | `0.5rem` | `0.75rem` | Radius of inputs and selects, and the side padding of their options |
| `w-input-gap` | `0.125rem` | `0.25rem` | Space between a field's border and the options in it |
| `w-button-height` | `2.25rem` | `2.75rem` | Buttons |
| `w-button-rounded` | `0.75rem` | `1rem` | Radius of buttons, and their side padding |
| `w-list-header-height` | `2.25rem` | `2rem` | List headers |
| `w-list-header-rounded` | `0.75rem` | `1rem` | Radius of list headers |
| `w-checkbox-size` | `0.75rem` | `1rem` | Checkboxes and radios |
| `w-shadow-lift` | `0.5rem` | `0.5rem` | How far `shadow-md` falls under dropdowns, modals and tooltips; `0rem` centers it into a glow |

The kit has more `w-*` variables for single components, such as `w-list-padding` and `w-modal-wrapper-rounded`; the playground covers the ones that shape the whole app.

---

---
url: https://rsmple.github.io/eco-vue-js/releases.md
description: >-
  Release notes for every eco-vue-js version, newest first — what changed in
  each component and what breaks on upgrade.
---

# Releases

Every version published to npm, newest first. The same notes are on [GitHub Releases](https://github.com/rsmple/eco-vue-js/releases).

## 0.26

### v0.26.20

2026-10-27 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.20)

* Add `deferred` and `previewData` props to [WSelectSingle](/components/select), [WSelect](/components/select), [WSelectAsync](/components/select) and [WSelectAsyncSingle](/components/select) — a deferred `seamless` select renders as a lightweight field until it is clicked or focused, so lists with many select cells render much faster; `previewData` supplies the selected options for its chips without loading the options
* Fix WSelectAsync and WSelectAsyncSingle requiring `valueGetter` — it defaults to the option's `id`, and leaving it out no longer logs a warning per field
* Speed up rendering of [WInputAsync](/components/input)
* Fix [WNavItem](/components/nav-bar) title for a route whose child record shares its path — the title registered on the parent record is now used

### v0.26.19

2026-10-26 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.19)

* Fix [WDropdownAdaptive](/components/dropdown-menu) not updating its open content when the parent changes its slots — content added or removed behind a `v-if` while the dropdown, dialog or bottom sheet is open now shows up

### v0.26.18

2026-10-25 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.18)

* Fix [WList](/components/list) sort menu listing fields whose `field` getter returns `undefined` for the current query params — only fields that resolve to a sortable key are offered now

### v0.26.17

2026-10-25 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.17)

* Fix [WInfiniteList](/components/infinite-list) adding pages one after another on very long lists (about a million rows and up) — the spacers now shrink to fit under the browser's element height limit, so the scrollbar moves through the list faster than the rows scroll

### v0.26.16

2026-10-24 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.16)

* Fix [WList](/components/list) table header and rows not stretching to the full width of the list when no column is flexible — an empty filler column now takes the leftover space
* Fix WList header cells picking up the field's `cssClass` — header cells now only get `cssClassHeader`
* Fix WList header settings content being clipped

### v0.26.15

2026-10-24 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.15)

* Lay out [WList](/components/list) table columns on one shared grid sized by the field meta `width` (`10rem` by default, `minmax(…fr)` and `var(--…)` allowed), so header and cells always line up and rows stop re-rendering while the list opens — nested fields span their own columns, and `componentItem` lines of nested arrays now fill the row instead of one cell
* Add `w-list-align-top-*` to set how far the checkbox and row menu sit from the top with `align-top`, so they line up with the first line of the cells
* Fix grouped WList: the group heading spans the whole row and sticks under the toolbar, grid rows run on across pages, and cards no longer jump while pages above load or are dropped — [WInfiniteList](/components/infinite-list) `pageClass` now styles one element holding all pages, with a new `pageStyle` beside it
* Fix long dropdown menus without a tip overflowing the screen — they now scroll within the height left

### v0.26.14

2026-10-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.14)

* Add [WQueryStatus](/components/query-status) — mounted once next to [WNotify](/components/notify), it watches the queries on screen and shows one message with Retry when some fail to load because the server is unreachable or answers 5xx, 408 or 429; while the server is down every skeleton stops and greys out
* Add [WQueryBoundary](/components/query-boundary) — wraps a card with the queries it shows; when one fails without data its skeletons stop and grey out, with its own message only for failures WQueryStatus doesn't show, such as a 403
* Keep failed list pages and [WPageError](/components/page-error) out of the WQueryStatus message, so a failure is told once
* Add the `partialLoadError` text ("Some data failed to load") and `getLoadErrorMessage`, `findFailedQueries` and `useHandledQueryError` in `utils/queryClient`

### v0.26.13

2026-10-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.13)

* Add [WPageError](/components/page-error) — wraps a page that shows one item and replaces it while its query has an error: the status, the server's `detail` and Back, plus Retry when the server was unreachable or answered 5xx; its texts (`errorTitle`, `pageNotFound`, `serverError`, `serverUnavailable`, `back`, `retry`) translate with `setTexts`
* Add `watchServerRecovery` to `utils/queryClient` — while the server is unreachable it sends a cheap probe request with a growing delay (and at once when the tab is shown or the browser comes back online), then refetches the failed queries once the server answers; vue-query's `refetchOnReconnect` only follows the browser's own connection
* Add `useAvailable()` to ApiClientInstance — false after a network failure or a 502/503/504, true again on the server's next answer

### v0.26.12

2026-10-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.12)

* Add an error state to [WInfiniteList](/components/infinite-list) and [WList](/components/list) — a page that failed to load with nothing cached shows the server's `detail` (or "Server is unavailable") and a Retry button instead of endless skeletons; replace it with the new `error` slot, and translate it with the `loadError`, `serverUnavailable` and `retry` texts
* Add `ApiErrorUnavailable` — requests reject with it when the server can't be reached or a gateway answers 502/503/504, instead of a bare `TypeError` that error handlers ignored
* Fix ApiClientInstance logging users out when the session refresh fails because the server is down, and requests hanging forever when the refresh failed or the refresh endpoint answered 401 — every request now settles, and a request retried after a 401 rejects when the retry fails
* Add `defaultQueryRetry` and `isRetryableError` to `utils/queryClient` — retries network errors, 5xx, 408 and 429 only, never 404 or other 4xx; use it as the `QueryClient` default

### v0.26.11

2026-10-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.11)

* Add `trail` to `useRouteTitle` — extra breadcrumb levels after a page that are not routes, such as the active filter of a list (`Pipelines / In progress`); the last one is the current title and shows its own `suffix`

### v0.26.10

2026-10-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.10)

* Fix [WSelectAsync](/components/select) showing stale options when `useQueryFnOptions` or `useQueryFnPrefix` changes — the option list and selected prefix now query again with the new function, including while the menu is open
* Fix queries from `createDefaultQuery` failing when called outside component setup — the resolved query client is now used
* Hide the [WInputSuggest](/components/input) placeholder while its unclickable menu is open, and drop the extra bottom margin on mobile
* Show the placeholder in [WInput](/components/input) when `unclickable` — the input also keeps its width and the mobile `text-base` size

### v0.26.9

2026-10-20 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.9)

* Add `maxSizeKb` to `WInput` to set the largest file `allowDropFile` accepts by drop or picker
* Raise the default `WInput` dropped-file limit from 10 KB to 100 KB

### v0.26.8

2026-10-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.8)

* Add `replace`, `target` and `rel` props to [WButtonMoreItem](/components/dropdown-menu) and [WMenuItem](/components/dropdown-menu) — open a menu link in a new tab or replace the current history entry, same as [WButton](/components/button)

### v0.26.7

2026-10-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.7)

* Fix [WUniform](/components/form) `confimGetter` cancel: the field drops its unsaved draft (an async [WInput](/components/input) shows the saved value again) and the update promise resolves instead of rejecting, so cancelling no longer reaches the app `errorHandler`
* Expose `cancel` on WInput — discards the unsaved async value
* Hide the [WFieldWrapper](/components/field-wrapper) filter button until the field is hovered, unless the filter is active
* Fix [WTabs](/components/tabs) switching from a horizontally scrolled tab — the scroll offset is reset so it no longer shifts the next tab during the transition

### v0.26.6

2026-10-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.6)

* Add `expirationCookie` option to ApiClientInstance — apps sharing an origin can each point at their own session-expiry cookie (defaults to `exp`), so one app logging out or refreshing no longer clears or stalls the other's session

### v0.26.5

2026-10-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.5)

* Add `toggle` slot to [WButtonMore](/components/dropdown-menu) to open the menu from another button, such as [WButtonInput](/components/button) — the slot gets `toggle`, `active` and `attrs` to wire up the click, highlight and `aria-expanded`
* Add `active` prop to WButtonInput to highlight it, such as while its menu is open
* Fix the hover and press ripple on [WButton](/components/button), WButtonInput and [WCheckbox](/components/checkbox) stopping inside the border — it now covers the border and its corners match the element's rounding
* Add `w-ripple-border` utility for custom `w-ripple` elements with a border — `w-ripple-border` for 1px, `w-ripple-border-2` or `w-ripple-border-(--var)` for others

### v0.26.4

2026-10-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.4)

* Fix [WInfiniteList](/components/infinite-list) not loading the next pages after a fast scroll, and size its spacers and skeletons by the real item count — a short last page no longer leaves blank space or shrinks the scrollbar estimate
* Fix the [WTabs](/components/tabs) bar on phones adding the page inset inside a box that sets `--w-frame-padding` — it now takes that padding instead
* Fix menus and confirms opened from above the modals, such as a full-screen login, rendering underneath their opener
* Fix the [WNavItem](/components/nav-bar) counter skeleton overlapping the title

### v0.26.3

2026-10-15 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.3)

* Fix [WTabs](/components/tabs) scrolling the page down when switching tabs while it isn't at the very top — the page now stays where it was

### v0.26.2

2026-10-14 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.2)

* Fix [WDragContainer](/components/drag-container) reordering when `list` holds equal values (the same string twice, or the same object) — dragging one of them no longer moves the wrong item or loses track of it

### v0.26.1

2026-10-14 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.1)

* Change IconDanger, IconSuccess and IconWarn to an outline style — existing usages will render as outlines
* Add IconDangerSolid, IconSuccessSolid and IconWarnSolid filled variants — use these to keep the previous filled look
* Notifications keep their filled icons by using the new solid variants

### v0.26.0&#x20;

2026-10-14 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.26.0)

* Add paginated mode to [WInputOptions](/components/input) — pass `useQueryFnOptions` + `queryParamsOptions` (and `searchField`, default `search`) instead of `options` to get server-side suggestions with infinite scroll
* Add `draft` mode to WInputOptions — typing only drives suggestions; the value changes on Enter, a picked suggestion or the "Apply:" row (`applyPrefix`), and the typed text is dropped when the menu closes
* **Breaking**: WInputOptions `#option` slot and `optionComponent` now use the select option types — `option` may be `undefined` on skeleton rows
* Fix Enter not selecting the cursor option in [WSelectAsync](/components/select), and "Duplicate keys" warnings in [WInfiniteList](/components/infinite-list) when rows share a `valueGetter` value

## 0.25

### v0.25.2

2026-10-14 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.25.2)

* Lighten the default `primary` and status colors (`negative`, `positive`, `warning`, `info`) in the Tailwind base theme — status fills now sit lighter than the primary, so badges and alerts no longer outweigh the content beside them, while white text on them stays readable
* Use `text-accent` instead of `text-description` for idle and disabled items in [WMenuItem](/components/dropdown-menu)

### v0.25.1

2026-10-13 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.25.1)

* Add `soft` and `icon` props to [WChip](/components/chip) — `soft` renders a rounded pill with a tinted background and colored text, with classes set via `setSemanticTypeChipSoftMap`; `icon` shows an icon before the label
* Fix [WButtonCopy](/components/button) changing the line height when placed inside text — it now takes up one line of the surrounding text and has a larger click area
* Add `noInline` prop to WButtonCopy to lay it out as a regular block instead

### v0.25.0

2026-10-10 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.25.0)

* Add `to` prop to [WTabsItem](/components/tabs) and [WButtonTab](/components/tabs) — tabs become route links that replace the history entry, and the current route decides which tab is open
* Add route titles: [WHeaderBar](/components/header-bar) without a `title` shows a breadcrumb of the current route, pages report data-driven titles with `useRouteTitle`, and `useDocumentTitle` keeps the browser tab title in sync — [WNavItem](/components/nav-bar) also shows the title the open page registers
* Fix [WNotify](/components/notify) toast position to respect safe-area insets, and keep pending toasts on screen until they finish — the result shows and closes after 5 seconds like any other toast
* Fix [WLink](/components/links) clipping long text — it now wraps instead of being cut off

## 0.24

### v0.24.0&#x20;

2026-10-10 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.24.0)

* Add filters to the [WList](/components/list) selection bar — put [WListFilter](/components/list) in the new `filter` slot. Chips that do not fit fold into a "more" chip, `pinned` keeps chosen filters always shown, and a filter's `meta.summary` names the picked values on its chip
* **Breaking**: [WInput](/components/input) emits `''` when cleared or emptied, also when the model was `undefined` — set `clearValue` to `undefined` or `null` to keep emitting that
* Add the `isPlaceholderItem` query option to show an item already cached by a list while its own query loads, a `divider` prop and count badges to [WTabs](/components/tabs), and `iconClass` to [WInfoCard](/components/info-card)
* Fix WTabs not updating when tabs change without changing their number, and list every sortable field in the WList sort menu, with a badge counting the sorted ones

## 0.23

### v0.23.1

2026-10-07 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.23.1)

* Fix [WUniform](/components/form) resetting its model when `queryParams` change before the new item has loaded — a create whose result carries the new id (stepper forms that save on a step) no longer erases the form; the loaded item replaces the model once it arrives
* Update dependencies with audit fixes

### v0.23.0&#x20;

2026-10-07 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.23.0)

* **Breaking**: `dateFormat` shows the month name (`07 Oct 2026`) and `datetimeFormat` puts the date first with the locale's separator (`07 Oct 2026, 14:30:05`) — dates no longer read differently across locales
* **Breaking**: date, time and duration formatters take options instead of flags — `dateFormatShort` → `dateFormat(d, {year: 'auto'})`, `timeFormatShort` → `timeFormat(d, {seconds: false})`, `durationHumanize(s, full, round)` → `durationFormat(s, {style, round})`, `parseDate` → `parseDateQuery`
* Add `setLocale` — dates, times, durations and numbers format in the app's locale, and durations show `10 mths` / `10 mins` instead of the ambiguous `10 M` / `10 m`
* Add `noData`, `dateFrom`, `dateTo` and `noDate` texts and localize the "Today" label in charts; [WInputDate](/components/input) reads dates typed in the locale's order

## 0.22

### v0.22.1

2026-10-06 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.22.1)

* Add `replace` option to `useOverlay().open` — the new dropdown takes the place of the one it was opened from, at its anchor, and keeps its `onClose` until it closes too
* Fix lazily loaded overlay content flashing an empty frame — the overlay now shows once the component has loaded, keeping the one it replaces until then
* Fix dropdowns closing when a press inside, such as dragging a slider, is released outside; fix bottom sheets not closing on swipe when shown without a backdrop; fix [WUniform](/components/form) detecting changes in nested object values
* Open the [WButtonDropdown](/components/dropdown-menu) menu with the overlay manager — a bottom sheet on phones; widen filter dropdowns to fit their fields, line up embedded select options with the field, and pin the [WNotifyCenter](/components/notify) footer in its dropdown

### v0.22.0&#x20;

2026-10-06 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.22.0)

* **Breaking**: Overlays now lay out their own content — a [WModalWrapper](/components/modal), filter or menu opened as a modal, dropdown or bottom sheet gets its title, buttons and padding from the frame. Remove `sm-not:px---inner-margin` from content and give edge-to-edge parts such as lists `w-frame-bleed`
* **Breaking**: Drop `embedded` from filter `meta` — filters show their `header` as a title and size to their content. Drop `moreToggleClass` from [WButtonSelection](/components/list) — list bulk actions that do not fit the bar move into More
* Ask before closing a modal whose [WUniform](/components/form) with `api-method` has unsaved changes, and keep it open while it saves — `useLayerChanges` and `useLayerBusy` do the same for other content. Add `setTexts` to translate the built-in texts
* Add `stepperControls`, `submitting` and `disabledNext` to [WTabs](/components/tabs) to put the step title and buttons in the frame — [WModalStepper](/components/modal) is deprecated in their favour
* Show toasts at the top edge on phones for every [WNotify](/components/notify) `position`, clear of a modal's buttons
* Fix WUniform date fields not reporting changes or losing their value after a save, keep unsaved changes when the loaded model updates, and check the current step's fields before the WTabs stepper moves on

## 0.21

### v0.21.3

2026-10-05 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.21.3)

* Add `horizontalAlign` to [WNotifyCenterButton](/components/notify) and `useNotifyCenter` — `HorizontalAlign.LEFT_INNER` grows the center left from a bell at the right end of the header, `HorizontalAlign.LEFT_CENTER` opens it beside a bell in a side rail
* Open overlay dropdowns with `align` set to `LEFT_CENTER` or `RIGHT_CENTER` beside the anchor, with a tip pointing at it — near the top or bottom of the screen the box shifts while the tip stays on the anchor
* Animate notifications into and out of [WNotifyCenter](/components/notify), and center its empty state
* Hide the [WButtonAction](/components/actions-bar) tooltip while the button is `active`

### v0.21.2

2026-10-05 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.21.2)

* Fix [WNavItemExpand](/components/nav-bar) not opening its dropdown on hover on server-rendered pages, such as a VitePress site
* Export `NotifyType`, `NotifyChannel` and the notify types (`NotifyConfig`, `NotifyContentEmits`, `NotifyGroup`, `NotifyItem`, `NotifyPatch`) from `eco-vue-js/dist/utils/Notify`
* Add `eco-vue-js/dist/utils/NotifyCenter` with `useNotifyCenter`, `closeNotifyCenter`, `isNotifyCenterOpen` and the pending and action counts — no more imports from component internals

### v0.21.1

2026-10-05 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.21.1)

* Keep [WNotify](/components/notify) toasts on screen while the pointer is over them — their timers pause and resume with the time they had left
* Fix WNotify groups merging repeated members into one — every member now adds to the list, newest first; a group's toast stays up for 5 seconds after its latest member and leaves all at once, and a long member list scrolls
* Fix a notify added by the same click that closes the notify center never showing its toast
* Fix `set` writing to the wrong level when an intermediate object already exists, `numberFormatter`/`percentFormatter` leaving every comma after the first in large numbers, and `w-border-svg-stroke-*` ignoring bare numbers — `w-border-svg-stroke-2` is now 2px

### v0.21.0&#x20;

2026-10-05 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.21.0)

* Add [WNotifyCenter](/components/notify) and [WNotifyCenterButton](/components/notify) — a history of notifications split into action and activity channels, with groups and custom `component` content; `Notify.process` shows a spinner until `Notify.update` settles it, `Notify.*` now returns the notification id, and [WNotify](/components/notify) gets a `position` prop
* Add anchored confirms — pass `anchor` to `Modal.addConfirm` (or open it with `useOverlay` from a menu item) to show the confirm as a dropdown next to the element, a bottom sheet on phones, instead of a modal; bulk actions get `clearSelection` so the selection resets after a confirm from the More menu
* Open [WButtonMore](/components/dropdown-menu), the list's sort, export, settings and filter menus, and input and select menus through one overlay manager — only one menu is open at a time, nested menus open over their parent, dropdowns are centered on their anchor with a tip, and Escape closes input menus; selects scroll to the selected option on open (`cursorSelected` also puts the cursor on it)
* **Breaking**: [WDropdownAdaptive](/components/dropdown-menu) now opens through the overlay manager — `top`, `bottom`, `updateAlign`, `emitUpdate`, `dropdownClass`, `closeOnClickOutside`, the `update:rect` emit and `updateDropdown` are gone; use `horizontalAlign`, `frameClass` and `closeOnClick`, and `close` now fires on any outside click, Escape or swipe

## 0.20

### v0.20.6

2026-10-03 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.6)

* Fix async [WUniform](/components/form) blocking every save on one invalid field — valid changed fields now save while the invalid one shows its error and waits, a change made during a save is sent when it finishes, and no "Form contains invalid data" notification pops up; validation also no longer scrolls to a field that is already in view
* Add [WDropdownTip](/components/dropdown) and the `surface-raised` and `shadow` roles — dropdowns and menus sit on a raised surface with a layered `shadow-md` (adjust with `--w-shadow-lift`), [WList](/components/list) filter dropdowns get a pointer tip, and tooltips follow the page theme instead of always being dark
* Drop the `w-checkbox-color-*` and `w-date-picker-day-*` utilities — checked [WCheckbox](/components/checkbox) and selected calendar days now pick black or white text by contrast (`text-tone-on`), so remove them from your `@apply` or the Tailwind build fails
* Add a Clear button to the WList sort menu, stop [WSelectAsync](/components/select) refetching its chips on select and unselect, keep light primaries such as yellow readable in borders and focus rings (`border-tone-line`), match [WButtonGroup](/components/button-group) radius and padding to [WButton](/components/button), and ship the docs as Markdown with an `llms.txt` index in the package

### v0.20.5

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.5)

* Fix the line-number gutter background in multiline [WInput](/components/input) — it now matches the input background, including one set with `w-input-bg-*`

### v0.20.4

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.4)

* Fix `@import "eco-vue-js/tailwind-base/markdown.css"` and `css/markdown/blocks.css` failing to resolve in Vite and ESLint — every stylesheet under `tailwind-base` is now exported, not only `base.css`

### v0.20.3

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.3)

* Add `semanticType` prop to [WMenuItem](/components/dropdown-menu) and [WButtonMoreItem](/components/dropdown-menu) — `negative`, `positive`, `warning` and `info` color the item text at rest, so a red "Delete" no longer needs a `tone-*!` override
* Add markdown styles to the Tailwind base — `@import "eco-vue-js/tailwind-base/markdown.css"` styles rendered markdown in `.w-markdown` with color roles, and `css/markdown/blocks.css` adds GitBook hints, colored text and expandable sections
* Fix `h4` in markdown rendering larger than `h3` in small-text containers, and the code block copy button turning invisible on hover in light mode

### v0.20.2

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.2)

* Add the `surface-subtle` color role (`bg-surface-subtle`) — a fainter layer than `surface-muted` for striped rows, empty chart cells and panels inside a card; themes set it with `--role-surface-subtle` and `--role-surface-subtle-dark`
* Make the default `primary-light` and `primary-darkest` shades softer
* Map `bg-X-light dark:bg-X-darkest` to `tone-X bg-tone-soft` and gray-50 pairs to `bg-surface-subtle` in the color roles codemod
* Fix the color roles codemod collapsing indentation and line breaks in multi-line class strings

### v0.20.1

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.1)

* Fix [WButton](/components/button) and other semantic-type borders rendering in the text color (white on filled buttons) in apps — the kit's semantic type classes are now picked up by Tailwind, so `border-tone-fill` is generated

### v0.20.0&#x20;

2026-10-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.20.0)

* Add color roles: components paint with roles (`text-accent`, `bg-surface`, `border-line`, …) and tones (`tone-negative text-tone`, `surface-fill`) instead of `dark:` pairs, and an app sets any role as `--role-*` in its `@theme` — also adds a `data-*` palette for categories, `gradient-*` roles, and the `npx eco-vue-color-roles` codemod for an app's own `dark:` pairs; see the Theming guide
* **Breaking**: retune default colors for contrast — darker violet primary, deeper status colors, zinc `gray-*`, darker `text-description` in light mode; `-dark` colors now default to their light value, and text on fills and tone text are derived from the fill so they stay readable in any theme
* **Breaking**: drop the `severity-*` and `score-*` colors from the theme — define them in the app
* Fix side padding of [WButton](/components/button) and input options with very large or very small radii — it now stays between `0.5rem` and half the height

## 0.19

### v0.19.4

2026-09-30 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.19.4)

* Fix `goto` in [WInfiniteList](/components/infinite-list) landing on the wrong rows for a page that is not rendered, and ignoring the item index — it now scrolls to the item itself, once its page has loaded
* Fix readonly [WInput](/components/input) and the selects built on it being taller than the editable field — switching to readonly no longer shifts the layout
* Restyle [WProgressBar](/components/progress) and [WProgressStriped](/components/progress), with the percentage readable over the fill and `role="progressbar"` for screen readers; [WSlider](/components/slider)'s thumb now grows on hover like [WSliderRange](/components/slider)'s; set `--w-chart-heatmap-bg` to match [WChartHeatmap](/components/charts)'s fade to a background other than the default
* Accept string ids in list selections (`id__in`, `id__not_in`), and drop the unused WFilterWrapper and `useQueryUpdater`

### v0.19.3

2026-09-30 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.19.3)

* Update [WSpinner](/components/spinner) to match regular icons — 24×24 viewbox with a 1.5 stroke, and 20px by default instead of 2rem; size it with `square-*`
* Add `IconSpinner`, an animated spinner usable anywhere a regular icon is
* Drop the `w-spinner-size-*` utility and the `spinner-dash-small` animation — use `square-*` and `animate-spinner-dash` instead

### v0.19.2

2026-09-29 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.19.2)

* Add `loading` to [WButtonAction](/components/actions-bar) — a shimmer runs over the button while its action is in progress — and close its tooltip on click; add `semanticType` to [WCounter](/components/counter), `label` to [WCheckbox](/components/checkbox) and [WButtonSelectionAction](/components/list), and use `textFilter` of [WActionsBar](/components/actions-bar) as the filter panel heading; list rows, toolbar buttons and [WExpansionItem](/components/expansion) now expose their names and expanded state to screen readers
* Fix [WSlider](/components/slider) filling from the wrong position with a non-zero `min`, ignoring `semanticType` and snapping off-step, and [WSliderRange](/components/slider) rendering without color unless set — it now defaults to primary; [WFilePicker](/components/file-picker) no longer accepts drops while readonly and keeps only the first dropped file without `multiple`
* Fix [WInfiniteList](/components/infinite-list) template ref exposing nothing — `resetPage`, `goto`, `refetchAll`, `isFetching` and `isRefetchingAll` now work — and refetching the wrong pages after an item changes; fix [WModalImport](/components/modal) hiding its progress bar and counting finished requests as aborted, [WPage](/components/report-pages) continuation pages bumping the section number, and [WRouterLink](/components/links) failing without vue-router or `to` — it now renders a plain link
* Drop unused props — `headerTopIgnore`, `lastChild` and `count` from WInfiniteList, `bottom` from WActionsBar, `update:search` from [WHeaderBar](/components/header-bar), `semanticType` and `noBg` from WSliderRange, `title` from [WDatePickerSingle](/components/date-picker) and [WListFilter](/components/list), `small` from WCounter, `showPoints` from [WChartLine](/components/charts); deprecate `searchVisible` on WListFilter; make `watermark` optional on WPage

### v0.19.1

2026-09-27 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.19.1)

* Emit `update:has-changes` from [WTabs](/components/tabs) when any tab has unsaved changes, render the `suffix` slot of [WTabsItem](/components/tabs) and disable the tab button of a disabled WTabsItem
* Fix the text color of [WChip](/components/chip), [WDropdownMenu](/components/dropdown-menu) ignoring `bottom` and [WButtonGroup](/components/button-group) not inheriting readonly and skeleton states from a parent; [WCheckboxGroupMultiple](/components/checkbox) now supports `subgrid` and `embedded` like [WCheckboxGroup](/components/checkbox)
* Add the `w-drag-item-overlay-*` utility to set the drag overlay color in [WDragContainer](/components/drag-container)
* Drop unused props — `top`, `bottom`, `parentElement` and `dropdownClass` from [WButtonDropdown](/components/dropdown-menu), `innerClass` from WDropdownMenu, `divided` from WTabsItem and `noPadding` from [WListCardField](/components/list)

### v0.19.0&#x20;

2026-09-27 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.19.0)

* Fix [WInput](/components/input) paste button rejecting clipboard text within `maxLength` and accepting text over it
* Fix [WSelectAsync](/components/select) showing at most 8 chips whatever `prefixMax` is — it now defaults to 8 and loads that many; [WSelectAsyncSingle](/components/select) now emits `focus` and `blur`
* **Breaking**: replace `selectOnClose` with `searchModel` on all selects, and drop unused props and events — `light` and `maxHeight` from [WTooltip](/components/tooltip), `mandatory` and `savedText` from [WToggle](/components/toggle) and form fields, `top`, `bottom`, `parentElement` and `innerClass` from [WInputSuggest](/components/input), [WInputDate](/components/input) and [WSelect](/components/select), `useFirstDefault` from WSelectAsync, `keypress:backspace` from WInput and `update:model-value` from [WSelectAsyncList](/components/select)
* Describe props, events and slots of WToggle, WTooltip, WInput and WSelect in the docs, and add a releases page

## 0.18

### v0.18.3

2026-09-26 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.18.3)

* Add `disabledItems` prop to [WButtonGroup](/components/button-group), `href`/`target`/`rel` props to [WButtonAction](/components/actions-bar) (with `tag="a"`) and a `right` slot to [WHeaderBar](/components/header-bar)
* Fix [WInputAsync](/components/input) refusing every save after one invalid value, and [WToggle](/components/toggle) with an array of `validate` functions always reporting an error
* Fix [WInfiniteList](/components/infinite-list) waiting for a scroll when a loaded page is too short to fill the viewport — the next page now loads right away; list headers inside their own scroll container now stick to its top instead of under the page header
* Make [WList](/components/list) and [WTabs](/components/tabs) render on the server — WList now reads its saved config on mount; `useIsMobile` breakpoints now match tailwind `sm` (640px) and `xl` (1280px), [WNavBar](/components/nav-bar) and [WActionsBar](/components/actions-bar) respect `--left-margin`/`--right-margin`, and textarea line styles ship in the tailwind base

### v0.18.2

2026-09-25 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.18.2)

* Icon-only buttons (`WButtonAction`, `WButtonSelectionAction`) expose their tooltip text as `aria-label`, so they have an accessible name
* Select dropdowns use `listbox`/`option` roles, with `aria-selected` and `aria-disabled` on options
* `WModalWrapper` renders as `role="dialog"` with `aria-modal`, and its title is an `h2` that labels the dialog
* Rich/textarea `WInput` (contenteditable) is labelled by its field title
* `WNavBar` renders a `<nav>` landmark
* `WInput` `autofocus` no longer steals focus when the user has already moved into another field within the autofocus delay

### v0.18.1

2026-09-24 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.18.1)

* Add `role="list"` to [WList](/components/list) and `role="listitem"` to its loaded rows — rows are reachable by `getByRole('listitem')` in tests and announced as a list by screen readers; skeleton rows get no role
* Render the [WHeaderBar](/components/header-bar) title as an `h1` instead of a `div` — same classes, so it looks the same, but the page title is now the page heading

### v0.18.0&#x20;

2026-09-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.18.0)

* Add `clearValue` prop to [WSelectSingle](/components/select) and [WSelectAsyncSingle](/components/select) — choose what clearing emits (`null` by default, or `undefined` / `''`), and the `update:model-value` type follows it
* **Breaking**: drop the unused `emptyValue` prop from [WFieldWrapper](/components/field-wrapper), [WInput](/components/input), [WButtonGroup](/components/button-group) and the select components

## 0.17

### v0.17.1

2026-09-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.17.1)

* Fix [WButtonGroup](/components/button-group) height — the group and its skeleton now size from `--w-button-height` (matching other buttons) instead of `--w-input-height`

### v0.17.0&#x20;

2026-09-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.17.0)

* **Breaking**: Restyle [WButtonGroup](/components/button-group) as a segmented control — options now sit on a shared tinted track with the selected one raised, instead of a row of joined WButtons. Button-only props are no longer accepted (`outline`, `borderComponent`, `noBorderComponent`, `download`, `autofocus`, link props); `semanticType`, `loading`, `tooltipText` and the field-wrapper props still work
* Fix WButtonGroup accepting clicks while `loading`, and show a proper field-height skeleton when `skeleton` is set
* Fix [WSkeleton](/components/skeleton) default sizing — skeletons now take up a full line height instead of collapsing to `1em`, so they no longer shift surrounding text when content loads
* Fix [WTabs](/components/tabs) header reserving extra empty space on the right when tabs are not wrapped

## 0.16

### v0.16.7

2026-09-21 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.7)

* Add `count` prop to [WButtonTab](/components/tabs) and to tab items in [WTabs](/components/tabs) — the count is shown formatted in parentheses after the tab title
* Add `embedded` prop to field components and `embedded` to filter `meta` — renders the field without a title or bottom margin and with its options inline. [WInputSuggest](/components/input) in this mode autofocuses and scrolls its options inside the local filter popup
* Fix the local filter picker in [WList](/components/list) offering the wrong filters or missing some when earlier filters are disabled or hidden. Filter toggle buttons are now outlined and highlighted while open
* Fix the WTabs header overflowing into the page's side margin on mobile

### v0.16.6

2026-09-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.6)

* Fix [WTooltip](/components/tooltip) content not updating when the slot's data changes while the tooltip is open
* Fix [WList](/components/list) header padding flickering on mount, and collapse card rows that are left holding only areas spanning into other rows (e.g. the select checkbox beside a hidden field)
* Add a `short` argument to `datetimeFormat` and show the year in `dateFormatShort` for dates outside the current year — `datetimeFormat` now renders `time - date` instead of `date time`
* Allow any `fr` value in `GridCol` (e.g. `2fr`) — `fr` is no longer accepted as the `minmax()` minimum, which CSS treats as invalid

### v0.16.5

2026-09-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.5)

* Add `eslint-plugin-template-security` to the recommended eslint config — all its rules run as `error` on `.ts`, `.tsx`, `.js` and `.vue` files (and `.astro` with the `astro` option), so lint now reports template security issues such as unsafe `v-html`, `javascript:` URLs and `target` links without `rel="noopener"`

### v0.16.4

2026-09-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.4)

* Fix `update` in `createRestModelApi` item-scope actions not updating models with string ids — cached items are now matched by string ids as well as numeric ones
* Export `isQueryModelId` for checking a value against `QueryModelId` (a positive integer or a non-empty string)

### v0.16.3

2026-09-17 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.3)

* Add a `rel` prop to [WLink](/components/links) — forwarded to the rendered `a` or router-link, so `noopener noreferrer` can be set on external links
* Add a `rel` prop to [WButton](/components/button) — applied when the button renders as a link, via either `href` or `to`

### v0.16.2

2026-09-16 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.2)

* Allow clearing the date in [WInputDate](/components/input) — emptying the input now emits `update:model-value` with `undefined` instead of silently restoring the previous date
* Disable the month and year arrows in [WDatePicker](/components/date-picker) and [WDatePickerSingle](/components/date-picker) once `minDate` or `maxDate` is reached — navigation no longer runs past the allowed range, and the calendar opens inside it
* Fix `maxDate` being ignored in WDatePicker and WDatePickerSingle whenever `minDate` was also set — days, weeks and months after `maxDate` are now disabled

### v0.16.1

2026-09-12 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.1)

* Fix `target` being ignored on [WLink](/components/links) when `to` is set — it was only forwarded to plain `<a>` links, so router links always opened in the same tab
* Fix [WChip](/components/chip) ignoring the semantic type background — chips now use the chip color map and respond to `setSemanticTypeChipMap`, instead of always rendering on a gray background
* Fix [WList](/components/list) card layout leaving empty gaps for hidden fields — rows and columns whose areas are all hidden are now dropped from the card grid

### v0.16.0&#x20;

2026-09-09 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.16.0)

* **Breaking**: `useDefaultQuery` is replaced by `createDefaultQuery(modelKey, scope, name, queryFn, isQueryParams?, options?)` — a query is declared once and returns a ready `use` function carrying `config`, `setData`, `setItem` and `removeItem`, keyed as `[modelKey, scope, params, name]`, and a query without params is now called with `undefined` as its first argument
* Add `createRestModelApi` for declaring every query of a model in one config — each entry picks a scope (`single`, `item`, `list`, `paginated`) and gets its own `use` function, plus optional actions that receive `update`/`set`/`invalidate` and roll the cache back automatically when the request rejects
* **Breaking**: the global `QueryOptions`, `UseQueryEmpty`, `UseQueryWithParams` and `UseQueryPaginated` types are removed — `UseQueryDefault<Data, QueryParams>` replaces all four, and the `queryOptions` prop of [WList](/components/list), [WInfiniteList](/components/infinite-list) and [WSelectAsyncList](/components/select) now takes `DefaultQueryOptions<Data>`
* Editing an item in WList or WInfiniteList now updates it in every cached query of that model instead of only the page it was rendered on — the paginated response is no longer rewritten by index
* Fix option content overflowing its cell in [WSelect](/components/select) dropdowns

## 0.15

### v0.15.6

2026-09-01 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.6)

* Add `placeholderEmpty` prop to [WSelect](/components/select) and [WSelectAsync](/components/select) — a separate placeholder shown while nothing is selected, falling back to `placeholder` when not set
* Keep the WSelect placeholder visible while the field is focused instead of clearing it as soon as the input takes focus
* Fix tooltips interfering with the pointer — the tooltip dropdown container no longer captures pointer events, so hovering across it can no longer close or destabilise it

### v0.15.5

2026-08-31 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.5)

* Fix `update:count` in [WList](/components/list) emitting `undefined` before the list has loaded — the count is now emitted only when the list actually reports one
* Fix [WChip](/components/chip) wrapping its label onto several lines — chips now size to their content on a single line
* Update dependencies

### v0.15.4

2026-08-30 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.4)

* Fix [WTabs](/components/tabs) not switching to a tab whose error only appears after validation — the watcher now tracks the error state of the tab items themselves, not just the `hasError` prop, and stays put only while the current tab is one of the invalid ones
* Fix the require-save check in WTabs firing on the wrong tab — moving forward now submits when any tab being skipped over is marked `requireSave`, instead of looking at the tab you are leaving
* Drop the `enableStatus` prop from WTabs — tab status (changes, value, error) is now always tracked, so remove the prop from call sites
* Fix the [WButtonTab](/components/tabs) active underline always using the primary color when `indicator` was not set — it now follows the button's text color

### v0.15.3

2026-08-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.3)

* Render [WNavItemExpand](/components/nav-bar) as a plain nav item when its default slot is empty — no more empty dropdown wrapper around items that have no children
* Add an `indicator` prop to [WTabs](/components/tabs), forwarded to the tab titles — the indicator is now controlled explicitly instead of being inferred from `stepper`
* Fix WTabs container layout — the grid is applied consistently, and the side column template no longer applies in `flat` mode
* Fix spacing of the clear button in select option prefixes

### v0.15.2

2026-08-15 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.2)

* Fix [WInfiniteList](/components/infinite-list) requesting a wrong page when the list is empty
* Add `isVisible` to [WNavItemExpand](/components/nav-bar) exposed props

### v0.15.1

2026-08-11 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.1)

* Fix [WSelectAsync](/components/select) requesting the first page of options twice — its internal lookup query now uses the same page size as the dropdown list, so both share one cached response

### v0.15.0&#x20;

2026-08-10 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.15.0)

* **Breaking**: the `WListCard` export is gone — the row and card rendering of a list item are now one internal component, so any direct import of `eco-vue-js/dist/components/List/WListCard.vue` must be dropped ([WList](/components/list) itself is unaffected)
* Fix the click action on a list item resolving incorrectly — the row now picks exactly one behaviour (select, `hasAction`, `cardTo` link, or expansion toggle), so a list with `alwaysSelect` but selection disabled no longer renders a dead action, and a `cardTo` returning `undefined` for an item falls back to opening its expansion
* Fix WList not reserving the menu column when only `toMarkdown` is passed — `--w-list-right` now accounts for it, so those lists stop overlapping the more button
* Fix [WButton](/components/button) dropping its `class` while in the skeleton state — the class now lands on the skeleton too

## 0.14

### v0.14.4

2026-08-09 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.14.4)

* Fix [WListHeaderItem](/components/list) making a column sortable when it has no field to sort by — such columns now render as a plain header
* Fix [WList](/components/list) not picking up changes to `configKey` and `defaultConfigMap` — the list config now updates when either prop changes

### v0.14.3

2026-08-08 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.14.3)

* Fix `w-hover-circle` stretching into an ellipse on non-square targets — the overlay is now sized from its height and centred with `inset` / `margin: auto` instead of stretching to full width
* Fix the resizer not picking up dark styles — the dark rule was nested inside the `::-webkit-resizer` selector where it never matched, and is now a top-level rule that honours the `.light` opt-out
* Drop the `overflow-x-overlay` and `overflow-y-overlay` utilities — `overflow: overlay` is not supported by browsers; [WButtonDropdown](/components/dropdown-menu), [WSelectAsyncList](/components/select) and [WFilePicker](/components/file-picker) now use `overflow-x-auto` / `overflow-y-auto` instead

### v0.14.2

2026-08-08 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.14.2)

* Fix enter/leave transitions in [WTabs](/components/tabs), [WCheckbox](/components/checkbox) and [WButtonTab](/components/tabs) not animating movement or scaling — Tailwind v4 emits `scale` and `translate` as their own CSS properties, so listing `transform` in the transition never applied to them
* Fix [WNotify](/components/notify) cards not sliding in, for the same reason — the transition now lists `translate`
* Fix the `w-hover-circle` overlay stretching into an ellipse on non-square targets — it is now sized by height with `aspect-ratio: 1 / 1` and centred, instead of filling the box
* Shrink the [WButtonMore](/components/dropdown-menu) icon from `1.25em` to `1.125em` so it sits better inside its hover circle

### v0.14.1

2026-08-08 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.14.1)

* Fix `w-*` utilities that silently emitted no CSS after the Tailwind v4 migration — the theme, variants and utilities are now defined in CSS (`@theme`/`@utility`/`@custom-variant`) instead of JS plugins reading v3 theme scales
* Fix the hover circle opacity on [WCheckbox](/components/checkbox) — it used `w-hover-circle-opacity-0.08`, which produced nothing under v4; opacity utilities now take an integer percentage (`w-hover-circle-opacity-8`)
* Update the README Tailwind setup — no config file or preset is needed, just `@import "eco-vue-js/tailwind-base/base.css"` after `@import "tailwindcss"`

### v0.14.0&#x20;

2026-08-07 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.14.0)

* **Breaking**: the kit now targets Tailwind CSS v4 — consumers must upgrade `tailwindcss` to v4 and migrate their own setup before bumping
* **Breaking**: `tailwind-base` is consumed as CSS, not as a JS preset — drop it from `tailwind.config` and add `@import "eco-vue-js/tailwind-base/base.css"` to your stylesheet, which pulls in the theme and every `w-` plugin
* **Breaking**: theme colors are flattened to single-level keys — utility class names are unchanged (`bg-severity-critical-bg`, `text-black-default` still work), but plugin lookups move from `theme('colors.black.default')` to `theme('colors.black-default')`
* **Breaking**: the eslint Tailwind config now runs eslint-plugin-tailwindcss v4 and resolves the theme from CSS — pass `cssConfigPath` to `recommended()` if your stylesheet is not at `src/assets/styles/styles.css`. `classnames-order` is off for now so that consumer upgrades diff only what actually changed — v4 sorts classes differently and enabling it would touch almost every file; it comes back on in the next release
* Drop the bundled container-queries plugin — Tailwind v4 ships `@container` support natively

## 0.13

### v0.13.10

2026-08-03 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.10)

* Fix z-index stacking in [WModal](/components/modal) — each open modal now reserves two layers, so floating content inside a modal no longer collides with the modal stacked above it
* Keep the previous options visible in [WSelectAsync](/components/select) while a new request is in flight — the dropdown no longer flashes empty when the search text or query params change
* Fix [WInputSuggest](/components/input) dropdown spacing — drop the extra top margin that was applied when the list opened upward next to an error message or `maxLength` counter

### v0.13.9

2026-08-03 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.9)

* Add `contentVisibility` prop to [WList](/components/list) — rows opt into `content-visibility: auto` so offscreen rows skip layout and paint
* Skeleton rows now render plain placeholder cells instead of mounting every field component — set `customSkeleton` on a list field that draws a skeleton of its own to keep it mounted
* Fix nested list fields ignoring the configured column order — ordering is now applied recursively, and the sort runs once per list instead of once per row

### v0.13.8

2026-08-02 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.8)

* Add [WDropdownAdaptive](/components/dropdown-menu) — renders as [WDropdownMenu](/components/dropdown-menu) on desktop and [WBottomSheet](/components/bottom-sheet) on mobile, with a `closeOnClickOutside` prop and a `header` slot for the sheet title; [WInputSuggest](/components/input), the list table settings and the filter picker now use it
* Rework the local list filter — filters render as inline dropdowns in a single row instead of a collapsible side-tab panel, and picking a filter opens it right away
* Add `selectOnly` and `disableSelect` props to [WList](/components/list) — `selectOnly` hides the select-all checkbox and disables shift-range selecting while keeping row selection, `disableSelect` turns selection off entirely
* Pass the row `index` as a second argument to WList `formFieldGetter` and expose `uniformScope` to list menu items

### v0.13.7

2026-07-25 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.7)

* Move the export action in [WList](/components/list) into the bulk actions group — it no longer shows alongside list actions when nothing is selected
* Add `to`, `href`, `tag`, `target` and `replace` props to [WButtonSelectionAction](/components/list) so it can render as a link, matching the other buttons

### v0.13.6

2026-07-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.6)

* Fix ContentEditable allowing backspace/delete to strip the line container and corrupt the editor structure

### v0.13.5

2026-07-21 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.5)

* Stop refocusing the input after clicking the clear button in [WInput](/components/input)
* Remove the `min-w-40` minimum width from the input field when a `prefix` slot is present in WInput
* Forward the `before` slot in [WInputSuggest](/components/input) and expose `focused` in its scope

### v0.13.4

2026-07-21 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.4)

* Restore spacing between tab header and content in [WTabs](/components/tabs) for non-side mode (`mb-4` on the header, replacing the removed container `gap-4`)

### v0.13.3

2026-07-21 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.3)

* Fix `update:current-title` in [WTabs](/components/tabs) not emitting the initial title when the header is hidden (`no-header`) — the title is now watched directly instead of relying on tab activation
* Move header/content `gap-4` in WTabs to side mode only
* Add `submitText` and `disableMinHeight` props to [WModalStepper](/components/modal)

### v0.13.2

2026-07-20 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.2)

* Add default slot to [WButtonMoreItem](/components/dropdown-menu) for custom label content, `text` prop is now optional

### v0.13.1

2026-07-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.1)

* Fix eslint config module resolution: use `import-x/resolver-next` with `createTypeScriptImportResolver` — consumers no longer need `eslint-import-resolver-typescript` as a direct devDependency

### v0.13.0&#x20;

2026-07-18 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.13.0)

* **Breaking**: eslint config now uses eslint-plugin-import-x — rule namespace changed from `import/` to `import-x/`
* Support ESLint 10
* Fix toRef prop typing for vue >=3.5.40 generic components

## 0.12

### v0.12.62

2026-07-17 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.62)

* Disable redundant eslint rules
* Fix arrow rule config

### v0.12.61

2026-07-15 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.61)

* Fix tabs transition position

### v0.12.60

2026-07-11 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.60)

* Fix select prefix slot
* Fix button group props
* Fix input styles

### v0.12.59

2026-07-02 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.59)

* Add no mode setting for [WList](/components/list)

### v0.12.58

2026-07-02 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.58)

* Add input border class prop
* Add prefix prop for select async single

### v0.12.57

2026-06-28 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.57)

* Add page size to params

### v0.12.56

2026-06-27 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.56)

* Fix list padding between pages

### v0.12.55

2026-06-23 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.55)

* Fix tabs stepper intermediate submit

### v0.12.54

2026-06-21 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.54)

* Add stepper intermediate submit support

### v0.12.53

2026-06-19 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.53)

* Audit fix

### v0.12.52

2026-06-07 · [GitHub](https://github.com/rsmple/eco-vue-js/releases/tag/v0.12.52)

* Fix button icons size

---

---
url: https://rsmple.github.io/eco-vue-js/components/actions-bar.md
description: >-
  WActionsBar, WActionsBarFilter and WButtonAction — the app's bar of icon
  buttons on the right, with a filter panel that pages slide out of it.
---

# Actions bar

`WActionsBar` is the bar of icon buttons on the right of the [app shell](/guide/app-shell). It is `position: fixed`, `--w-actions-bar-width` wide, and takes `--actions-bar-width` in layout from `sm` up; on phones it is off-screen, and apps slide it in together with the open nav. Its class `w-actions-bar` is the hook for the app's surface and shadow.

Buttons go in the `top` and `bottom` slots — the filter button sits between them — and settings, such as a [theme toggle](/components/toggle#theme-toggle), in `footer` at the bottom.

## Action buttons

`WButtonAction` is the icon button of the actions bar. `title` names it in a tooltip, or under the icon with `titleText`, and for screen readers. It is a router link with `to`, an external link with `tag="a"` and `href`, and a button otherwise. `count` adds a badge, `active` colors the icon for a toggle that is on, and `loading` runs a shimmer while its action is in progress.

## Filters

`WActionsBarFilter` lets a page put its filters into the bar. Its default slot becomes a panel that slides out of the bar, and the bar gets a filter button with the `count` prop as its badge — titled by the bar's `textFilter`, which also heads the panel. The panel is `--actions-bar-filter-width` wide from `sm` up, and covers the screen next to the bar on phones. It renders nothing where it is placed, and takes the panel out of the bar when the page unmounts.

In the demo, the bar is fixed to the frame instead of the window. Click the filter button to slide out the panel.

```vue
<template>
  <!--
    The bar is `position: fixed` to the window in an app. The transform makes this frame the box it is fixed to,
    and the variables are the ones an app sets on `body`.
  -->
  <div
    class="
      relative h-96 overflow-hidden rounded-xl border border-solid border-line-subtle transform-[translateZ(0)]
      [--actions-bar-filter-width:16rem] [--header-height:3.5rem] [--right-margin:0px] [--w-actions-bar-width:3.5rem]
    "
  >
    <div class="grid gap-2 p-4 pr-18">
      <span class="font-semibold">Plants</span>
      <span class="text-description text-sm">
        {{ onlyThirsty ? 'Thirsty plants only' : 'All plants' }}{{ light ? `, ${ light } light` : '' }}
      </span>
    </div>

    <WActionsBar
      text-filter="Filters"
      class="bg-surface shadow-md"
    >
      <template #top>
        <WButtonAction
          title="Add plant"
          :icon="markRaw(IconAdd)"
          @click="added++"
        />

        <WButtonAction
          title="Water all"
          :icon="markRaw(IconDrop)"
          :loading="watering"
          @click="water"
        />

        <WButtonAction
          title="Alerts"
          :icon="markRaw(IconNotification)"
          :count="added"
          :active="added > 0"
          @click="added = 0"
        />
      </template>

      <template #footer>
        <WButtonAction
          title="Settings"
          :icon="markRaw(IconSettings)"
          title-text
        />
      </template>
    </WActionsBar>

    <WActionsBarFilter :count="(onlyThirsty ? 1 : 0) + (light ? 1 : 0)">
      <div class="grid gap-4 px-4">
        <WToggle
          v-model="onlyThirsty"
          title="Thirsty only"
        />

        <WCheckbox
          v-for="item in lights"
          :key="item"
          :model-value="light === item"
          :title="item"
          radio
          @update:model-value="light = $event ? item : undefined"
        />
      </div>
    </WActionsBarFilter>
  </div>
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import WActionsBar from 'eco-vue-js/dist/components/ActionsBar/WActionsBar.vue'
import WActionsBarFilter from 'eco-vue-js/dist/components/ActionsBar/WActionsBarFilter.vue'
import WButtonAction from 'eco-vue-js/dist/components/Button/WButtonAction.vue'
import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'
import IconDrop from 'eco-vue-js/dist/assets/icons/IconDrop'
import IconNotification from 'eco-vue-js/dist/assets/icons/IconNotification'
import IconSettings from 'eco-vue-js/dist/assets/icons/IconSettings'

const lights = ['Bright', 'Partial', 'Shade']

const onlyThirsty = ref(false)
const light = ref<string>()
const added = ref(0)
const watering = ref(false)

const water = () => {
  watering.value = true
  setTimeout(() => watering.value = false, 1500)
}
</script>
```

## API

### WActionsBar

```ts
import WActionsBar from 'eco-vue-js/dist/components/ActionsBar/WActionsBar.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `textFilter` | `string` | — | Title of the filter button and heading of the filter panel. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `top` | — | WButtonAction buttons at the top, above the filter button. |
| `bottom` | — | WButtonAction buttons under the filter button. |
| `footer` | — | Content at the bottom of the bar, such as settings. |

### WActionsBarFilter

```ts
import WActionsBarFilter from 'eco-vue-js/dist/components/ActionsBar/WActionsBarFilter.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | **required** | Number of filters set, shown as a badge on the filter button. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Filters, shown in the panel that slides out of the actions bar. |

### WButtonAction

```ts
import WButtonAction from 'eco-vue-js/dist/components/Button/WButtonAction.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `SVGComponent` | — | Icon of the button. The `icon` slot replaces it. |
| `title` | `string` | **required** | Name of the action, shown in a tooltip — or under the icon with `titleText` — and read by screen readers. |
| `active` | `boolean` | — | Colors the icon primary, for a toggle that is on. Only with the default `SECONDARY` type. |
| `tag` | `"button" \| "a"` | `"button"` | Element rendered without `to`: a `button`, or an `a` for an external link with `href`. |
| `href` | `string` | — | Link target when `tag` is `a`. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | `target` attribute of the link when `tag` is `a`. |
| `rel` | `string` | — | `rel` attribute of the link when `tag` is `a`. |
| `count` | `number` | — | Number in a badge on the corner, hidden at 0. |
| `semanticType` | `SemanticType` | `SemanticType.SECONDARY` | Color scheme of the button. |
| `disabled` | `boolean` | — | Grays the button out and ignores clicks. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the button and ignores clicks. |
| `tooltipText` | `string` | — | Tooltip text instead of `title`. |
| `titleText` | `boolean` | — | Shows `title` under the icon instead of in the tooltip. |
| `loading` | `boolean` | — | Runs a shimmer over the button while its action is in progress. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(event: MouseEvent)` | The button was clicked, unless it is disabled or a skeleton. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `icon` | — | Content of the button, replacing `icon`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/header-bar.md
description: >-
  WHeaderBar and WHeaderBarSearch — the app's fixed header with the page title
  and buttons, and a search that a page puts into it.
---

# Header bar

`WHeaderBar` is the fixed header of the [app shell](/guide/app-shell) — the one at the top of this page. It spans the whole width, `--header-height` tall; pad it by the bars beside it, e.g. `pl---nav-bar-width pr---actions-bar-width`, to keep its title and buttons between them. Below `xl` it leaves its top-left corner free for the nav's menu button.

The title is the `title` prop or the `title` slot, and the `right` slot goes after it, before the search button. Its background is translucent with a blur where the browser supports `backdrop-filter`, so the page shows through as it scrolls under.

## Search

`WHeaderBarSearch` puts a search into the header from any page, without touching the layout. Its default slot is shown in place of the header's title row, and the header gets a search button that opens it. The slot receives `visible`, `show` and `hide`; the `shown` prop opens it right away, and again whenever it turns `true`. It renders nothing where it is placed, and takes its content out of the header when the page unmounts.

```vue
<template>
  <div class="grid max-w-md gap-4">
    <span class="text-description text-sm">
      This page's header is a WHeaderBar: the search below is placed there, behind a search button on its right.
    </span>

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      @click="shown = !shown"
    >
      {{ shown ? 'Unmount the search' : 'Mount the search' }}
    </WButton>

    <WHeaderBarSearch
      v-if="shown"
      shown
    >
      <template #default="{hide}">
        <div class="flex w-full items-center gap-2">
          <WInput
            v-model="search"
            placeholder="Search plants"
            no-margin
            class="flex-1"
          />

          <WButton
            :semantic-type="SemanticType.SECONDARY"
            @click="hide?.()"
          >
            Close
          </WButton>
        </div>
      </template>
    </WHeaderBarSearch>

    <span
      v-if="search"
      class="text-sm"
    >
      Searching for “{{ search }}”
    </span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WHeaderBarSearch from 'eco-vue-js/dist/components/HeaderBar/WHeaderBarSearch.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'

const shown = ref(false)
const search = ref<string>()
</script>
```

## Route titles

Without a `title` prop or slot, the header shows the titles of the current route as one line: its parent pages as muted links and the page's own title in bold. Each level of `route.matched` takes its title from the page, or from its `meta.title`.

A page reports a title that depends on its data from setup with `useRouteTitle`. It registers the title for the route record the page is rendered by, and removes it when the page unmounts:

```ts
import {useRouteTitle} from 'eco-vue-js/dist/utils/useRouteTitle'

useRouteTitle(() => ({
  title: query.data.value?.name,
  suffix: ProductTitleSuffix,
}))
```

* `title` is `undefined` while the data loads, and the header shows a placeholder.
* `titleShort` goes to the breadcrumb, the browser tab and nav items, instead of `title`.
* `documentTitle` goes to the browser tab only — e.g. a long name the page shows in full in its body, while the header shows a short label.
* `to` is the breadcrumb link while a child page is open. It defaults to the level's named route, then its named `''` child, then its `redirect`.
* `suffix` is a component shown after the title, only while the page is the current one — a parent page's chips leave the header on its child pages.
* `trail` adds levels after the page that are not routes, such as the active filter of a list. The page level becomes a link (set its `to` to keep the other filters), and the last trail level is the current one, with its own `suffix`:

```ts
useRouteTitle(() => ({
  title: t('nav.pipelines'),
  to: {query: {...route.query, status: undefined}},
  trail: status.value ? [{title: statusTitleMap[status.value], suffix: WorkersText}] : [],
  suffix: WorkersText,
}))
```

Records that share a path, such as a parent and its `''` child, are one level, so a parent layout can title its index page.

The same titles fill other places:

* `useDocumentTitle(suffix)` keeps `document.title` in sync, page first: `payments/api · Payments Platform · App`. Call it once in the app's root component.
* WNavItem shows the short title its route's page registers, while the page is open, so a nav item of an item page shows the item instead of a static "Item".
* `useRouteTitles()` returns the levels for a custom header.

## API

### WHeaderBar

```ts
import WHeaderBar from 'eco-vue-js/dist/components/HeaderBar/WHeaderBar.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Title of the page. The `title` slot replaces it. Without both, the header shows the titles of the current route: a breadcrumb of its parents and the page title, see `useRouteTitle`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `right` | — | Content after the title, before the search button. |

### WHeaderBarSearch

```ts
import WHeaderBarSearch from 'eco-vue-js/dist/components/HeaderBar/WHeaderBarSearch.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shown` | `boolean` | — | Opens the search right away, and again whenever it becomes `true`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ visible?: boolean \| undefined; hide?: (() => void) \| undefined; show?: (() => void) \| undefined; }` | Search content shown in place of the header's title row when the search button is clicked. `hide` goes back to the title. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/nav-bar.md
description: >-
  WNavBar, WNavItem, WNavItemExpand and WNavItemTransition — the app's left nav
  that docks on wide screens and opens from the header below, with router-link
  items, groups and counters.
---

# Nav bar

`WNavBar` is the nav on the left of the [app shell](/guide/app-shell) — the one on the left of this page. It is `position: fixed` under the header and takes `--nav-bar-width` in layout from `xl` (1280px) up. Below it, it collapses and adds a menu button in the header's top-left corner, and opens as an overlay over the page; it emits `update:is-open` when the overlay opens or closes. Its class `w-nav-bar` is the hook for the app's surface and shadow, and its content uses `w-nav-bar-width` to keep its width while the nav collapses.

## Nav items

`WNavItem` is a router link with an icon and a title. Both default to the route's `meta.icon` and `meta.titleShort` (or `meta.title`), so an item is often just `<WNavItem :to="{name: RouteName.PROJECTS}" />`. It is active while the current route has the same name; `queryFields` lists the query params that must match too, for items that open the same route with different filters. `count` shows a number in brackets after the title and `counter` a badge, with `skeleton` while they load.

`WNavItemExpand` groups items under a title. The items show under it while one of them is active; otherwise hovering the group opens them in a menu to the right. With `to`, the group is a link of its own. `even` keeps the items always shown and not indented, for a nav inside a page.

`WNavItemTransition` wraps a list of items so that the ones added or removed with `v-if` — such as an item for the current record — expand and collapse.

The demo below uses `even` to show a group inside a page. Its items link to pages of this site, so the one you're on is active.

```vue
<template>
  <div class="grid max-w-xs gap-4">
    <WToggle
      v-model="showRecent"
      title="Show the recent page"
    />

    <div class="rounded-xl border border-solid border-line-subtle py-2">
      <WNavItemTransition>
        <WNavItemExpand
          title="Layout"
          :icon="markRaw(IconMenu)"
          :query-fields="[]"
          even
        >
          <WNavItem
            :to="{path: '/components/nav-bar'}"
            title="Nav bar"
            :icon="markRaw(IconList)"
            :query-fields="[]"
          />

          <WNavItem
            :to="{path: '/components/header-bar'}"
            title="Header bar"
            :icon="markRaw(IconHeading)"
            :count="2"
            :query-fields="[]"
          />

          <WNavItem
            :to="{path: '/components/actions-bar'}"
            title="Actions bar"
            :icon="markRaw(IconElement)"
            :counter="3"
            :query-fields="[]"
          />

          <WNavItem
            v-if="showRecent"
            :to="{path: '/components/report-pages'}"
            title="Report pages"
            :icon="markRaw(IconNote)"
            :query-fields="[]"
          />
        </WNavItemExpand>
      </WNavItemTransition>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import WNavItem from 'eco-vue-js/dist/components/Nav/WNavItem.vue'
import WNavItemExpand from 'eco-vue-js/dist/components/Nav/WNavItemExpand.vue'
import WNavItemTransition from 'eco-vue-js/dist/components/Nav/WNavItemTransition.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

import IconElement from 'eco-vue-js/dist/assets/icons/IconElement'
import IconHeading from 'eco-vue-js/dist/assets/icons/IconHeading'
import IconList from 'eco-vue-js/dist/assets/icons/IconList'
import IconMenu from 'eco-vue-js/dist/assets/icons/IconMenu'
import IconNote from 'eco-vue-js/dist/assets/icons/IconNote'

const showRecent = ref(false)
</script>
```

In an app the items open routes by name:

```vue
<WNavItemTransition>
  <WNavItem :to="{name: RouteName.PROJECTS}" />

  <WNavItem
    v-if="$route.name === RouteName.PROJECT"
    :to="{name: RouteName.PROJECT, params: {projectId: $route.params.projectId}}"
  />

  <WNavItemExpand
    title="Plants"
    :icon="markRaw(IconPlant)"
    :count="plantCount"
  >
    <WNavItem
      :to="{name: RouteName.PLANTS, query: {status: 'thirsty'}}"
      title="Thirsty"
      :query-fields="['status']"
    />

    <WNavItem
      :to="{name: RouteName.PLANTS, query: {status: 'watered'}}"
      title="Watered"
      :query-fields="['status']"
    />
  </WNavItemExpand>
</WNavItemTransition>
```

## API

### WNavBar

```ts
import WNavBar from 'eco-vue-js/dist/components/Nav/WNavBar.vue'
```

#### Props

*No props.*

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:is-open` | `(value: boolean)` | The nav opened or closed below `xl`, where it is an overlay. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content of the nav, such as WNavItem items. |

### WNavItem

```ts
import WNavItem from 'eco-vue-js/dist/components/Nav/WNavItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `SVGComponent` | — | Icon before the title. Defaults to the route's `meta.icon`. |
| `title` | `string` | — | Title of the item. Defaults to the title the route's page registers with `useRouteTitle` while it is open, then the route's `meta.titleShort`, then `meta.title`. |
| `count` | `number` | — | Number after the title in brackets, such as the number of items on the page it opens. |
| `counter` | `number` | — | Number in a badge over the end of the title, such as unread items. Hidden at 0. |
| `skeleton` | `boolean` | — | Shows a placeholder for `count` and hides `counter`, while they load. |
| `hasActive` | `boolean` | — | Marks the item as the parent of the active item. Set by WNavItemExpand. |
| `expand` | `boolean` | — | Marks the item as the toggle of a group without a route of its own. Set by WNavItemExpand. |
| `indent` | `boolean` | — | Indents the item as a child of a group. Set by WNavItemExpand. |
| `queryFields` | `string[]` | — | Query params that must match the current route's for the item to be active, besides its route name. Other params, such as filters, are ignored. |
| `hovered` | `boolean` | — | Highlights the item as hovered. Set by WNavItemExpand while its menu is open. |
| `even` | `boolean` | — | Lays the item out without the indent of a group. Set by WNavItemExpand. |
| `to` | `RouteLocationRaw` | **required** | Router location — renders a router link. Needs vue-router installed in the app. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `icon` | — | Icon before the title, when neither `icon` nor the route's `meta.icon` is set. |
| `right` | — | Content at the end of the item. |

### WNavItemExpand

```ts
import WNavItemExpand from 'eco-vue-js/dist/components/Nav/WNavItemExpand.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `SVGComponent` | — | Icon before the title. |
| `title` | `string` | **required** | Title of the group. |
| `count` | `number` | — | Number after the title in brackets. |
| `counter` | `number` | — | Number in a badge over the end of the title. Hidden at 0. |
| `skeleton` | `boolean` | — | Shows a placeholder for `count` and hides `counter`, while they load. |
| `indent` | `boolean` | — | Indents the group as a child of another group. |
| `queryFields` | `string[]` | — | Query params that must match the current route's for the group's own route to be active. |
| `even` | `boolean` | — | Keeps the items always shown, without indent and without the menu on hover, e.g. for a nav inside a page. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | WNavItem items of the group. They show under the group while one of them is active, and in a menu on hover otherwise. |
| `icon` | — | Icon before the title, when `icon` isn't set. |

### WNavItemTransition

```ts
import WNavItemTransition from 'eco-vue-js/dist/components/Nav/WNavItemTransition.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Nav items. Items added or removed with `v-if` expand and collapse. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/button.md
description: >-
  WButton — the base action element with semantic colors, loading and disabled
  states, links and tooltips — plus WButtonCopy and WButtonInput.
---

# Button

`WButton` is the base action element. It renders a `<button>` by default, a router link when `to` is set, and an `<a>` with `tag="a"` and `href`. Every other button in this folder (`WButtonMore`, `WButtonCopy`, `WButtonSelection`…) builds on it. For picking one value out of a few, see [Button group](./button-group).

## Basic usage

Put any content in the default slot. For icon-only buttons, set `tooltipText` — it is shown on hover and gives the button a readable hint.

```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <WButton @click="count++">
      Clicked {{ count }} times
    </WButton>

    <WButton outline>
      Outline
    </WButton>

    <WButton tooltip-text="Add item">
      <IconAdd class="square-5" />
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'

const count = ref(0)
</script>
```

## Semantic types

`semanticType` picks the color scheme. The classes behind each type are app-wide and can be swapped once at startup with `setSemanticTypeButtonBackgroundMap` from `eco-vue-js/dist/utils/SemanticType`.

```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <WButton
      v-for="type in Object.values(SemanticType)"
      :key="type"
      :semantic-type="type"
    >
      {{ type }}
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
</script>
```

## States

* `loading` hides the content behind a spinner but keeps the width, so the layout does not jump. Clicks are ignored.
* `disabled` and `skeleton` fall back to the state provided by a parent when not set. A form or list that is disabled or loading disables or skeletons every button inside it — only pass these props to override that.

```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <WButton
      :loading="saving"
      @click="save"
    >
      Save
    </WButton>

    <WButton disabled>
      Disabled
    </WButton>

    <WButton skeleton>
      Skeleton
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

const saving = ref(false)

const save = () => {
  saving.value = true

  setTimeout(() => saving.value = false, 1500)
}
</script>
```

## Small buttons

`WButtonCopy` copies `value` to the clipboard. Its icon turns into a check for a moment after copying. By default it takes up one line of the surrounding text, so it sits inside a sentence without changing the line height; `noInline` lays it out as a regular block instead.

`WButtonInput` is a square icon button as tall as an input (`--w-input-height`), with the input's border and corners, to sit next to an input or in its `right` slot. `tooltipText` names it, `loading` swaps the icon for a spinner, and `to` makes it a router link.

```vue
<template>
  <div class="grid gap-6">
    <div class="flex items-center gap-2">
      <code class="rounded-lg bg-surface-muted px-2 py-1">{{ token }}</code>

      <WButtonCopy :value="token" />
    </div>

    <div class="flex max-w-md items-center gap-2">
      <WInput
        v-model="search"
        placeholder="Sensor"
        class="flex-1"
        no-margin
      />

      <WButtonInput
        :icon="markRaw(IconRefresh)"
        tooltip-text="Sync sensors"
        :loading="syncing"
        @click="sync"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import WButtonCopy from 'eco-vue-js/dist/components/Button/WButtonCopy.vue'
import WButtonInput from 'eco-vue-js/dist/components/Button/WButtonInput.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'

import IconRefresh from 'eco-vue-js/dist/assets/icons/IconRefresh'

const token = 'gh2_4f9c2e1a7b'
const search = ref<string>()
const syncing = ref(false)

const sync = () => {
  syncing.value = true
  setTimeout(() => syncing.value = false, 1500)
}
</script>
```

## API

### WButton

```ts
import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `semanticType` | `SemanticType` | `SemanticType.PRIMARY` | Color scheme. Classes per type are app-wide and can be overridden with `setSemanticTypeButtonBackgroundMap`. |
| `disabled` | `boolean` | — | Blocks clicks and dims the button. When unset, inherits the disabled or readonly state provided by a parent. |
| `loading` | `boolean` | — | Replaces the content with a spinner and swallows clicks, keeping the button's width. |
| `tag` | `keyof HTMLElementTagNameMap` | `"button"` | Element to render when neither `to` nor `href` applies. |
| `type` | `string` | — | Native `type` attribute, e.g. `submit` inside a form. |
| `replace` | `boolean` | — | With `to`, replaces the current history entry instead of pushing a new one. |
| `href` | `string` | — | Link target when `tag` is `a`. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | Native `target` of the link, with `href` or `to`. |
| `rel` | `string` | — | Native `rel` of the link, with `href` or `to`. |
| `join` | `boolean` | — | Squares off inner corners and borders so adjacent buttons read as one segmented control. |
| `tooltipText` | `string` | — | Shows a tooltip on hover — also the accessible hint for icon-only buttons. |
| `download` | `string` | — | Native `download` attribute, used with `tag="a"` and `href`. |
| `skeleton` | `boolean` | — | Renders a skeleton placeholder of the button's size. When unset, inherits the skeleton state provided by a parent. |
| `autofocus` | `boolean` | — | Focuses the button after mount and whenever it becomes enabled again. |
| `outline` | `boolean` | — | Border and text only, no background fill. |
| `borderComponent` | `VNode` | — | Custom decorative border layer, overriding the one registered for the `semanticType`. |
| `noBorderComponent` | `boolean` | — | Skips the decorative border layer. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(event: MouseEvent \| KeyboardEvent)` | Click or Enter. Not emitted while disabled or `loading`. |
| `mousedown` | `(event: MouseEvent)` | Mouse down. Not emitted while disabled or `loading`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Button content. |

### WButtonCopy

```ts
import WButtonCopy from 'eco-vue-js/dist/components/Button/WButtonCopy.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | **required** | Text copied to the clipboard on click. |
| `noInline` | `boolean` | — | Lays the button out as a regular block instead of sizing it to one line of the surrounding text. |

### WButtonInput

```ts
import WButtonInput from 'eco-vue-js/dist/components/Button/WButtonInput.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `SVGComponent` | **required** | Icon of the button. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |
| `tooltipText` | `string` | — | Tooltip text, which also names the button. |
| `loading` | `boolean` | — | Shows a spinner instead of the icon and ignores clicks. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the button. |
| `disabled` | `boolean` | — | Grays the button out and ignores clicks. |
| `active` | `boolean` | — | Highlights the button, such as while the menu it opens is shown. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The button was clicked, unless it is disabled or loading. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/links.md
description: >-
  WLink and WLinkArrow text links, and WRouterLink that works with or without
  vue-router.
---

# Links

`WLink` is a link inside text, with an icon in a colored chip before it — a link icon by default, or `icon`. The text is `text` or the default slot. It is a router link with `to` and a plain link with `href`; `target` and `rel` go on the link either way. `semanticType` sets the color, primary by default.

`WLinkArrow` is a quiet "more" link with an arrow after the text, e.g. under a short list: `<WLinkArrow :to="{name: RouteName.PLANTS}" text="All plants" />`.

`WRouterLink` renders the app's `RouterLink` with `to`, and a plain `a` with `href` otherwise — also in an app without vue-router. The kit's links and buttons are built on it.

```vue
<template>
  <p class="max-w-xl leading-relaxed">
    Each plant links to its
    <WLink
      href="https://en.wikipedia.org/wiki/Monstera_deliciosa"
      text="Monstera deliciosa"
      target="_blank"
      rel="noopener"
    />
    article. The
    <WLink
      href="https://www.rhs.org.uk/plants"
      target="_blank"
      rel="noopener"
      :semantic-type="SemanticType.INFO"
      :icon="markRaw(IconArchiveBook)"
    >
      RHS plant guide
    </WLink>
    explains how to care for it.
  </p>
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WLink from 'eco-vue-js/dist/components/Link/WLink.vue'

import IconArchiveBook from 'eco-vue-js/dist/assets/icons/IconArchiveBook'
</script>
```

## API

### WLink

```ts
import WLink from 'eco-vue-js/dist/components/Link/WLink.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | URL of the link, when there is no `to`. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | `target` attribute of the link. |
| `rel` | `string` | — | `rel` attribute of the link. |
| `text` | `string` | — | Text of the link. The default slot replaces it. |
| `semanticType` | `SemanticType` | `SemanticType.PRIMARY` | Color of the text and the icon's chip. |
| `icon` | `SVGComponent` | — | Icon before the text, in a chip. Defaults to a link icon. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Text of the link, replacing `text`. |

### WLinkArrow

```ts
import WLinkArrow from 'eco-vue-js/dist/components/Link/WLinkArrow.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | Text of the link. The default slot replaces it. |
| `to` | `RouteLocationRaw` | **required** | Router location — renders a router link. Needs vue-router installed in the app. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Text of the link, replacing `text`. |

### WRouterLink

```ts
import WRouterLink from 'eco-vue-js/dist/components/RouterLink/WRouterLink.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | — | URL of a plain link, used when `to` is empty. |
| `replace` | `boolean` | — | Replaces the current history entry instead of adding one, with `to`. |
| `to` | `RouteLocationRaw` | **required** | Router location — renders a router link. Needs vue-router installed in the app. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content of the link. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/input.md
description: >-
  WInput — text, number, password and multiline inputs with titles, clear
  button, states and validation, plus WInputAsync and WInputDate.
---

# Input

`WInput` is a text field bound with `v-model`. It renders its own title, description and error message, so a form row is a single component. The other inputs in this folder wrap it: `WInputAsync` adds validation, `WInputSuggest` a dropdown, `WInputOptions` a list of suggestions and `WInputDate` a date picker.

## Basic usage

`type="number"` makes the model a `number`; everything else is a `string`. `textarea` switches to a multiline field that grows with its content, `resize` lets the user drag it taller. `allowClear` adds a clear button. Clearing or deleting all the text emits `''` — or `undefined` or `null` set with `clearValue`, which also narrows the emitted type. `icon` adds an icon at the start.

```vue
<template>
  <div class="grid max-w-md gap-2">
    <WInput
      v-model="name"
      title="Name"
      placeholder="Monstera"
      allow-clear
    />

    <WInput
      v-model="search"
      placeholder="Search"
      :icon="IconSearch"
      allow-clear
    />

    <WInput
      v-model="year"
      type="number"
      title="Year"
      :min="0"
      :max="2100"
    />

    <WInput
      v-model="notes"
      title="Notes"
      textarea
      resize
    />
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'

import IconSearch from 'eco-vue-js/dist/assets/icons/IconSearch'

const name = ref<string>()
const search = ref<string>()
const year = ref<number>()
const notes = ref<string>()
</script>
```

## States

* `title`, `description` and `errorMessage` render around the field. `required` adds an asterisk to the title.
* `readonly`, `disabled` and `skeleton` fall back to the state provided by a parent, the same way as for buttons — a readonly form makes every input inside it readonly.

```vue
<template>
  <div class="grid max-w-md gap-2">
    <WInput
      model-value="Moby-Dick"
      title="Required"
      description="Shown under the title."
      required
    />

    <WInput
      model-value="1851"
      title="With an error"
      error-message="Must be after 1900"
    />

    <WInput
      model-value="Read only"
      title="Readonly"
      readonly
    />

    <WInput
      model-value="Disabled"
      title="Disabled"
      disabled
    />

    <WInput
      title="Skeleton"
      skeleton
    />
  </div>
</template>

<script lang="ts" setup>
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
</script>
```

## Validation

`WInputAsync` edits a local copy and saves it on Enter or blur (or after `debounce`). `validate` — one function or a list — returns an error message or `undefined`; an invalid value shows the error and is not saved, so the parent only ever receives valid values.

```vue
<template>
  <WInputAsync
    v-model="email"
    title="Email"
    placeholder="name@example.com"
    :validate="[required, isEmail]"
    class="max-w-md"
  />

  <p class="text-sm text-description">
    Saved value: {{ email || '—' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WInputAsync from 'eco-vue-js/dist/components/Input/WInputAsync.vue'

const email = ref<string>()

const required: ValidateFn = value => value ? undefined : 'Required'
const isEmail: ValidateFn = value => typeof value === 'string' && value.includes('@') ? undefined : 'Not an email'
</script>
```

## Suggestions

`WInputOptions` is a free-text input with a list of suggestions under it. Arrow keys move through the list, Enter or a click puts the option's `valueGetter` value into the input. The list is not filtered for you — pass the options that match the current text.

`WInputSuggest` is the same input with an empty menu: put anything into its `content` slot, and call the slot's `blur` to close it.

```vue
<template>
  <WInputOptions
    v-model="plant"
    title="Plant"
    placeholder="Start typing"
    :options="filtered"
    :value-getter="option => option.name"
    empty-stub="No such plant"
    allow-clear
    class="max-w-md"
  >
    <template #option="{option}">
      <div class="w-option flex items-center">
        {{ option?.emoji }} {{ option?.name }}
      </div>
    </template>
  </WInputOptions>

  <p class="text-sm text-description">
    Model: {{ plant || '—' }}
  </p>
</template>

<script lang="ts" setup>
import {computed, ref} from 'vue'

import WInputOptions from 'eco-vue-js/dist/components/Input/WInputOptions.vue'

const plants = [
  {id: 1, name: 'Cactus', emoji: '🌵'},
  {id: 2, name: 'Clover', emoji: '🍀'},
  {id: 3, name: 'Rose', emoji: '🌹'},
  {id: 4, name: 'Sunflower', emoji: '🌻'},
  {id: 5, name: 'Tulip', emoji: '🌷'},
  {id: 6, name: 'Hibiscus', emoji: '🌺'},
]

const plant = ref<string | null>()

const filtered = computed(() => plants.filter(item => item.name.toLowerCase().includes(plant.value?.toLowerCase() ?? '')))
</script>
```

The suggestions can come from a paginated query instead: pass `useQueryFnOptions` and `queryParamsOptions` in place of `options`. The typed text is sent in `searchField` (`search` by default), more pages load as the menu scrolls, and `optionComponent` takes the same components as `WSelectAsync`. The value stays free text — a suggestion only fills it in.

With `draft`, typing changes only the suggestions, not the value. An apply row at the top of the menu shows the typed text; it, Enter, or a picked suggestion sets the value, and closing the menu drops the draft. Use it where every change is costly, like a list filter.

```vue
<template>
  <WInputOptions
    v-model="variety"
    title="Variety"
    placeholder="Type any name or pick a known one"
    :use-query-fn-options="varietyModelApi.paginated.use"
    :query-params-options="{}"
    :value-getter="option => option.name"
    :option-component="OptionVariety"
    empty-stub="No known variety"
    draft
    allow-clear
    class="max-w-xl"
  />

  <p class="text-sm text-description">
    Model: {{ variety || '—' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WInputOptions from 'eco-vue-js/dist/components/Input/WInputOptions.vue'

import {varietyModelApi} from '../../../Select/docs/examples/api/garden'
import OptionVariety from '../../../Select/docs/examples/parts/OptionVariety.vue'

const variety = ref<string | null>()
</script>
```

## Date

`WInputDate` binds a `Date` and opens a calendar. The user can also type a date; `minDate` and `maxDate` limit both.

```vue
<template>
  <WInputDate
    v-model="date"
    title="Due date"
    :min-date="new Date()"
    class="max-w-md"
  />

  <p class="text-sm text-description">
    Model: {{ date?.toDateString() ?? '—' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WInputDate from 'eco-vue-js/dist/components/Input/WInputDate.vue'

const date = ref<Date>()
</script>
```

## Toolbar

A textarea with `rich` gets a toolbar of formatting buttons; `toolbarActions` adds your own. Each action wraps the selected text: `value` is a `WrapSelection`, such as a start and end marker to toggle, and a list of them makes a group that opens on hover. `WInputToolbarButton` is the button itself, for the `toolbar` slot of `WInputSuggest` when a button needs more than a formatting — call the slot's `wrapSelection` from its `click`.

## API

### WInput

```ts
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `(Type extends "number" ? number : string) \| null` | — | Field value — a `number` when `type` is `number`, otherwise a `string`. |
| `type` | `Type` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | `10` | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `maxSizeKb` | `number` | `100` | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | `"off"` | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `unclickable` | `boolean \| null` | `null` | Blocks typing and turns a click into a `focus` event, for fields that open a menu instead of taking text. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowClear` | `boolean` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared or emptied by editing. Defaults to `''` (`undefined` for `type="number"`); set it explicitly to emit `undefined` or `null`. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `async` | `boolean` | — | Keeps edits local and emits them only when saved — on Enter or blur — instead of on every keystroke. |
| `debounce` | `number` | — | With `async`, also saves after this many ms without typing, showing a progress bar under the text. |
| `hideDebounce` | `boolean` | — | Hides the `debounce` progress bar. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(EmitType)` | The new value — on every change, or only when saved with `async`. |
| `keypress:enter` | `(KeyboardEvent)` | Enter without modifiers. Not emitted by an `async` single-line input, where Enter saves. |
| `keypress:up` | `(KeyboardEvent)` | Arrow Up without modifiers. |
| `keypress:down` | `(KeyboardEvent)` | Arrow Down without modifiers. |
| `keypress:delete` | `(KeyboardEvent)` | Backspace or Delete without modifiers. |
| `click:clear` | — | The clear button was clicked. |
| `focus` | `(FocusEvent \| undefined)` | The input got focus. With `unclickable`, emitted on click with no event. |
| `blur` | `(FocusEvent)` | The input lost focus. |
| `click` | `(MouseEvent)` | Click on the input, or on the button that reveals a `textSecure` value. |
| `mousedown` | `(MouseEvent)` | Mouse down on the input. Stopped from reaching the field. |
| `select:input` | `(Event)` | Native `select` event of the input — the text selection changed. |
| `paste` | — | A value was pasted with the paste button. |
| `rendered` | `(HTMLElement[])` | The textarea rendered its `textParts`, with the tagged elements in order. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `prefix` | `{ modelValue: (Type extends "number" ? number : string) \| null \| undefined; }` | Content before the text inside the field, such as chips. Also shown while readonly. |
| `before` | `{ modelValue: (Type extends "number" ? number : string) \| null \| undefined; focused: boolean; }` | Content right before the text, in the same box as the input. |
| `toolbar` | `{ wrapSelection: (value: WrapSelection) => void; }` | Extra buttons in the textarea toolbar — `wrapSelection` applies a formatting to the selected text. Shows the toolbar on its own. |
| `after` | — | Content right after the text, in the same box as the input. |
| `suffix` | `{ loading: boolean; disabled: boolean; }` | Buttons after the clear, paste and copy buttons. `disabled` is also set by `disabledActions`. |
| `inner` | — | Content at the end of the field box, after the action buttons. |
| `right` | — | Content to the right of the field. |
| `bottom` | — | Content under the field, above the Save and Cancel buttons of an `async` input. |

### WInputAsync

```ts
import WInputAsync from 'eco-vue-js/dist/components/Input/WInputAsync.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `validate` | `ValidateFn \| ValidateFn[]` | — | Checks the value before it is saved. A returned error message is shown under the field and the value is not emitted. |
| `modelValue` | `(Type extends "number" ? number : string) \| null` | — | Field value — a `number` when `type` is `number`, otherwise a `string`. |
| `type` | `Type` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `unclickable` | `boolean \| null` | `null` | Blocks typing and turns a click into a `focus` event, for fields that open a menu instead of taking text. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowClear` | `boolean` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared or emptied by editing. Defaults to `''` (`undefined` for `type="number"`); set it explicitly to emit `undefined` or `null`. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `async` | `boolean` | — | Keeps edits local and emits them only when saved — on Enter or blur — instead of on every keystroke. |
| `debounce` | `number` | — | With `async`, also saves after this many ms without typing, showing a progress bar under the text. |
| `hideDebounce` | `boolean` | — | Hides the `debounce` progress bar. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(EmitType)` | The saved value — on Enter, blur, `debounce` or Save — once it passes `validate`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | — | Content to the right of the field. |
| `prefix` | `{ modelValue: (Type extends "number" ? number : string) \| null \| undefined; }` | Content before the text inside the field, such as chips. Also shown while readonly. |
| `before` | `{ modelValue: (Type extends "number" ? number : string) \| null \| undefined; focused: boolean; }` | Content right before the text, in the same box as the input. |

### WInputSuggest

```ts
import WInputSuggest from 'eco-vue-js/dist/components/Input/WInputSuggest.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |
| `modelValue` | `(Type extends "number" ? number : string) \| null` | — | Field value — a `number` when `type` is `number`, otherwise a `string`. |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `Type` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowClear` | `boolean` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared or emptied by editing. Defaults to `''` (`undefined` for `type="number"`); set it explicitly to emit `undefined` or `null`. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `async` | `boolean` | — | Keeps edits local and emits them only when saved — on Enter or blur — instead of on every keystroke. |
| `debounce` | `number` | — | With `async`, also saves after this many ms without typing, showing a progress bar under the text. |
| `hideDebounce` | `boolean` | — | Hides the `debounce` progress bar. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `horizontalAlign` | `HorizontalAlign` | `HorizontalAlign.FILL` | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(EmitType)` | The typed value. Not emitted while `loading`. |
| `keypress:enter` | `(KeyboardEvent)` | Enter without modifiers. |
| `keypress:up` | `(KeyboardEvent)` | Arrow Up without modifiers. |
| `keypress:down` | `(KeyboardEvent)` | Arrow Down without modifiers. |
| `keypress:delete` | `(KeyboardEvent)` | Backspace or Delete without modifiers. |
| `open` | — | The menu opened, on focus. |
| `close` | — | The menu closed. |
| `click:clear` | — | The clear button was clicked. |
| `focus` | `(FocusEvent \| undefined)` | The input got focus. On mobile, not emitted by the field that opens the bottom sheet. |
| `blur` | `(FocusEvent)` | The input lost focus. On mobile, not emitted by the field that opens the bottom sheet. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `toolbar` | `{ wrapSelection: (value: WrapSelection) => void; }` | Extra buttons in the textarea toolbar — `wrapSelection` applies a formatting to the selected text. Shows the toolbar on its own. |
| `prefix` | `{ unclickable?: boolean \| null \| undefined; }` | Content before the text inside the field, such as chips. `unclickable` is `true` for the field that opens the mobile bottom sheet. |
| `before` | `{ modelValue: (Type extends "number" ? number : string) \| null \| undefined; focused: boolean; }` | Content right before the text, in the same box as the input. |
| `right` | `{ unclickable?: boolean \| null \| undefined; }` | Content to the right of the field. `unclickable` is `true` for the field that opens the mobile bottom sheet. |
| `bottom` | — | Content under the field, after a `static` menu. |
| `content` | `{ focused: boolean; blur: () => void; focus: () => void; }` | Menu content. `focus` and `blur` move focus to and from the input, which opens and closes the menu. |

### WInputOptions

```ts
import WInputOptions from 'eco-vue-js/dist/components/Input/WInputOptions.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |
| `modelValue` | `(Type extends "number" ? number : string) \| null` | — | Field value — a `number` when `type` is `number`, otherwise a `string`. |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `Type` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowClear` | `boolean` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared or emptied by editing. Defaults to `''` (`undefined` for `type="number"`); set it explicitly to emit `undefined` or `null`. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `async` | `boolean` | — | Keeps edits local and emits them only when saved — on Enter or blur — instead of on every keystroke. |
| `debounce` | `number` | — | With `async`, also saves after this many ms without typing, showing a progress bar under the text. |
| `hideDebounce` | `boolean` | — | Hides the `debounce` progress bar. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `options` | `Option[]` | — | Suggestions shown in the menu. Filter them by the typed text yourself. Use either this or `useQueryFnOptions`. |
| `useQueryFnOptions` | `UseQueryDefault<PaginatedResponse<Option>, QueryParams>` | — | Paginated query that loads the suggestions, page by page as the menu scrolls. The typed text is sent in `searchField`. Use either this or `options`. |
| `queryParamsOptions` | `QueryParams` | — | Parameters for `useQueryFnOptions`. |
| `searchField` | `keyof QueryParams` | — | Query parameter that receives the typed text. Defaults to `search`. |
| `valueGetter` | `(option: Option) => (Type extends "number" ? number : string) & {}` | **required** | Value an option puts into the input. |
| `emptyStub` | `string` | — | Text shown when there are no suggestions. Defaults to "No suggestion". |
| `draft` | `boolean` | — | Treats the typed text as a draft: it only drives the suggestions, and the value changes when a suggestion is picked, on Enter, or from the apply row at the top of the menu. The draft is dropped when the menu closes. Clearing applies at once. |
| `applyPrefix` | `string` | — | Label before the typed text in the apply row of a `draft` input. Defaults to "Apply:". |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `((Type extends "number" ? number : string) \| null)` | The typed value, or the value of a picked option. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | — | Content to the right of the field. |
| `option` | `PartialNot<SelectOptionProps<Option>>` | Content of an option in the menu. Replaces `optionComponent`. `option` is `undefined` on a loading skeleton row. |

### WInputDate

```ts
import WInputDate from 'eco-vue-js/dist/components/Input/WInputDate.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Date` | — | Selected date. Typed text is parsed into a date as it changes. |
| `minDate` | `Date` | — | Earliest selectable date. A typed date before it is replaced with it. |
| `maxDate` | `Date` | — | Latest selectable date. A typed date after it is replaced with it. |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowClear` | `boolean` | — | Adds a button that clears the value, emitting `clearValue`. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `async` | `boolean` | — | Keeps edits local and emits them only when saved — on Enter or blur — instead of on every keystroke. |
| `debounce` | `number` | — | With `async`, also saves after this many ms without typing, showing a progress bar under the text. |
| `hideDebounce` | `boolean` | — | Hides the `debounce` progress bar. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |
| `horizontalAlign` | `HorizontalAlign` | `HorizontalAlign.RIGHT_INNER` | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: Date \| undefined)` | The picked or typed date, clamped to `minDate` and `maxDate`. `undefined` when the text is cleared. Text that is not a date emits nothing. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | `{ unclickable?: boolean \| null \| undefined; }` | Content to the right of the field. On mobile, `unclickable` is `true` for the field on the page and `false` for its copy in the bottom sheet. |

### WInputToolbarButton

```ts
import WInputToolbarButton from 'eco-vue-js/dist/components/Input/WInputToolbarButton.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Text of the button, e.g. "H1". |
| `icon` | `SVGComponent` | — | Icon of the button. |
| `value` | `WrapSelection \| { title?: string \| undefined; icon?: SVGComponent \| undefined; value?: WrapSelection \| undefined; label?: string \| undefined; }[]` | — | Formatting applied to the selected text on click. A list turns the button into a group that opens its items on hover. |
| `tooltip` | `string` | — | Tooltip text. |
| `disabled` | `boolean` | — | Disables the button. |
| `label` | `string` | — | Name for screen readers. Defaults to `tooltip`, then `title`. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(index: number \| undefined)` | The button was clicked — with the item's index for a group, and `undefined` otherwise. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/select.md
description: >-
  WSelectSingle, WSelect and their async variants — searchable selects over a
  static list or a paginated query, with a custom option template.
---

# Select

Selects pick values out of a list of objects. The model holds only the values — ids, codes — and the select finds the objects behind them to display.

| Component | Model | Options come from |
| --- | --- | --- |
| `WSelectSingle` | one value or `null` | `options` array, or a `useQueryFnOptions` query returning an array |
| `WSelect` | array of values | same as above |
| `WSelectAsyncSingle` | one value or `null` | a paginated query, searched and paged on the server |
| `WSelectAsync` | array of values | same as above |

Every select needs:

* `valueGetter` — picks the model value out of an option.
* An `option` slot or an `optionComponent` to render an option. There is no default label; the slot receives `option`, `selected` and `model` (`true` when rendering the chosen value in the field rather than in the dropdown). Put a `w-option` class on the option's root, so it takes the height and rounding of a line in the field; add `w-option-has-bg` when the option has a background of its own, like a tag, so the background covers the field's left padding instead of sitting inside it. Such options are best made an `optionComponent`, which can hold the unselect button inside the background — see [Multiple](#multiple).
* `searchFn` for the static selects — the async ones send the search text to the query instead.

## Single

```vue
<template>
  <WSelectSingle
    v-model="soil"
    :options="soils"
    :value-getter="item => item.code"
    :search-fn="(item, search) => item.name.toLowerCase().includes(search.toLowerCase())"
    title="Soil"
    placeholder="Pick a soil"
    allow-clear
    :clear-value="null"
    class="max-w-md"
  >
    <template #option="{option}">
      <div class="w-option flex items-center">
        {{ option?.name }}
      </div>
    </template>
  </WSelectSingle>

  <p class="text-sm text-description">
    Model: {{ soil ?? 'null' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'

const soils = [
  {id: 1, code: 'loam', name: 'Loam'},
  {id: 2, code: 'sand', name: 'Sandy'},
  {id: 3, code: 'clay', name: 'Clay'},
  {id: 4, code: 'peat', name: 'Peat'},
]

const soil = ref<string | null>('loam')
</script>
```

With `allowClear` the value can be cleared. `clearValue` sets what clearing emits — `null`, `undefined` or `''` — and passing it explicitly also narrows the emitted type to match your model.

## Multiple

`WSelect` has no `v-model`: it emits `select` and `unselect` with the value, and leaves adding and removing to the parent. That way the parent can save each change, and show a spinner on the option until it's done with `loading`.

```vue
<template>
  <WSelect
    :model-value="tags"
    :options="options"
    :value-getter="item => item.id"
    :search-fn="(item, search) => item.name.toLowerCase().includes(search.toLowerCase())"
    title="Tags"
    placeholder="Add a tag"
    :option-component="OptionTag"
    class="max-w-md"
    @select="tags = [...tags, $event]"
    @unselect="tags = tags.filter(item => item !== $event)"
  />

  <p class="text-sm text-description">
    Model: {{ tags }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelect from 'eco-vue-js/dist/components/Select/WSelect.vue'

import OptionTag from './parts/OptionTag.vue'

const options = [
  {id: 1, name: 'indoor'},
  {id: 2, name: 'edible'},
  {id: 3, name: 'pet-safe'},
  {id: 4, name: 'fragrant'},
  {id: 5, name: 'evergreen'},
]

const tags = ref<number[]>([2, 3])
</script>
```

The tags are drawn by an `optionComponent` rather than the `option` slot. The select passes its unselect button to the component's default slot, so the component can put it inside the tag's background; with the slot, the button sits next to the tag. The same component renders the tags in the dropdown, without a button.

```vue [OptionTag.vue]
<template>
  <WSkeleton
    v-if="skeleton"
    class="w-option"
  />

  <div
    v-else
    class="tone-primary w-option w-option-has-bg bg-tone/10 text-tone grid max-w-max grid-cols-[1fr_auto] items-center gap-1 font-semibold"
  >
    <div class="truncate">
      {{ option?.name ?? search }}
    </div>

    <!-- The select puts its unselect button here, for a chosen tag in the field. -->
    <slot />
  </div>
</template>

<script lang="ts" setup>
import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

defineProps<SelectOptionProps<{id: number, name: string}>>()
</script>
```

## Async

`WSelectAsyncSingle` and `WSelectAsync` take `useQueryFnOptions` — a paginated query made with the kit's query helpers — and `queryParamsOptions`. The search text goes into the query params as `search` (`searchField` renames it), and more pages load as the dropdown scrolls.

To show the chosen value before the user opens the dropdown, the select requests it by id: the same query with `id__in` set to the model values (`valueQueryKey` renames it). The endpoint has to support that filter.

```vue
<template>
  <WSelectAsyncSingle
    v-model="plantId"
    :use-query-fn-options="plantModelApi.paginated.use"
    :query-params-options="{}"
    :value-getter="item => item.id"
    title="Plant"
    placeholder="Search by name or species"
    :option-component="OptionPlant"
    allow-clear
    :clear-value="null"
    class="max-w-md"
  />

  <p class="text-sm text-description">
    Model: {{ plantId ?? 'null' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectAsyncSingle from 'eco-vue-js/dist/components/Select/WSelectAsyncSingle.vue'

import OptionPlant from './parts/OptionPlant.vue'

// The `use` of any paginated query — here the plant model from the list recipe.
import {plantModelApi} from '../../../../../docs/examples/recipes/plant-list/api/Plant'

const plantId = ref<number | null>(3)
</script>
```

Until the selected plant loads by id, the select renders its option with `skeleton` — give the option a `WSkeleton` branch, or the field stays blank for that moment. Options on menu pages that are still loading get it too.

```vue [OptionPlant.vue]
<template>
  <!-- Shown while the selected plant loads by id, and for options on pages still loading. -->
  <WSkeleton
    v-if="skeleton"
    class="w-option w-skeleton-w-48"
  />

  <div
    v-else
    class="w-option grid grid-cols-[auto_1fr_auto] items-center gap-2"
  >
    <span
      class="bg-tone-fill size-2.5 rounded-full"
      :class="option ? kindToneMap[option.kind] : 'tone-data-gray'"
    />

    <span class="truncate">
      {{ option?.name ?? search }} <span
        v-if="option"
        class="text-description italic"
      >{{ option.species }}</span>
    </span>

    <slot />
  </div>
</template>

<script lang="ts" setup>
import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import {Kind, type Plant} from '../../../../../../docs/examples/recipes/plant-list/models/Plant'

defineProps<SelectOptionProps<Plant>>()

const kindToneMap: Record<Kind, string> = {
  [Kind.TROPICAL]: 'tone-data-green',
  [Kind.SUCCULENT]: 'tone-data-orange',
  [Kind.FERN]: 'tone-data-teal',
  [Kind.HERB]: 'tone-data-violet',
}
</script>
```

## Option layouts

An option is any markup, so it can carry as much as a card. The same component draws an option in three places, and its props tell them apart:

* **In the field** — `model` is `true`. Keep it to one line of `w-option` height, so the input does not grow. In a multiple select, the default slot holds the unselect button: place it inside the option's background.
* **In the menu** — `model` is falsy and there is room: add more rows, and a `py-1` to space them. `selected` is set for picked options.
* **While loading** — `skeleton` is `true` and `option` may be `undefined`. Draw a `WSkeleton` the size of what it stands for.
* **The "New:" row** of `createOption` — `option` is empty and `search` holds the typed text, which the option shows instead.

Extra props of an option component, like a display variant, are passed with `optionComponentProps`.

### Tags with their own color

Each option carries its tone, and the tag paints a soft background with it — `w-option-has-bg` stretches it to the field's edge. A typed light level is created with the tag icon and a gray tone.

```vue
<template>
  <WSelect
    :model-value="light"
    :options="options"
    :value-getter="item => item.id"
    :search-fn="(item, search) => item.name.toLowerCase().includes(search)"
    :create-option="createLight"
    title="Light it tolerates"
    placeholder="Add a light level"
    :option-component="OptionToneTag"
    class="max-w-md"
    @select="light = [...light, $event]"
    @unselect="light = light.filter(item => item !== $event)"
  />

  <p class="text-sm text-description">
    Model: {{ light }}
  </p>
</template>

<script lang="ts" setup>
import {markRaw, reactive, ref} from 'vue'

import WSelect from 'eco-vue-js/dist/components/Select/WSelect.vue'

import IconCloud from 'eco-vue-js/dist/assets/icons/IconCloud'
import IconCloudSun from 'eco-vue-js/dist/assets/icons/IconCloudSun'
import IconCloudSunPartial from 'eco-vue-js/dist/assets/icons/IconCloudSunPartial'
import IconMoon from 'eco-vue-js/dist/assets/icons/IconMoon'
import IconSun from 'eco-vue-js/dist/assets/icons/IconSun'

import OptionToneTag, {type ToneTag} from '../../../../../docs/examples/shared/OptionToneTag.vue'

const options = reactive<ToneTag[]>([
  {id: 'full-sun', name: 'Full sun', tone: 'tone-data-amber', icon: markRaw(IconSun)},
  {id: 'bright-indirect', name: 'Bright indirect', tone: 'tone-data-orange', icon: markRaw(IconCloudSun)},
  {id: 'part-shade', name: 'Part shade', tone: 'tone-data-teal', icon: markRaw(IconCloudSunPartial)},
  {id: 'shade', name: 'Shade', tone: 'tone-data-cyan', icon: markRaw(IconCloud)},
  {id: 'low-light', name: 'Low light', tone: 'tone-data-violet', icon: markRaw(IconMoon)},
])

const light = ref<string[]>(['bright-indirect', 'part-shade'])

// In an app, a POST that answers with the saved option. Without an icon, the option shows a tag.
const createLight = (search: string): ToneTag => {
  const option = {id: search.toLowerCase().replaceAll(' ', '-'), name: search, tone: 'tone-data-gray'}

  options.push(option)

  return option
}
</script>
```

```vue [OptionToneTag.vue]
<template>
  <WSkeleton
    v-if="skeleton"
    class="w-option"
  />

  <!-- Each option brings its own tone; a typed one, not created yet, has no option and falls back to the search text. -->
  <div
    v-else
    class="w-option w-option-has-bg bg-tone-soft text-tone grid max-w-max grid-cols-[auto_1fr_auto] items-center gap-1.5 font-semibold"
    :class="option?.tone ?? 'tone-data-gray'"
  >
    <component
      :is="option?.icon ?? IconTag"
      class="square-[1.25em] shrink-0"
    />

    <span class="truncate">{{ option?.name ?? search }}</span>

    <!-- The select puts its unselect button here, for a chosen tag in the field. -->
    <slot />
  </div>
</template>

<script lang="ts" setup generic="Id extends string">
import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import IconTag from 'eco-vue-js/dist/assets/icons/IconTag'

export type ToneTag<Id extends string = string> = {
  id: Id
  name: string
  tone: string
  /** Without one, the tag icon is shown. */
  icon?: SVGComponent
}

defineProps<SelectOptionProps<ToneTag<Id>>>()
</script>
```

### Avatar and details

One line in the field; in the menu, the option fills the row with a larger avatar, the role on a second line and the last week of watering pushed to the right, one bar a day. Each person carries their avatar tone, so they look the same everywhere — the home page and the [List with fields](/recipes/list-with-fields) recipe use the same people and option.

```vue
<template>
  <WSelectSingle
    v-model="gardenerId"
    :options="gardeners"
    :value-getter="item => item.id"
    :search-fn="(item, search) => item.name.toLowerCase().includes(search) || item.role.toLowerCase().includes(search)"
    title="On watering duty"
    placeholder="Pick a gardener"
    :option-component="OptionGardener"
    allow-clear
    :clear-value="null"
    class="max-w-md"
  />

  <p class="text-sm text-description">
    Model: {{ gardenerId ?? 'null' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'

import {gardeners} from '../../../../../docs/examples/shared/Gardener'
import OptionGardener from '../../../../../docs/examples/shared/OptionGardener.vue'

const gardenerId = ref<number | null>(1)
</script>
```

```vue [OptionGardener.vue]
<template>
  <WSkeleton
    v-if="skeleton || !option"
    class="w-option w-option-has-bg"
  />

  <!-- In the field it is one line, so the input keeps its height; the menu adds the role and the last week of watering. -->
  <div
    v-else
    class="w-option grid grid-cols-[auto_1fr_auto] items-center gap-2"
    :class="model ? 'w-option-has-bg' : undefined"
  >
    <span
      class="surface-fill flex shrink-0 items-center justify-center rounded-full font-semibold"
      :class="[option.tone, model ? 'size-5 text-[0.625rem] option-shift' : 'size-8 text-xs']"
    >
      {{ initials(option.name) }}
    </span>

    <span
      v-if="model"
      class="truncate"
    >{{ option.name }}</span>

    <template v-else>
      <span class="grid min-w-0">
        <span class="truncate">{{ option.name }}</span>
        <span class="text-description truncate text-xs">{{ option.role }}</span>
      </span>

      <!-- One bar a day, filled on the days they watered. -->
      <span
        class="flex items-end gap-0.5"
        :class="option.tone"
        :title="`Watered ${ option.week.filter(Boolean).length } of the last 7 days`"
      >
        <span
          v-for="(watered, day) in option.week"
          :key="day"
          class="w-1 rounded-full"
          :class="watered ? 'bg-tone-fill h-4' : 'bg-line h-1.5'"
        />
      </span>
    </template>

    <slot />
  </div>
</template>

<script lang="ts" setup>
import type {Gardener} from './Gardener'

import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import {initials} from './Gardener'

defineProps<SelectOptionProps<Gardener>>()
</script>

<style>
.option-shift {
  margin-left: max(-0.5rem, calc(var(--w-option-padding) / -2));
}
</style>
```

```ts [Gardener.ts]
/** A person who looks after the plants. Shared by the docs examples, so the same people show up everywhere. */
export type Gardener = {
  id: number
  name: string
  role: string
  /** Tone class of the avatar. */
  tone: string
  /** The last seven days, oldest first: whether they watered that day. */
  week: boolean[]
}

export const gardeners: Gardener[] = [
  {id: 1, name: 'Carl Linnaeus', role: 'Head gardener', tone: 'tone-data-green', week: [true, true, false, true, true, true, true]},
  {id: 2, name: 'Gregor Mendel', role: 'Gardener', tone: 'tone-data-violet', week: [true, false, true, true, false, true, true]},
  {id: 3, name: 'Barbara McClintock', role: 'Gardener', tone: 'tone-data-pink', week: [false, true, true, true, true, false, true]},
  {id: 4, name: 'Luther Burbank', role: 'Volunteer', tone: 'tone-data-amber', week: [false, false, true, false, false, true, false]},
  {id: 5, name: 'Beatrix Potter', role: 'Greenhouse', tone: 'tone-data-teal', week: [true, true, true, false, true, true, false]},
  {id: 6, name: 'George Washington Carver', role: 'Seedlings', tone: 'tone-data-cyan', week: [false, true, false, true, true, true, true]},
  {id: 7, name: 'Joseph Banks', role: 'Gardener', tone: 'tone-data-blue', week: [true, true, true, true, false, false, true]},
  {id: 8, name: 'Alexander von Humboldt', role: 'Volunteer', tone: 'tone-data-orange', week: [false, true, false, false, true, false, false]},
  {id: 9, name: 'Marianne North', role: 'Greenhouse', tone: 'tone-data-fuchsia', week: [true, false, true, true, true, false, true]},
  {id: 10, name: 'Jane Colden', role: 'Herbs', tone: 'tone-data-red', week: [true, true, false, true, false, true, true]},
  {id: 11, name: 'Asa Gray', role: 'Gardener', tone: 'tone-data-gray', week: [false, true, true, true, true, true, false]},
  {id: 12, name: 'John Bartram', role: 'Orchard', tone: 'tone-data-green', week: [true, false, false, true, true, false, true]},
  {id: 13, name: 'Ynes Mexia', role: 'Seedlings', tone: 'tone-data-violet', week: [true, true, true, true, true, true, false]},
  {id: 14, name: 'Joseph Dalton Hooker', role: 'Greenhouse', tone: 'tone-data-pink', week: [false, false, true, true, false, true, true]},
  {id: 15, name: 'Charles Darwin', role: 'Volunteer', tone: 'tone-data-amber', week: [false, true, false, false, false, true, false]},
  {id: 16, name: 'Maria Sibylla Merian', role: 'Herbs', tone: 'tone-data-teal', week: [true, true, false, true, true, false, true]},
  {id: 17, name: 'Gertrude Jekyll', role: 'Gardener', tone: 'tone-data-cyan', week: [true, true, true, false, true, true, true]},
  {id: 18, name: 'Vita Sackville-West', role: 'Gardener', tone: 'tone-data-blue', week: [false, true, true, true, false, true, true]},
  {id: 19, name: 'Kate Brandegee', role: 'Seedlings', tone: 'tone-data-orange', week: [true, false, true, false, true, true, false]},
  {id: 20, name: 'Eloise Butler', role: 'Volunteer', tone: 'tone-data-fuchsia', week: [false, false, false, true, false, true, true]},
  {id: 21, name: 'Liberty Hyde Bailey', role: 'Orchard', tone: 'tone-data-red', week: [true, true, false, false, true, true, true]},
  {id: 22, name: 'David Douglas', role: 'Gardener', tone: 'tone-data-gray', week: [true, false, true, true, true, true, false]},
  {id: 23, name: 'Ernest Wilson', role: 'Greenhouse', tone: 'tone-data-green', week: [false, true, true, false, true, false, true]},
  {id: 24, name: 'Frank Kingdon-Ward', role: 'Volunteer', tone: 'tone-data-violet', week: [true, false, false, false, true, false, false]},
  {id: 25, name: 'Janaki Ammal', role: 'Seedlings', tone: 'tone-data-pink', week: [true, true, true, true, false, true, true]},
  {id: 26, name: 'Agnes Arber', role: 'Herbs', tone: 'tone-data-amber', week: [false, true, true, false, true, true, false]},
  {id: 27, name: 'Nikolai Vavilov', role: 'Seedlings', tone: 'tone-data-teal', week: [true, false, true, true, false, true, true]},
  {id: 28, name: 'Masanobu Fukuoka', role: 'Orchard', tone: 'tone-data-cyan', week: [false, false, true, true, true, false, true]},
  {id: 29, name: 'Katherine Esau', role: 'Greenhouse', tone: 'tone-data-blue', week: [true, true, false, true, true, true, false]},
  {id: 30, name: 'John Muir', role: 'Volunteer', tone: 'tone-data-orange', week: [false, true, false, true, false, false, true]},
  {id: 31, name: 'Rachel Carson', role: 'Gardener', tone: 'tone-data-fuchsia', week: [true, true, true, false, false, true, true]},
  {id: 32, name: 'Norman Borlaug', role: 'Seedlings', tone: 'tone-data-red', week: [true, false, true, true, true, true, true]},
  {id: 33, name: 'Wangari Maathai', role: 'Orchard', tone: 'tone-data-gray', week: [true, true, false, true, false, true, false]},
  {id: 34, name: 'Piet Oudolf', role: 'Gardener', tone: 'tone-data-green', week: [false, true, true, true, true, false, true]},
  {id: 35, name: 'Lancelot Brown', role: 'Gardener', tone: 'tone-data-violet', week: [true, false, false, true, true, true, false]},
  {id: 36, name: 'Hildegard of Bingen', role: 'Herbs', tone: 'tone-data-pink', week: [false, true, true, false, true, true, true]},
]

/** First and last initials, which fit the round avatar. */
export const initials = (name: string) => {
  const parts = name.split(' ')

  return parts.length > 1 ? parts[0]![0]! + parts.at(-1)![0]! : name.slice(0, 2)
}
```

### Joined segments

Three segments, each a `w-option-has-bg` with its own background: the name, the humidity colored by range, and the kind on a gradient that holds the unselect button. The option's own `textOnly` prop, passed through `optionComponentProps`, drops the backgrounds and keeps the colored text — for a plain list or a table cell.

```vue
<template>
  <WSelectAsync
    :model-value="plantIds"
    :use-query-fn-options="plantModelApi.paginated.use"
    :query-params-options="{}"
    :value-getter="item => item.id"
    title="Shelf by the window"
    placeholder="Add a plant"
    :option-component="OptionPassport"
    :option-component-props="{textOnly}"
    class="max-w-xl"
    @select="plantIds = [...plantIds, $event]"
    @unselect="plantIds = plantIds.filter(item => item !== $event)"
    @update:model-value="plantIds = $event"
  />

  <WCheckbox
    v-model="textOnly"
    title="Text only"
  />

  <p class="text-sm text-description">
    Model: {{ plantIds }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'
import WSelectAsync from 'eco-vue-js/dist/components/Select/WSelectAsync.vue'

import OptionPassport from './parts/OptionPassport.vue'

import {plantModelApi} from '../../../../../docs/examples/recipes/plant-list/api/Plant'

const plantIds = ref<number[]>([1, 2, 3, 4])

const textOnly = ref(false)
</script>
```

```vue [OptionPassport.vue]
<template>
  <WSkeleton
    v-if="skeleton"
    class="w-option w-skeleton-w-48"
  />

  <!-- Three joined segments, each with its own background, so each is a `w-option-has-bg`. -->
  <div
    v-else
    class="w-option flex w-max max-w-full overflow-hidden"
  >
    <div
      class="w-option-has-bg text-accent flex min-w-0 items-center rounded-l-[inherit]"
      :class="{'bg-surface border-line-subtle border-y border-l': !textOnly}"
    >
      <span class="truncate">{{ option?.name ?? search }}</span>
    </div>

    <div
      v-if="option"
      class="w-option-has-bg text-tone flex items-center font-semibold tabular-nums"
      :class="[humidityTone, {'surface-soft border-y border-line-subtle': !textOnly}]"
      :title="`Prefers ${ option.humidity }% air humidity`"
    >
      <IconDrop class="square-[1em] mr-1" />
      {{ option.humidity }}%
    </div>

    <div
      class="w-option-has-bg grid grid-cols-[1fr_auto] items-center gap-1 rounded-r-[inherit] font-semibold capitalize"
      :class="textOnly ? ['text-tone', kindStyle.tone] : ['surface-fill bg-linear-to-r', kindStyle.tone, kindStyle.gradient]"
    >
      <span class="truncate">{{ option?.kind ?? 'new' }}</span>

      <!-- The unselect button lands in the last segment, on the gradient. -->
      <slot />
    </div>
  </div>
</template>

<script lang="ts" setup>
import {computed} from 'vue'

import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import IconDrop from 'eco-vue-js/dist/assets/icons/IconDrop'

import {Kind, type Plant} from '../../../../../../docs/examples/recipes/plant-list/models/Plant'

const props = defineProps<SelectOptionProps<Plant> & {
  /** Colors the text only, without backgrounds — for a plain list or a table cell. */
  textOnly?: boolean
}>()

/** `surface-fill` takes the tone for the text and the unselect button; the gradient paints over its flat fill. */
const kindStyleMap: Record<Kind, {tone: string, gradient: string}> = {
  [Kind.TROPICAL]: {tone: 'tone-data-green', gradient: 'from-data-green to-data-teal'},
  [Kind.SUCCULENT]: {tone: 'tone-data-orange', gradient: 'from-data-orange to-data-pink'},
  [Kind.FERN]: {tone: 'tone-data-teal', gradient: 'from-data-teal to-data-cyan'},
  [Kind.HERB]: {tone: 'tone-data-violet', gradient: 'from-data-violet to-data-fuchsia'},
}

const kindStyle = computed(() => props.option ? kindStyleMap[props.option.kind] : {tone: 'tone-data-gray', gradient: 'from-data-gray to-data-gray'})

const humidityTone = computed(() => {
  if (!props.option || props.option.humidity < 50) return 'tone-data-amber'
  if (props.option.humidity <= 65) return 'tone-data-green'
  return 'tone-data-cyan'
})
</script>
```

### Compact in the field, a card in the menu

The first line is the whole option in the field: the bed, the date and how many seedlings sprouted and were lost. The menu adds the crops and a bar of how the tray is doing. The skeleton follows the same split.

```vue
<template>
  <WSelectAsyncSingle
    v-model="batchId"
    :use-query-fn-options="batchModelApi.paginated.use"
    :query-params-options="{}"
    :value-getter="item => item.id"
    title="Seed tray"
    placeholder="Search by bed or crop"
    :option-component="OptionBatch"
    allow-clear
    :clear-value="null"
    class="max-w-md"
  />

  <p class="text-sm text-description">
    Model: {{ batchId ?? 'null' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectAsyncSingle from 'eco-vue-js/dist/components/Select/WSelectAsyncSingle.vue'

import {batchModelApi} from './api/garden'
import OptionBatch from './parts/OptionBatch.vue'

const batchId = ref<number | null>(3)
</script>
```

```vue [OptionBatch.vue]
<template>
  <!-- The placeholder takes the shape of what it stands for: one line in the field, a card in the menu. -->
  <WSkeleton
    v-if="skeleton && model"
    class="w-option w-skeleton-w-56"
  />

  <div
    v-else-if="skeleton"
    class="grid gap-1.5 py-1"
  >
    <WSkeleton class="w-skeleton-h-5" />
    <WSkeleton class="w-skeleton-h-5 w-skeleton-w-32" />
    <WSkeleton class="w-skeleton-h-1.5 w-skeleton-w-full" />
  </div>

  <div
    v-else-if="option"
    class="w-option grid content-center gap-1.5"
  >
    <!-- The first line is the whole option in the field. -->
    <div class="grid grid-cols-[1fr_auto_auto_auto] items-center gap-2">
      <span class="text-accent truncate">
        <span class="font-semibold">{{ option.bed }}</span> · sown {{ dateFormatter.format(option.sownAt) }}
      </span>

      <span class="tone-data-green text-tone text-xs font-semibold tabular-nums">+{{ option.sprouted }}</span>
      <span
        class="text-xs font-semibold tabular-nums"
        :class="option.lost ? 'tone-data-red text-tone' : 'text-subtle'"
      >−{{ option.lost }}</span>

      <slot />
    </div>

    <template v-if="!model">
      <div class="flex flex-wrap gap-1">
        <span
          v-for="crop in option.crops"
          :key="crop"
          class="bg-tone-soft text-tone rounded-full px-2 text-xs font-semibold"
          :class="cropToneMap[crop]"
        >
          {{ crop }}
        </span>
      </div>

      <!-- How the tray is doing: sprouted, still waiting, lost. -->
      <div class="flex h-1.5 overflow-hidden rounded-full bg-surface-muted">
        <div
          v-for="part in parts"
          :key="part.label"
          :class="part.class"
          :style="{width: `${ part.value / total * 100 }%`}"
        />
      </div>

      <div class="text-description flex gap-3 text-xs">
        <span
          v-for="part in parts"
          :key="part.label"
          class="flex items-center gap-1"
        >
          <span
            class="size-2 rounded-full"
            :class="part.class"
          />
          {{ part.value }} {{ part.label }}
        </span>
      </div>
    </template>
  </div>
</template>

<script lang="ts" setup>
import {computed} from 'vue'

import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import {type Batch, cropToneMap} from '../api/garden'

const props = defineProps<SelectOptionProps<Batch>>()

const dateFormatter = Intl.DateTimeFormat('en', {day: 'numeric', month: 'short'})

const parts = computed(() => props.option
  ? [
    {label: 'sprouted', value: props.option.sprouted, class: 'bg-data-green'},
    {label: 'waiting', value: props.option.waiting, class: 'bg-data-amber'},
    {label: 'lost', value: props.option.lost, class: 'bg-data-red'},
  ]
  : [])

const total = computed(() => parts.value.reduce((sum, part) => sum + part.value, 0) || 1)
</script>
```

### A dense card

A seed variety with its crop, flags drawn as icons and a sowing calendar — twelve cells colored for sowing, harvest, or both. The legend sits above the options in the `content` slot. In the field it collapses to a colored tag.

```vue
<template>
  <WSelectAsync
    :model-value="varietyIds"
    :use-query-fn-options="varietyModelApi.paginated.use"
    :query-params-options="{}"
    :value-getter="item => item.id"
    title="Seeds to order"
    placeholder="Search by variety or crop"
    :option-component="OptionVariety"
    class="max-w-xl"
    @select="varietyIds = [...varietyIds, $event]"
    @unselect="varietyIds = varietyIds.filter(item => item !== $event)"
    @update:model-value="varietyIds = $event"
  >
    <!-- A legend for the calendar strip, above the options. -->
    <template #content>
      <div class="text-description flex gap-3 px---w-select-option-padding pt-2 text-xs">
        <span class="flex items-center gap-1"><span class="bg-data-teal size-2 rounded-full" /> Sow</span>
        <span class="flex items-center gap-1"><span class="bg-data-amber size-2 rounded-full" /> Harvest</span>
      </div>
    </template>
  </WSelectAsync>

  <p class="text-sm text-description">
    Model: {{ varietyIds }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectAsync from 'eco-vue-js/dist/components/Select/WSelectAsync.vue'

import {varietyModelApi} from './api/garden'
import OptionVariety from './parts/OptionVariety.vue'

const varietyIds = ref<number[]>([1, 9])
</script>
```

```vue [OptionVariety.vue]
<template>
  <WSkeleton
    v-if="skeleton && model"
    class="w-option"
  />

  <div
    v-else-if="skeleton"
    class="grid gap-1.5 py-1"
  >
    <WSkeleton class="w-skeleton-h-5" />
    <WSkeleton class="w-skeleton-h-4 w-skeleton-w-48" />
    <WSkeleton class="w-skeleton-h-4 w-skeleton-w-full" />
  </div>

  <!-- In the field: the name with a crop tag, and the unselect button inside it. -->
  <div
    v-else-if="model"
    class="w-option w-option-has-bg bg-tone-soft text-tone grid max-w-max grid-cols-[auto_1fr_auto] items-center gap-1.5"
    :class="option ? cropToneMap[option.crop] : 'tone-data-gray'"
  >
    <span class="bg-tone-fill size-2 rounded-full" />
    <span class="truncate font-semibold">{{ option?.name ?? search }}</span>

    <slot />
  </div>

  <div
    v-else-if="option"
    class="grid max-w-full gap-1 py-1"
  >
    <div class="flex min-w-0 items-center gap-2">
      <span class="text-accent truncate font-semibold">{{ option.name }}</span>

      <span
        class="bg-tone-soft text-tone shrink-0 rounded-full px-2 text-xs font-semibold"
        :class="cropToneMap[option.crop]"
      >{{ option.crop }}</span>

      <span
        v-if="option.heirloom"
        class="tone-data-amber text-tone ml-auto flex shrink-0 items-center gap-1 text-xs font-semibold"
      >
        <IconStar class="square-[1.25em]" />
        Heirloom
      </span>
    </div>

    <div class="text-description text-xs">
      Germinates in {{ option.germination[0] }}–{{ option.germination[1] }} days · first harvest at {{ option.harvest }} days
    </div>

    <div class="flex gap-3 text-xs">
      <span
        class="flex items-center gap-1"
        :class="option.organic ? 'tone-data-green text-tone' : 'text-description'"
      >
        <IconPlant class="square-[1.25em]" />
        {{ option.organic ? 'Organic' : 'Conventional' }}
      </span>

      <span
        class="flex items-center gap-1"
        :class="option.frostHardy ? 'tone-data-cyan text-tone' : 'text-description'"
      >
        <IconSnowflake class="square-[1.25em]" />
        {{ option.frostHardy ? 'Frost-hardy' : 'Frost-tender' }}
      </span>
    </div>

    <!-- The year at a glance: when to sow, when to harvest, and months that are both. -->
    <div class="mt-0.5 flex gap-0.5">
      <span
        v-for="(month, monthIndex) in MONTHS"
        :key="monthIndex"
        class="flex h-4 items-center justify-center rounded-sm text-[0.5625rem] font-semibold px-2"
        :class="monthClass(monthIndex)"
      >
        {{ month }}
      </span>
    </div>
  </div>
</template>

<script lang="ts" setup>
import type {SelectOptionProps} from 'eco-vue-js/dist/components/Select/types'

import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import IconPlant from 'eco-vue-js/dist/assets/icons/IconPlant'
import IconSnowflake from 'eco-vue-js/dist/assets/icons/IconSnowflake'
import IconStar from 'eco-vue-js/dist/assets/icons/IconStar'

import {type Variety, cropToneMap} from '../api/garden'

const props = defineProps<SelectOptionProps<Variety>>()

const MONTHS = ['J', 'F', 'M', 'A', 'M', 'J', 'J', 'A', 'S', 'O', 'N', 'D']

const monthClass = (month: number) => {
  const sow = props.option?.sowMonths.includes(month)
  const harvest = props.option?.harvestMonths.includes(month)

  // `surface-fill` picks a readable text color for the tone; the split gradient paints over its fill.
  if (sow && harvest) return 'tone-data-teal surface-fill bg-linear-to-br from-data-teal from-50% to-data-amber to-50%'
  if (sow) return 'tone-data-teal surface-fill'
  if (harvest) return 'tone-data-amber surface-fill'
  return 'bg-surface-muted text-subtle'
}
</script>
```

The batches and varieties come from a mock API, built the same way as the plants:

```ts [api/garden.ts]
import {createRestModelApi} from 'eco-vue-js/dist/utils/restModelApi'
import {paginateList} from 'eco-vue-js/dist/utils/useDefaultQuery'

export enum Crop {
  TOMATO = 'Tomato',
  PEPPER = 'Pepper',
  SQUASH = 'Squash',
  BEAN = 'Bean',
  KALE = 'Kale',
  CUCUMBER = 'Cucumber',
  EGGPLANT = 'Eggplant',
  BEET = 'Beet',
  RADISH = 'Radish',
  CARROT = 'Carrot',
}

/** Each crop gets one of the theme's data colors, used as a tone: `text-tone`, `bg-tone-soft`, `surface-fill`. */
export const cropToneMap: Record<Crop, string> = {
  [Crop.TOMATO]: 'tone-data-red',
  [Crop.PEPPER]: 'tone-data-orange',
  [Crop.SQUASH]: 'tone-data-amber',
  [Crop.BEAN]: 'tone-data-green',
  [Crop.KALE]: 'tone-data-teal',
  [Crop.CUCUMBER]: 'tone-data-cyan',
  [Crop.EGGPLANT]: 'tone-data-violet',
  [Crop.BEET]: 'tone-data-fuchsia',
  [Crop.RADISH]: 'tone-data-pink',
  [Crop.CARROT]: 'tone-data-orange',
}

/** A tray of seeds sown into a bed on one day. */
export type Batch = {
  id: number
  bed: string
  sownAt: Date
  crops: Crop[]
  sprouted: number
  waiting: number
  lost: number
}

/** A seed variety from the catalogue. Months are 0-based. */
export type Variety = {
  id: number
  name: string
  crop: Crop
  heirloom: boolean
  organic: boolean
  frostHardy: boolean
  /** Days to germinate, from and to. */
  germination: [number, number]
  /** Days from sowing to the first harvest. */
  harvest: number
  sowMonths: number[]
  harvestMonths: number[]
}

type QueryParams = {
  page?: number
  search?: string
  /** Comma-separated ids — how async selects look up the items behind their model value. */
  id__in?: string
}

const batches: Batch[] = ([
  ['Bed 1', [2, 3], [Crop.TOMATO, Crop.PEPPER], 18, 4, 2],
  ['Bed 2', [2, 9], [Crop.KALE], 22, 0, 1],
  ['Bed 3', [2, 17], [Crop.BEET, Crop.RADISH, Crop.CARROT], 31, 12, 5],
  ['Bed 4', [2, 24], [Crop.BEAN], 9, 14, 0],
  ['Bed 5', [3, 1], [Crop.SQUASH, Crop.CUCUMBER], 6, 8, 4],
  ['Greenhouse A', [3, 6], [Crop.EGGPLANT, Crop.PEPPER], 12, 2, 0],
  ['Greenhouse B', [3, 14], [Crop.TOMATO], 24, 6, 3],
  ['Bed 6', [3, 21], [Crop.RADISH], 40, 0, 2],
  ['Bed 7', [4, 2], [Crop.BEAN, Crop.SQUASH], 3, 20, 1],
  ['Cold frame', [4, 11], [Crop.KALE, Crop.BEET], 0, 16, 0],
] as const).map(([bed, [month, day], crops, sprouted, waiting, lost], index) => ({
  id: index + 1,
  bed,
  sownAt: new Date(2026, month, day),
  crops: [...crops],
  sprouted,
  waiting,
  lost,
}))

const months = (from: number, to: number) => Array.from({length: to - from + 1}, (_, index) => from + index)

const varieties: Variety[] = ([
  ['Cherokee Purple', Crop.TOMATO, true, true, false, [6, 14], 80, months(2, 3), months(6, 8)],
  ['Sungold', Crop.TOMATO, false, false, false, [5, 10], 65, months(2, 3), months(6, 9)],
  ['Brandywine', Crop.TOMATO, true, true, false, [6, 14], 90, months(2, 3), months(7, 8)],
  ['California Wonder', Crop.PEPPER, true, false, false, [8, 21], 75, months(1, 2), months(7, 9)],
  ['Early Jalapeño', Crop.PEPPER, false, true, false, [8, 16], 65, months(1, 2), months(6, 9)],
  ['Waltham Butternut', Crop.SQUASH, true, true, false, [5, 10], 100, months(4, 5), months(8, 9)],
  ['Blue Lake', Crop.BEAN, true, false, false, [6, 10], 58, months(4, 6), months(6, 8)],
  ['Kentucky Wonder', Crop.BEAN, true, true, false, [6, 12], 65, months(4, 6), months(7, 9)],
  ['Lacinato', Crop.KALE, true, true, true, [5, 8], 60, [2, 3, 6, 7], [5, 6, 9, 10, 11]],
  ['Red Russian', Crop.KALE, true, false, true, [5, 8], 50, [2, 3, 7], [4, 5, 9, 10, 11]],
  ['Marketmore 76', Crop.CUCUMBER, false, true, false, [4, 10], 68, months(4, 5), months(6, 8)],
  ['Listada de Gandia', Crop.EGGPLANT, true, true, false, [7, 14], 85, months(1, 2), months(7, 8)],
  ['Detroit Dark Red', Crop.BEET, true, false, true, [5, 12], 60, months(2, 6), months(5, 9)],
  ['Chioggia', Crop.BEET, true, true, true, [5, 12], 55, months(2, 6), months(5, 9)],
  ['French Breakfast', Crop.RADISH, true, true, true, [3, 7], 25, [2, 3, 4, 7, 8], [3, 4, 5, 8, 9]],
  ['Cherry Belle', Crop.RADISH, false, false, true, [3, 7], 24, [2, 3, 4, 7, 8], [3, 4, 5, 8, 9]],
  ['Danvers', Crop.CARROT, true, true, true, [10, 21], 75, months(2, 5), months(6, 10)],
] as const).map(([name, crop, heirloom, organic, frostHardy, germination, harvest, sowMonths, harvestMonths], index) => ({
  id: index + 1,
  name,
  crop,
  heirloom,
  organic,
  frostHardy,
  germination: [...germination],
  harvest,
  sowMonths: [...sowMonths],
  harvestMonths: [...harvestMonths],
}))

/** Stands in for a request to the API: answers after a moment with a copy of the data. */
const respond = <Data>(handler: () => Data) => new Promise<Data>(resolve => {
  setTimeout(() => resolve(structuredClone(handler())), 600)
})

/** Searches the given fields and filters by `id__in`, as a backend would. */
const filterList = <Item extends {id: number}>(list: Item[], queryParams: QueryParams | undefined, fields: (item: Item) => string[]) => {
  const search = queryParams?.search?.trim().toLowerCase()
  const ids = queryParams?.id__in?.split(',').map(Number)

  return list
    .filter(item => !search || fields(item).some(field => field.toLowerCase().includes(search)))
    .filter(item => !ids || ids.includes(item.id))
}

const isQueryParams = (value: unknown): value is QueryParams | undefined => value === undefined || value instanceof Object

export const batchModelApi = createRestModelApi({
  modelKey: 'Batch',
  model: {} as Batch,
  queries: {
    paginated: {
      scope: 'paginated',
      dataType: {} as PaginatedResponse<Batch>,
      isQueryParams,
      // In an app, a GET to `/batches/` with the query params.
      queryFn: ({queryKey}) => respond(() => paginateList(filterList(batches, queryKey[2], item => [item.bed, ...item.crops]), queryKey[2]?.page, 6)),
    },
  },
})

export const varietyModelApi = createRestModelApi({
  modelKey: 'Variety',
  model: {} as Variety,
  queries: {
    paginated: {
      scope: 'paginated',
      dataType: {} as PaginatedResponse<Variety>,
      isQueryParams,
      // In an app, a GET to `/varieties/` with the query params.
      queryFn: ({queryKey}) => respond(() => paginateList(filterList(varieties, queryKey[2], item => [item.name, item.crop]), queryKey[2]?.page, 6)),
    },
  },
})
```

## In list cells

A select per row costs most of a list's first render: each one sets up its search, cursor, dropdown and input, and a query of its own when the options come from `useQueryFnOptions`. With `deferred`, a `seamless` select renders only its field and the selected options until it is pressed or focused — then it mounts the full select and opens it. Options from a query are not loaded before that, so give the selected ones in `previewData`, from data the row already has. The async selects load their chips on their own when `previewData` is not given, as they do when mounted.

```vue
<template>
  <div class="grid max-w-md grid-cols-[1fr_10rem] items-center gap-x-4">
    <template
      v-for="plant in plants"
      :key="plant.id"
    >
      <div>{{ plant.name }}</div>

      <WSelectSingle
        v-model="plant.soil"
        :options="soils"
        :value-getter="item => item.code"
        :search-fn="(item, search) => item.name.toLowerCase().includes(search.toLowerCase())"
        placeholder="Soil"
        seamless
        deferred
        no-margin
      >
        <template #option="{option, search}">
          <div class="w-option flex items-center">
            {{ option?.name ?? search }}
          </div>
        </template>
      </WSelectSingle>
    </template>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'

const soils = [
  {id: 1, code: 'loam', name: 'Loam'},
  {id: 2, code: 'sand', name: 'Sandy'},
  {id: 3, code: 'clay', name: 'Clay'},
  {id: 4, code: 'peat', name: 'Peat'},
]

const plants = ref([
  {id: 1, name: 'Monstera', soil: 'peat' as string | null},
  {id: 2, name: 'Aloe', soil: 'sand' as string | null},
  {id: 3, name: 'Fern', soil: null as string | null},
  {id: 4, name: 'Basil', soil: 'loam' as string | null},
])
</script>
```

## Other forms

* **`WSelectStringified`** is a `WSelect` whose model is one string — the values joined by `divider`, such as `"high,critical"` for a query param, or a JSON array with `divider="json"`.
* **`WSelectAsyncList`** shows the options of a paginated query as a list that is always open, in a scrolling box, with the picked ones checked — for picking from a long list inside a form or a modal. It emits `select` and `unselect` instead of a model; `selectOnly` and `unselectOnly` allow only one of them.

## API

### WSelectSingle

```ts
import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Model \| ClearValue \| null \| undefined` | **required** | Selected value. |
| `allowClear` | `AllowClear` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared. Defaults to `null`; set it explicitly to emit `undefined` or `''`. |
| `createdData` | `Data` | — | Option to add to the loaded ones — for a selected value the query does not return, such as one created elsewhere. |
| `previewData` | `Data` | — | Selected option, shown in the field until the options load — and, with `deferred`, before the select mounts. |
| `useQueryFnOptions` | `UseQueryDefault<Data[], unknown> \| UseQueryDefault<Data[], QueryParamsOptions>` | — | Query that loads the options. Takes `queryParamsOptions` when the query has parameters. Use either this or `options`. |
| `queryParamsOptions` | `QueryParamsOptions` | — | Parameters for `useQueryFnOptions`. |
| `options` | `Data[]` | — | Static list of options, instead of loading them with `useQueryFnOptions`. |
| `valueGetter` | `(value: Data) => Model` | **required** | Gets the value stored in the model from an option. |
| `searchFn` | `(option: Data, search: string) => boolean` | **required** | Tells whether an option matches the typed search, which is trimmed and lowercased. |
| `useQueryFnDefault` | `UseQueryDefault<Data, undefined>` | — | Query that loads a default option. When it resolves while nothing is selected, the option is selected and `init-model` is emitted. |
| `useFirstDefault` | `boolean` | — | Selects the first loaded option while nothing is selected, and emits `init-model`. |
| `emptyStub` | `string` | — | Shown in the menu instead of "Nothing to show" when there are no options and no search. |
| `hidePrefix` | `boolean` | — | Hides the selected chips while the menu is open, leaving room to type. |
| `createOption` | `((search: string) => Data \| Promise<Data \| undefined> \| undefined)` | — | Adds a "New:" option for the typed search. Return the created option to select it, or `undefined` to cancel. |
| `filterOptions` | `((option: Data) => boolean)` | — | Hides options for which it returns `false`. |
| `hideOptionIcon` | `boolean` | — | Hides the check mark next to selected options in the menu. |
| `searchModel` | `boolean` | — | Commits the typed text when the menu closes — selects the option matching it exactly, or creates one with `createOption`. In a single select, the selected value is also put into the search text on focus, so it can be edited. For string values. |
| `lazy` | `boolean` | — | Waits until the menu is first opened before loading the options. |
| `placeholderEmpty` | `string` | — | Placeholder while nothing is selected and the field is not focused. Defaults to `placeholder`. |
| `deferred` | `boolean` | — | Renders only the selected options until the field is first pressed or focused, then mounts the full select and opens it — for selects repeated in list cells. The options are not loaded before that, so pass `previewData` when they come from a query. With `seamless`, and not with `useQueryFnDefault` or `useFirstDefault`. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

::: details Inherited from `src/components/Input/types.ts` (35)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(EmitType, Data \| undefined)` | The new value, with its option — `clearValue` when cleared. |
| `update:query-options-error` | `(string \| undefined)` | Error detail from a failed `useQueryFnOptions`, or `undefined` once it loads. |
| `init-model` | — | A default value was selected by `useQueryFnDefault` or `useFirstDefault`. |
| `focus` | `(FocusEvent \| undefined)` | The field was focused. |
| `blur` | `(FocusEvent)` | The field lost focus. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | — | Content to the right of the field. |
| `prefix` | — | Replaces the selected chips. |
| `option` | `PartialNot<SelectOptionProps<Data>>` | Renders an option, in the menu and in the selected chips — `model` is `true` in a chip. Replaces `optionComponent`. |
| `content` | — | Content at the top of the menu, above the options. |

### WSelect

```ts
import WSelect from 'eco-vue-js/dist/components/Select/WSelect.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Model[] \| undefined` | **required** | Selected values. The component does not change it — update it from `select` and `unselect`. |
| `valueGetter` | `(value: Data) => Model` | **required** | Gets the value stored in the model from an option. |
| `searchFn` | `(option: Data, search: string) => boolean` | **required** | Tells whether an option matches the typed search, which is trimmed and lowercased. |
| `useQueryFnDefault` | `UseQueryDefault<Data, undefined>` | — | Query that loads a default option. When it resolves while nothing is selected, the option is selected and `init-model` is emitted. |
| `useFirstDefault` | `boolean` | — | Selects the first loaded option while nothing is selected, and emits `init-model`. |
| `emptyStub` | `string` | — | Shown in the menu instead of "Nothing to show" when there are no options and no search. |
| `disableClear` | `boolean` | — | Hides the remove button on the selected chips. |
| `hidePrefix` | `boolean` | — | Hides the selected chips while the menu is open, leaving room to type. |
| `createOption` | `((search: string) => Data \| Promise<Data \| undefined> \| undefined)` | — | Adds a "New:" option for the typed search. Return the created option to select it, or `undefined` to cancel. |
| `filterOptions` | `((option: Data) => boolean)` | — | Hides options for which it returns `false`. |
| `hideOptionIcon` | `boolean` | — | Hides the check mark next to selected options in the menu. |
| `createdData` | `Data[]` | — | Options to add to the loaded ones — for selected values the query does not return, such as ones created elsewhere. |
| `searchModel` | `boolean` | — | Commits the typed text when the menu closes — selects the option matching it exactly, or creates one with `createOption`. In a single select, the selected value is also put into the search text on focus, so it can be edited. For string values. |
| `lazy` | `boolean` | — | Waits until the menu is first opened before loading the options. |
| `placeholderEmpty` | `string` | — | Placeholder while nothing is selected and the field is not focused. Defaults to `placeholder`. |
| `cursorSelected` | `boolean` | — | Puts the cursor on the first selected option when the menu opens, so Enter toggles it — by default the menu only scrolls to it. Always set in the single selects. |
| `previewData` | `Data[]` | — | Selected options, shown in the chips until the options load — and, with `deferred`, before the select mounts. |
| `deferred` | `boolean` | — | Renders only the selected options until the field is first pressed or focused, then mounts the full select and opens it — for selects repeated in list cells. The options are not loaded before that, so pass `previewData` when they come from a query. With `seamless`, and not with `useQueryFnDefault` or `useFirstDefault`. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |
| `useQueryFnOptions` | `UseQueryDefault<Data[], unknown> \| UseQueryDefault<Data[], QueryParamsOptions>` | — | Query that loads the options. Takes `queryParamsOptions` when the query has parameters. Use either this or `options`. |
| `queryParamsOptions` | `QueryParamsOptions` | — | Parameters for `useQueryFnOptions`. |
| `options` | `Data[]` | — | Static list of options, instead of loading them with `useQueryFnOptions`. |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

::: details Inherited from `src/components/Input/types.ts` (35)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `select` | `(Model, Data)` | An option was picked. Add it to `modelValue`. |
| `unselect` | `(Model, Data \| undefined)` | An option was removed, from its chip or the menu. Remove it from `modelValue`. |
| `focus` | `(FocusEvent \| undefined)` | The field was focused. |
| `blur` | `(FocusEvent)` | The field lost focus. |
| `update:query-options-error` | `(string \| undefined)` | Error detail from a failed `useQueryFnOptions`, or `undefined` once it loads. |
| `init-model` | — | A default value was selected by `useQueryFnDefault` or `useFirstDefault`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `option` | `PartialNot<SelectOptionProps<Data>>` | Renders an option, in the menu and in the selected chips — `model` is `true` in a chip. Replaces `optionComponent`. |
| `right` | — | Content to the right of the field. |
| `prefix` | — | Replaces the selected chips. |
| `content` | — | Content at the top of the menu, above the options. |

### WSelectAsyncSingle

```ts
import WSelectAsyncSingle from 'eco-vue-js/dist/components/Select/WSelectAsyncSingle.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Model \| ClearValue \| null` | **required** | Selected value. |
| `allowClear` | `AllowClear` | — | Adds a button that clears the value, emitting `clearValue`. |
| `clearValue` | `ClearValue` | — | Value emitted when cleared. Defaults to `null`; set it explicitly to emit `undefined` or `''`. |
| `previewData` | `Data` | — | Selected option, shown in the field instead of loading it. |
| `createdData` | `Data` | — | Option to add to the loaded ones — for a selected value the query does not return, such as one created elsewhere. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |
| `useQueryFnOptions` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | **required** | Paginated query that loads the options, page by page as the menu scrolls. The search text is sent in `searchField`. |
| `queryParamsOptions` | `QueryParams` | **required** | Parameters for `useQueryFnOptions`. |
| `valueGetter` | `((value: Data) => Model)` | `(data as unknown as {     id: Model; }).id` | Gets the value stored in the model from an option. Defaults to the option's `id`. |
| `useQueryFnDefault` | `UseQueryDefault<Data, undefined>` | — | Query that loads a default option. When it resolves while nothing is selected, the option is selected and `init-model` is emitted. |
| `emptyStub` | `string` | — | Shown in the menu instead of "Nothing to show" when there are no options and no search. |
| `hidePrefix` | `boolean` | — | Hides the selected chips while the menu is open, leaving room to type. |
| `createOption` | `((search: string) => Data \| Promise<Data \| undefined> \| undefined)` | — | Adds a "New:" option for the typed search. Return the created option to select it, or `undefined` to cancel. |
| `hideOptionIcon` | `boolean` | — | Hides the check mark next to selected options in the menu. |
| `searchModel` | `boolean` | — | Commits the typed text when the menu closes — selects the option matching it exactly, or creates one with `createOption`. In a single select, the selected value is also put into the search text on focus, so it can be edited. For string values. |
| `lazy` | `boolean` | — | Waits until the menu is first opened before loading the options. |
| `placeholderEmpty` | `string` | — | Placeholder while nothing is selected and the field is not focused. Defaults to `placeholder`. |
| `deferred` | `boolean` | — | Renders only the selected options until the field is first pressed or focused, then mounts the full select and opens it — for selects repeated in list cells. The options are not loaded before that, so pass `previewData` when they come from a query. With `seamless`, and not with `useQueryFnDefault` or `useFirstDefault`. |
| `useQueryFnPrefix` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | — | Paginated query that loads the selected options for the chips. Defaults to `useQueryFnOptions`. |
| `searchField` | `keyof QueryParams` | — | Query parameter that receives the search text. Defaults to `search`. |
| `valueQueryKey` | `string` | `"id__in"` | Query parameter that receives the selected values, comma-separated, when loading the chips. |
| `prefixText` | `string` | — | Word after the count shown instead of chips when more than `prefixMax` values are selected. Defaults to "items". |
| `prefixMax` | `number` | `8` | Most selected values shown as chips; above it, a count with a clear-all button is shown instead. |
| `reverse` | `boolean` | — | Shows the check mark on options that are not selected instead of those that are — for a select that picks what to exclude. |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

::: details Inherited from `src/components/Input/types.ts` (35)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(EmitType, Data \| undefined)` | The new value, with its option — `clearValue` when cleared. |
| `init-model` | — | A default value was selected by `useQueryFnDefault`. |
| `focus` | `(FocusEvent \| undefined)` | The field was focused. |
| `blur` | `(FocusEvent)` | The field lost focus. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | `Record<string, never>` | Content to the right of the field. |
| `option` | `PartialNot<SelectOptionProps<Data>>` | Renders an option, in the menu and in the selected chips — `model` is `true` in a chip. Replaces `optionComponent`. |
| `content` | — | Content at the top of the menu, above the options. |
| `prefix` | — | Replaces the selected chips. |

### WSelectAsync

```ts
import WSelectAsync from 'eco-vue-js/dist/components/Select/WSelectAsync.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `useQueryFnOptions` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | **required** | Paginated query that loads the options, page by page as the menu scrolls. The search text is sent in `searchField`. |
| `useQueryFnPrefix` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | — | Paginated query that loads the selected options for the chips. Defaults to `useQueryFnOptions`. |
| `queryParamsOptions` | `QueryParams` | **required** | Parameters for `useQueryFnOptions`. |
| `searchField` | `keyof QueryParams` | — | Query parameter that receives the search text. Defaults to `search`. |
| `valueGetter` | `((value: Data) => Model)` | `(data as unknown as {     id: Model; }).id` | Gets the value stored in the model from an option. Defaults to the option's `id`. |
| `previewData` | `Data[]` | — | Selected options, used for the chips instead of loading them — also before the select mounts with `deferred`. |
| `valueQueryKey` | `string` | `"id__in"` | Query parameter that receives the selected values, comma-separated, when loading the chips. |
| `prefixText` | `string` | — | Word after the count shown instead of chips when more than `prefixMax` values are selected. Defaults to "items". |
| `prefixMax` | `number` | `8` | Most selected values shown as chips; above it, a count with a clear-all button is shown instead. |
| `reverse` | `boolean` | — | Shows the check mark on options that are not selected instead of those that are — for a select that picks what to exclude. |
| `modelValue` | `Model[] \| undefined` | **required** | Selected values. The component does not change it — update it from `select` and `unselect`. |
| `useQueryFnDefault` | `UseQueryDefault<Data, undefined>` | — | Query that loads a default option. When it resolves while nothing is selected, the option is selected and `init-model` is emitted. |
| `emptyStub` | `string` | `"No match"` | Shown in the menu instead of "Nothing to show" when there are no options and no search. |
| `disableClear` | `boolean` | — | Hides the remove button on the selected chips. |
| `hidePrefix` | `boolean` | — | Hides the selected chips while the menu is open, leaving room to type. |
| `createOption` | `((search: string) => Data \| Promise<Data \| undefined> \| undefined)` | — | Adds a "New:" option for the typed search. Return the created option to select it, or `undefined` to cancel. |
| `hideOptionIcon` | `boolean` | — | Hides the check mark next to selected options in the menu. |
| `createdData` | `Data[]` | — | Options to add to the loaded ones — for selected values the query does not return, such as ones created elsewhere. |
| `searchModel` | `boolean` | — | Commits the typed text when the menu closes — selects the option matching it exactly, or creates one with `createOption`. In a single select, the selected value is also put into the search text on focus, so it can be edited. For string values. |
| `lazy` | `boolean` | — | Waits until the menu is first opened before loading the options. |
| `placeholderEmpty` | `string` | — | Placeholder while nothing is selected and the field is not focused. Defaults to `placeholder`. |
| `cursorSelected` | `boolean` | — | Puts the cursor on the first selected option when the menu opens, so Enter toggles it — by default the menu only scrolls to it. Always set in the single selects. |
| `deferred` | `boolean` | — | Renders only the selected options until the field is first pressed or focused, then mounts the full select and opens it — for selects repeated in list cells. The options are not loaded before that, so pass `previewData` when they come from a query. With `seamless`, and not with `useQueryFnDefault` or `useFirstDefault`. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

::: details Inherited from `src/components/Input/types.ts` (35)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `select` | `(Model, Data)` | An option was picked. Add it to `modelValue`. |
| `unselect` | `(Model, Data \| undefined)` | An option was removed, from its chip or the menu. Remove it from `modelValue`. |
| `update:model-value` | `(Model[])` | Emits `[]` from the clear-all button shown with the count, when more than `prefixMax` values are selected. |
| `init-model` | — | A default value was selected by `useQueryFnDefault`. |
| `focus` | `(FocusEvent \| undefined)` | The field was focused. |
| `blur` | `(FocusEvent)` | The field lost focus. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | `Record<string, never>` | Content to the right of the field. |
| `option` | `PartialNot<SelectOptionProps<Data>>` | Renders an option, in the menu and in the selected chips — `model` is `true` in a chip. Replaces `optionComponent`. |
| `content` | — | Content at the top of the menu, above the options. |
| `prefix` | `{ modelValue: Model[]; }` | Replaces the selected chips. |

### WSelectStringified

```ts
import WSelectStringified from 'eco-vue-js/dist/components/Select/WSelectStringified.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Model \| null \| undefined` | **required** | Picked values in one string, joined by `divider`. |
| `divider` | `string` | **required** | Separator between the values, e.g. `,`, or `json` for a JSON array of strings. |
| `useQueryFnOptions` | `UseQueryDefault<Data[], unknown> \| UseQueryDefault<Data[], QueryParamsOptions>` | — | Query that loads the options. Takes `queryParamsOptions` when the query has parameters. Use either this or `options`. |
| `queryParamsOptions` | `QueryParamsOptions` | — | Parameters for `useQueryFnOptions`. |
| `options` | `Data[]` | — | Static list of options, instead of loading them with `useQueryFnOptions`. |
| `valueGetter` | `(value: Data) => Model` | **required** | Gets the value stored in the model from an option. |
| `searchFn` | `(option: Data, search: string) => boolean` | **required** | Tells whether an option matches the typed search, which is trimmed and lowercased. |
| `useQueryFnDefault` | `UseQueryDefault<Data, undefined>` | — | Query that loads a default option. When it resolves while nothing is selected, the option is selected and `init-model` is emitted. |
| `useFirstDefault` | `boolean` | — | Selects the first loaded option while nothing is selected, and emits `init-model`. |
| `emptyStub` | `string` | — | Shown in the menu instead of "Nothing to show" when there are no options and no search. |
| `disableClear` | `boolean` | — | Hides the remove button on the selected chips. |
| `hidePrefix` | `boolean` | — | Hides the selected chips while the menu is open, leaving room to type. |
| `createOption` | `((search: string) => Data \| Promise<Data \| undefined> \| undefined)` | — | Adds a "New:" option for the typed search. Return the created option to select it, or `undefined` to cancel. |
| `filterOptions` | `((option: Data) => boolean)` | — | Hides options for which it returns `false`. |
| `hideOptionIcon` | `boolean` | — | Hides the check mark next to selected options in the menu. |
| `createdData` | `Data[]` | — | Options to add to the loaded ones — for selected values the query does not return, such as ones created elsewhere. |
| `searchModel` | `boolean` | — | Commits the typed text when the menu closes — selects the option matching it exactly, or creates one with `createOption`. In a single select, the selected value is also put into the search text on focus, so it can be edited. For string values. |
| `lazy` | `boolean` | — | Waits until the menu is first opened before loading the options. |
| `placeholderEmpty` | `string` | — | Placeholder while nothing is selected and the field is not focused. Defaults to `placeholder`. |
| `cursorSelected` | `boolean` | — | Puts the cursor on the first selected option when the menu opens, so Enter toggles it — by default the menu only scrolls to it. Always set in the single selects. |
| `previewData` | `Data[]` | — | Selected options, shown in the chips until the options load — and, with `deferred`, before the select mounts. |
| `deferred` | `boolean` | — | Renders only the selected options until the field is first pressed or focused, then mounts the full select and opens it — for selects repeated in list cells. The options are not loaded before that, so pass `previewData` when they come from a query. With `seamless`, and not with `useQueryFnDefault` or `useFirstDefault`. |
| `optionComponent` | `OptionComponent` | — | Component that renders an option, in the menu and in the selected chips. Receives `option`, `selected`, `model` and `search`. The `option` slot replaces it. |
| `optionComponentProps` | `(OptionComponent extends Component<infer Props> ? Partial<Omit<Props, keyof SelectOptionProps<Option>>> : never)` | — | Extra props passed to every `optionComponent`. |
| `horizontalAlign` | `HorizontalAlign` | — | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (21)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

::: details Inherited from `src/components/Input/types.ts` (35)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maxLength` | `number` | — | Cuts off input longer than this, and shows a `length / maxLength` counter under the field while it is focused. |
| `readonly` | `boolean` | — | Shows the value as text without an input. When unset, inherits the readonly state provided by a parent. |
| `type` | `"text"` | — | Native input type. `number` parses the value into a number. |
| `textarea` | `boolean` | — | Multi-line editor instead of a single-line input, with undo and redo. |
| `resize` | `boolean` | — | Lets the user drag the textarea's height. |
| `placeholder` | `string` | — | Hint shown while the field is empty. |
| `icon` | `SVGComponent` | — | Icon at the start of the field, highlighted while focused. |
| `size` | `number` | — | Native `size` attribute, which sets the input's minimum width in characters. |
| `maxSizeKb` | `number` | — | Largest file, in KB, that `allowDropFile` accepts by drop or picker. Defaults to 100. |
| `step` | `number` | — | Native `step` attribute for `type="number"`. |
| `min` | `number` | — | Native `min` attribute for `type="number"`. |
| `max` | `number` | — | Native `max` attribute for `type="number"`. |
| `name` | `string` | — | Native `name` attribute. |
| `autocomplete` | `string` | — | Native `autocomplete` attribute. |
| `autofocus` | `number \| boolean` | — | Focuses the field after mount, and again when the browser tab becomes active. A number sets the delay in ms (`0` focuses at once). Skipped while another input has focus. |
| `disabledActions` | `boolean` | — | Disables the action buttons (clear, paste, copy) while keeping the input editable. |
| `loading` | `boolean` | — | Shows a spinner in the actions and blocks input. |
| `spellcheck` | `boolean` | — | Enables the browser's spell check. |
| `customBackspaceHandle` | `boolean` | — | Handles Backspace in code — removes the character or selection and emits the new value — instead of leaving it to the browser. |
| `textSecure` | `boolean` | — | Masks the value, with a button to reveal it, for secrets. A model value of `true` means a secret is set but not sent to the client, and shows a check mark instead. |
| `placeholderSecure` | `boolean` | — | Shows the secret-set check mark while the field is empty. |
| `allowPaste` | `boolean` | — | Adds a button that pastes from the clipboard, replacing the value. |
| `hideInput` | `boolean` | — | Hides the text input, leaving only the `prefix` content. |
| `noWrap` | `boolean` | — | Keeps the `prefix` content on one line, scrolling sideways instead of wrapping. |
| `textTransparent` | `boolean` | — | Makes the typed text transparent while keeping the caret, for an overlay that draws the text itself. |
| `textParts` | `TextPart[]` | — | Textarea content as a list of strings and tagged parts, for highlighting parts of the text. |
| `rich` | `boolean` | — | Adds a formatting toolbar to the textarea. |
| `toolbarActions` | `ToolbarAction[]` | — | Custom buttons for the textarea toolbar. |
| `borderClass` | `string` | — | Border color classes, replacing the default gray. |
| `explicit` | `boolean` | — | With `async`, shows Save and Cancel buttons while there are unsaved edits. Always on for `textarea` and `textSecure`. |
| `mobileTitle` | `string` | — | Title for the mobile bottom sheet the menu opens in. Defaults to `title`. |
| `persist` | `boolean` | — | Keeps the menu open when the input loses focus. |
| `closeOnClear` | `boolean` | — | Closes the menu when the value is cleared. |
| `static` | `boolean` | — | Renders the menu content under the input instead of in a dropdown. |
| `hideToggle` | `boolean` | — | Hides the button that opens and closes the menu. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(Model)` | The picked values, joined into one string. |
| `update:query-options-error` | `(string \| undefined)` | Error message of the options query, or `undefined` once it loads. |
| `init-model` | — | The options loaded. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | — | Content to the right of the field. |
| `option` | `PartialNot<SelectOptionProps<Data>>` | Content of an option, in the menu and in the chips. |
| `content` | — | Content at the top of the menu. |

### WSelectAsyncList

```ts
import WSelectAsyncList from 'eco-vue-js/dist/components/Select/WSelectAsyncList.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the list. |
| `emptyStub` | `string` | — | Text shown when the query returns no options. |
| `modelValue` | `Model[]` | **required** | Picked values. |
| `useQueryFn` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | **required** | Paginated query of the options, loaded page by page as the list scrolls. |
| `queryParams` | `QueryParams` | **required** | Params of the query, such as a search. |
| `skeleton` | `boolean` | — | Shows placeholders instead of the list. When unset, inherits the skeleton state provided by a parent. |
| `excludeParams` | `(keyof QueryParams)[]` | — | Params whose change refetches the loaded pages instead of starting from the first one. |
| `selectOnly` | `boolean` | — | Only allows picking options, not unpicking them. |
| `unselectOnly` | `boolean` | — | Only allows unpicking options, not picking them. |
| `hideOptionIcon` | `boolean` | — | Hides the check icon of the options. |
| `valueGetter` | `((data: Data) => Model)` | `(data as unknown as {     id: Model; }).id` | Value of an option. Defaults to its `id`. |
| `queryOptions` | `Partial<DefaultQueryOptions<PaginatedResponse<Data>> \| undefined>` | — | Options for every page query. |
| `disabled` | `boolean` | — | Stops picking. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Stops picking. When unset, inherits the readonly state provided by a parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `select` | `(Model)` | An option was picked. |
| `unselect` | `(Model)` | An option was unpicked. |
| `update:count` | `(number)` | Total number of options, from the query's `count`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `PartialNot<SelectOptionProps<Data>>` | Content of an option, with `skeleton` while its page loads. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/toggle.md
description: >-
  WToggle — an on/off switch bound with v-model, with title, description, small
  and right-label layouts — and WToggleTheme for the light or dark theme.
---

# Toggle

`WToggle` is a switch for a `boolean` model. The title sits on the left and the switch on the right, so a column of toggles lines up; `rightLabel` puts the title after the switch instead.

```vue
<template>
  <div class="grid max-w-md gap-2">
    <WToggle
      v-model="notify"
      title="Email notifications"
      description="A digest once a day."
    />

    <WToggle
      v-model="compact"
      title="Compact rows"
      right-label
      small
    />

    <WToggle
      :model-value="true"
      title="Disabled"
      disabled
    />
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

const notify = ref(true)
const compact = ref(false)
</script>
```

`validate` checks the new value before it is emitted: when it returns an error, the change is dropped and the error is shown as a warning notification. `negate` flips the switch so it shows `true` as off, for settings phrased the other way round.

## Theme toggle

`WToggleTheme` is a toggle for the app's light or dark theme: on with a sun for `Theme.LIGHT`, off with a moon for `Theme.DARK`. It only switches the `Theme` value — applying it, usually as a `dark` class on `<html>`, and remembering it is up to the app. See [App shell](/guide/app-shell#layout-component) and [Theming](/guide/theming).

```vue
<template>
  <div class="grid max-w-md gap-2">
    <WToggleTheme
      v-model="theme"
      title="Theme"
    />

    <span class="text-description text-sm">
      Picked: {{ theme }} — this demo only keeps the value; the header's toggle applies it to the site.
    </span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {Theme} from 'eco-vue-js/dist/utils/utils'

import WToggleTheme from 'eco-vue-js/dist/components/Toggle/WToggleTheme.vue'

const theme = ref(Theme.LIGHT)
</script>
```

## API

### WToggle

```ts
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Value` | **required** | Switch state. `null` puts the caret in the middle, the mixed state used with `intermediate`. |
| `title` | `string` | — | Label next to the switch; the `title` slot replaces it. |
| `icon` | `SVGComponent` | — | Icon drawn inside the caret. Hidden while `loading`. |
| `small` | `boolean` | — | Smaller title text. |
| `disabled` | `boolean` | — | Blocks changes and dims the toggle. When unset, inherits the disabled state provided by a parent. |
| `loading` | `boolean` | — | Shows a spinner in the caret and ignores clicks. |
| `readonly` | `boolean` | — | Shows the state without allowing changes, and keeps the title selectable. When unset, inherits the readonly state provided by a parent. |
| `rightLabel` | `boolean` | — | Puts the title after the switch instead of before it. |
| `noMargin` | `boolean` | — | Drops the default vertical margin around the toggle. |
| `description` | `string` | — | Secondary text under the toggle. |
| `intermediate` | `boolean` | `false` | Cycles through three states on click — `true`, `false`, then `null` — instead of two. |
| `negate` | `boolean` | — | Inverts the display: a `true` model shows the switch as off, and turning it on emits `false`. |
| `validate` | `ValidateFn \| ValidateFn[]` | — | Checks the new value before it is emitted. A returned error message cancels the change and is shown as a warning notification. |
| `center` | `boolean` | — | Centers the switch in its row. |
| `skeleton` | `boolean` | — | Renders a skeleton placeholder. When unset, inherits the skeleton state provided by a parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(Value)` | The new state, after `negate` is applied and `validate` passes. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |

### WToggleTheme

```ts
import WToggleTheme from 'eco-vue-js/dist/components/Toggle/WToggleTheme.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Theme` | **required** | Current theme: the toggle is on, with a sun, for `Theme.LIGHT`, and off, with a moon, for `Theme.DARK`. |
| `title` | `string` | — | Label next to the switch; the `title` slot replaces it. |
| `small` | `boolean` | — | Smaller title text. |
| `disabled` | `boolean` | — | Blocks changes and dims the toggle. When unset, inherits the disabled state provided by a parent. |
| `loading` | `boolean` | — | Shows a spinner in the caret and ignores clicks. |
| `readonly` | `boolean` | — | Shows the state without allowing changes, and keeps the title selectable. When unset, inherits the readonly state provided by a parent. |
| `rightLabel` | `boolean` | — | Puts the title after the switch instead of before it. |
| `noMargin` | `boolean` | — | Drops the default vertical margin around the toggle. |
| `description` | `string` | — | Secondary text under the toggle. |
| `validate` | `ValidateFn \| ValidateFn[]` | — | Checks the new value before it is emitted. A returned error message cancels the change and is shown as a warning notification. |
| `center` | `boolean` | — | Centers the switch in its row. |
| `skeleton` | `boolean` | — | Renders a skeleton placeholder. When unset, inherits the skeleton state provided by a parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: Theme)` | The picked theme. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/checkbox.md
description: >-
  WCheckbox, WCheckboxGroup and WCheckboxGroupMultiple — a single checkbox, one
  value out of a list with radio buttons, and several values out of a list of
  plain values or objects.
---

# Checkbox

`WCheckbox` is a checkbox for a `boolean` model. The title comes from the `title` prop or the default slot, and `radio` draws a round radio button instead. With `intermediate`, a `null` model shows the partly-selected mark — for a "select all" over a partial selection.

```vue
<template>
  <div class="grid max-w-md gap-2">
    <WCheckbox
      v-model="agree"
      title="I agree to the terms"
    />

    <WCheckbox
      :model-value="null"
      title="Partly selected"
      intermediate
    />

    <WCheckbox
      v-model="compact"
      title="Radio look"
      radio
    />

    <WCheckbox
      :model-value="true"
      title="Disabled"
      tooltip-text="Managed by your organization"
      disabled
    />
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'

const agree = ref(false)
const compact = ref(true)
</script>
```

## Groups

For a choice out of a list there are two group components. Both take the options as `list` and render inside a field wrapper, so they have the field's `title`, `description` and error layout:

* `WCheckboxGroup` picks one value — `v-model` holds it. `allowClear` lets a click on the selected option clear it back to `null`.
* `WCheckboxGroupMultiple` picks several. Its model is an array, but it doesn't emit a new array: it emits `select` and `unselect` with the one value that changed, so the parent can save each change on its own.

`list` holds plain values, labelled with `titleMap` (and optionally `iconMap`, `tooltipTextMap`, `classMap`), or objects, with `valueGetter` to read the value out of each and the `option` slot or `optionComponent` to render it. `wrap` lays the options out in a row that wraps, `stretch` spreads them over the width.

```vue
<template>
  <div class="grid max-w-md gap-6">
    <WCheckboxGroup
      v-model="plan"
      :list="PLANS"
      :title-map="PLAN_TITLES"
      title="Plan"
      radio
      wrap
    />

    <WCheckboxGroupMultiple
      :model-value="channels"
      :list="CHANNELS"
      :value-getter="item => item.id"
      title="Notify me by"
      @select="channels = [...channels, $event]"
      @unselect="channels = channels.filter(id => id !== $event)"
    >
      <template #option="{option}">
        {{ option?.title }}
      </template>
    </WCheckboxGroupMultiple>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WCheckboxGroup from 'eco-vue-js/dist/components/Checkbox/WCheckboxGroup.vue'
import WCheckboxGroupMultiple from 'eco-vue-js/dist/components/Checkbox/WCheckboxGroupMultiple.vue'

const PLANS = ['free', 'pro', 'team'] as const

const PLAN_TITLES = {free: 'Free', pro: 'Pro', team: 'Team'}

const CHANNELS = [
  {id: 1, title: 'Email'},
  {id: 2, title: 'Slack'},
  {id: 3, title: 'Push notifications'},
]

const plan = ref<typeof PLANS[number]>('pro')
const channels = ref<number[]>([1])
</script>
```

With `loading`, the option that was clicked last shows a spinner and the others are disabled — set it while the change saves.

## API

### WCheckbox

```ts
import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `boolean \| null` | **required** | Checked state. `null` is the mixed state — drawn as a smaller mark with `intermediate`. |
| `title` | `string` | — | Label next to the box; the default slot replaces it. |
| `disabled` | `boolean` | — | Blocks changes and dims the checkbox. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Shows the state without allowing changes. When unset, inherits the readonly state provided by a parent. |
| `icon` | `SVGComponent` | — | Icon drawn inside the box instead of the check mark. |
| `radio` | `boolean` | — | Round radio button with a dot instead of a square box with a check mark. |
| `loading` | `boolean` | — | Shows a spinner in the box and ignores clicks. |
| `skeleton` | `boolean` | — | Renders in a gray loading state and ignores clicks. When unset, inherits the skeleton state provided by a parent. |
| `intermediate` | `boolean` | — | Draws a `null` model as a smaller mark, the mixed state, instead of a filled box. |
| `tooltipText` | `string` | — | Tooltip on hover over the box. Not shown on touch devices. Also names a checkbox without `title` or `label` for screen readers. |
| `label` | `string` | — | Names a checkbox without a visible `title` for screen readers. |
| `alignTop` | `boolean` | — | Aligns the box with the first line of a multi-line title instead of centering it. |
| `noMargin` | `boolean` | — | Drops the bottom padding added under a checkbox with a title. |
| `lessTransitions` | `boolean` | — | Checks and unchecks without the scale animation. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: boolean)` | The opposite of the current state — a `null` model becomes `true`. |
| `mousedown` | `(value: MouseEvent)` | Mouse down on the checkbox. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Label next to the box. Replaces `title`. |

### WCheckboxGroup

```ts
import WCheckboxGroup from 'eco-vue-js/dist/components/Checkbox/WCheckboxGroup.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `list` | `Model[] \| Entity[] \| readonly Entity[] \| readonly Model[]` | **required** | Option objects, turned into values by `valueGetter`. Option values. |
| `valueGetter` | `ValueGetter \| ((value: Entity) => Model)` | — | Maps a `list` item to its value. Maps a `list` item to its value. Required when `list` holds objects. |
| `optionComponent` | `CheckboxGroupOptionComponent<Entity> \| CheckboxGroupOptionComponent<Model>` | — | Renders an option's label. The `option` slot replaces it. |
| `modelValue` | `Model \| undefined` | **required** | Selected value. |
| `wrap` | `boolean` | — | Lays the options out in a row that wraps, instead of a column. |
| `stretch` | `boolean` | — | Lays the options out in one row, stretched to equal widths. |
| `loading` | `boolean` | — | Shows a spinner in the last clicked option and disables the others, while its change is saved. |
| `allowClear` | `boolean` | — | Clicking the selected option again emits `null`. |
| `iconMap` | `Record<GroupModelStringified<Model>, SVGComponent>` | — | Icon inside each option's box, keyed by the option's value as a string. |
| `titleMap` | `Record<GroupModelStringified<Model>, string>` | — | Label of each option, keyed by the option's value as a string. |
| `tooltipTextMap` | `Record<GroupModelStringified<Model>, string>` | — | Tooltip on each option's box, keyed by the option's value as a string. |
| `classMap` | `Record<GroupModelStringified<Model>, string>` | — | Classes for each option, keyed by the option's value as a string. |
| `optionClass` | `string` | — | Classes for every option. |
| `radio` | `boolean` | — | Round radio button with a dot instead of a square box with a check mark. |
| `alignTop` | `boolean` | — | Aligns the box with the first line of a multi-line title instead of centering it. |
| `lessTransitions` | `boolean` | — | Checks and unchecks without the scale animation. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (23)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `maxLength` | `number` | — | Shows a `length / maxLength` counter under the field while it is focused. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Shows the value without allowing changes. When unset, inherits the readonly state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(Model)` | The clicked option's value, or `null` when `allowClear` unselects it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the options. |
| `option` | `{ option: ValueGetter extends undefined ? Model : Entity; selected: boolean; }` | Renders an option's label. Replaces `optionComponent` and `titleMap`. |
| `right` | — | Content to the right of the options. |

### WCheckboxGroupMultiple

```ts
import WCheckboxGroupMultiple from 'eco-vue-js/dist/components/Checkbox/WCheckboxGroupMultiple.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `list` | `Model[] \| Entity[] \| readonly Entity[] \| readonly Model[]` | **required** | Option objects, turned into values by `valueGetter`. Option values. |
| `valueGetter` | `ValueGetter \| ((value: Entity) => Model)` | — | Maps a `list` item to its value. Maps a `list` item to its value. Required when `list` holds objects. |
| `optionComponent` | `CheckboxGroupOptionComponent<Entity> \| CheckboxGroupOptionComponent<Model>` | — | Renders an option's label. The `option` slot replaces it. |
| `modelValue` | `Model[] \| undefined` | **required** | Selected values. |
| `radio` | `boolean` | — | Round radio button with a dot instead of a square box with a check mark. |
| `loading` | `boolean` | — | Shows a spinner in the last clicked option and disables the others, while its change is saved. |
| `alignTop` | `boolean` | — | Aligns the box with the first line of a multi-line title instead of centering it. |
| `lessTransitions` | `boolean` | — | Checks and unchecks without the scale animation. |
| `wrap` | `boolean` | — | Lays the options out in a row that wraps, instead of a column. |
| `stretch` | `boolean` | — | Lays the options out in one row, stretched to equal widths. |
| `iconMap` | `Record<GroupModelStringified<Model>, SVGComponent>` | — | Icon inside each option's box, keyed by the option's value as a string. |
| `titleMap` | `Record<GroupModelStringified<Model>, string>` | — | Label of each option, keyed by the option's value as a string. |
| `tooltipTextMap` | `Record<GroupModelStringified<Model>, string>` | — | Tooltip on each option's box, keyed by the option's value as a string. |
| `classMap` | `Record<GroupModelStringified<Model>, string>` | — | Classes for each option, keyed by the option's value as a string. |
| `optionClass` | `string` | — | Classes for every option. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (23)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `maxLength` | `number` | — | Shows a `length / maxLength` counter under the field while it is focused. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Shows the value without allowing changes. When unset, inherits the readonly state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `select` | `(Model)` | An unselected option was clicked. |
| `unselect` | `(Model)` | A selected option was clicked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the options. |
| `option` | `{ option: ValueGetter extends undefined ? Model : Entity; selected: boolean; }` | Renders an option's label. Replaces `optionComponent` and `titleMap`. |
| `right` | — | Content to the right of the options. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/form.md
description: >-
  WUniform — forms built from nested WUniform fields, with validation, saving
  only the changed fields, auto-save, loading the model with a query, and
  readonly, disabled and skeleton states.
---

# Form

Forms are built from one component, `WUniform`, used at two levels:

* The **form** holds the model and saves it. Its default slot gives a scope for the fields.
* Each **field** is a nested `WUniform` that gets the form's scope with `v-bind="scope"` and a `field` key. Its `field` slot renders the control, which gets its value, title, error message and states with `v-bind="scopeField"`.

The kit's controls — WInput, WSelect, WCheckbox, WToggle, WButtonGroup and the others — take the field scope as it is.

## Submit

With `initData`, the form keeps its own copy of the model, built from the given or loaded value. `submit` from the scope, or from the form's template ref, validates the fields and calls `apiMethod`:

* If a field is invalid, nothing is sent: the errors show on the fields, a warning lists them, and the page scrolls to the first one. The list in the warning is a `WUniformErrorMessage`, which can also show a validation result elsewhere.
* Only the changed fields are sent. `fullPayload` sends the whole model.
* The result of `apiMethod` becomes the new initial model, so `hasChanges` resets, and is emitted with `success`.
* When `apiMethod` rejects with an `ApiError`, the field errors in its response show on the matching fields. Try `taken@example.com` below.

`validate` takes one function or a list, each returning an error message or `undefined`. Errors appear after a submit attempt — on each change with `async` — and clear as soon as the value is valid. `required` is checked first.

```vue
<template>
  <WUniform
    :init-data="initData"
    :api-method="save"
    tag="div"
    class="grid max-w-md"
  >
    <template #default="scope">
      <WUniform
        v-bind="scope"
        field="name"
        title="Name"
        required
      >
        <template #field="scopeField">
          <WInput
            v-bind="scopeField"
            required
          />
        </template>
      </WUniform>

      <WUniform
        v-bind="scope"
        field="email"
        title="Email"
        :validate="validateEmail"
        required
      >
        <template #field="scopeField">
          <WInput
            v-bind="scopeField"
            placeholder="Try taken@example.com"
            required
          />
        </template>
      </WUniform>

      <WUniform
        v-bind="scope"
        field="newsletter"
        title="Subscribe to the newsletter"
      >
        <template #field="scopeField">
          <WCheckbox
            v-bind="scopeField"
            class="mb-4"
          />
        </template>
      </WUniform>

      <WButton
        :disabled="!scope.hasChanges"
        :loading="scope.submitting"
        class="w-fit"
        @click="scope.submit?.()"
      >
        Save
      </WButton>
    </template>
  </WUniform>

  <p class="mt-4 text-sm text-description">
    Last payload: {{ sent ? JSON.stringify(sent) : '—' }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {ApiError} from 'eco-vue-js/dist/utils/api'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

type Profile = {name: string, email: string, newsletter: boolean}

const sent = ref<Partial<Profile>>()

let stored: Profile = {name: '', email: '', newsletter: false}

const initData = (value: Partial<Profile>): Profile => ({
  name: value.name ?? '',
  email: value.email ?? '',
  newsletter: value.newsletter ?? false,
})

const validateEmail = (value: unknown) => typeof value === 'string' && value && !value.includes('@') ? 'Enter a valid email' : undefined

// Stands in for an API call: gets only the changed fields and returns the whole saved object.
const save = (payload: Partial<Profile>) => new Promise<Profile>((resolve, reject) => {
  sent.value = payload

  setTimeout(() => {
    if (payload.email === 'taken@example.com') {
      reject(new ApiError({data: {email: ['This email is already taken']}, request: new Request('/profile')}))
    } else {
      stored = {...stored, ...payload}
      resolve(stored)
    }
  }, 800)
})
</script>
```

A form in a modal usually has its buttons in the modal's `actions` slot, outside the scope. There, a template ref gives the same `submit` and `submitting` — see [Modal](/components/modal).

## Auto-save

`async` saves every change right away, one field at a time. The changed field shows a spinner while it is saved, and the rest of the form stays editable. `confimGetter` asks before a change is applied — on cancel the change is dropped and the field shows the saved value again.

Only the changed fields are validated and sent. An invalid one shows its error at once and keeps its value without being saved, and changes to other fields are still saved. The value is sent once it is fixed. A change made while a save is in progress is sent when that save ends. When `apiMethod` returns nothing, the sent values become the initial ones for their fields. Fields that weren't sent keep their unsaved changes. `fullPayload` sends the whole model instead and waits until every field is valid.

```vue
<template>
  <WUniform
    :init-data="initData"
    :api-method="save"
    tag="div"
    class="grid max-w-md"
    async
  >
    <template #default="scope">
      <WUniform
        v-bind="scope"
        field="notifications"
        title="Email notifications"
        :confim-getter="confirmDisable"
      >
        <template #field="scopeField">
          <WToggle
            v-bind="scopeField"
            class="mb-4"
          />
        </template>
      </WUniform>

      <WUniform
        v-bind="scope"
        field="theme"
        title="Theme"
      >
        <template #field="scopeField">
          <WButtonGroup
            v-bind="scopeField"
            :list="['light', 'dark', 'system']"
          >
            <template #option="{option}">
              {{ option }}
            </template>
          </WButtonGroup>
        </template>
      </WUniform>
    </template>
  </WUniform>
</template>

<script lang="ts" setup>
import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

type Settings = {notifications: boolean, theme: string}

let stored: Settings = {notifications: true, theme: 'system'}

const initData = (): Settings => ({...stored})

// Stands in for an API call.
const save = (payload: Partial<Settings>) => new Promise<Settings>(resolve => {
  setTimeout(() => {
    stored = {...stored, ...payload}
    resolve(stored)
  }, 800)
})

const confirmDisable = (value: boolean): ConfirmProps | undefined => value ? undefined : {
  title: 'Turn off notifications?',
  description: 'You will stop getting emails about new comments.',
  acceptText: 'Turn off',
}
</script>
```

## Loading the model

`useQueryFn` loads the model with a query when no `modelValue` is given, with `queryParams` for its params or `noParams` when it takes none. The fields show skeletons until it loads, and `initData` turns the loaded value into the editable model:

```vue
<WUniform
  :use-query-fn="settingsApi.use"
  :query-params="projectId"
  :init-data="getModel"
  :api-method="settingsApi.update"
>
  <template #default="scope">
    ...
  </template>
</WUniform>
```

When the loaded value changes — another view saved the item and updated the cache, or an auto-save did — the form takes it and keeps the changes not saved yet. When `queryParams` change, the form loads another item and drops its changes, and so do the forms inside it that keep their own copy of the model. Until that item loads, the form keeps its current model, so a create whose result carries the new id stays filled while the saved item loads.

## Nested objects

A nested `WUniform` with a default slot instead of a `field` slot edits an object inside the model. Its fields bind its own scope:

```vue
<WUniform
  v-bind="scope"
  field="address"
>
  <template #default="scopeAddress">
    <WUniform
      v-bind="scopeAddress"
      field="city"
      title="City"
    >
      <template #field="scopeField">
        <WInput v-bind="scopeField" />
      </template>
    </WUniform>
  </template>
</WUniform>
```

Changes, errors and `fullPayload` work per field as for top-level ones.

## Readonly, disabled and skeleton

`readonly`, `disabled` and `skeleton` set on the form reach every field with the scope. While a form without `async` is submitting, its fields are disabled.

```vue
<template>
  <WButtonGroup
    v-model="state"
    :list="['editable', 'readonly', 'disabled', 'skeleton']"
    class="mb-6"
  >
    <template #option="{option}">
      {{ option }}
    </template>
  </WButtonGroup>

  <WUniform
    :init-data="initData"
    :readonly="state === 'readonly'"
    :disabled="state === 'disabled'"
    :skeleton="state === 'skeleton'"
    tag="div"
    class="grid max-w-md"
  >
    <template #default="scope">
      <WUniform
        v-bind="scope"
        field="title"
        title="Title"
      >
        <template #field="scopeField">
          <WInput v-bind="scopeField" />
        </template>
      </WUniform>

      <WUniform
        v-bind="scope"
        field="priority"
        title="Priority"
      >
        <template #field="scopeField">
          <WButtonGroup
            v-bind="scopeField"
            :list="['low', 'medium', 'high']"
          >
            <template #option="{option}">
              {{ option }}
            </template>
          </WButtonGroup>
        </template>
      </WUniform>
    </template>
  </WUniform>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

const state = ref('editable')

const initData = () => ({title: 'Repot the monstera', priority: 'medium'})
</script>
```

To set a state for a whole area — every form and control in a page, for a user without edit rights — provide it from a parent component instead. Controls use the provided value when their own prop is unset:

```ts
import {useProvideReadonly} from 'eco-vue-js/dist/utils/provide'

useProvideReadonly(computed(() => !canEdit.value))
```

`useProvideDisabled` and `useProvideSkeleton` work the same way.

## With tabs

Forms inside [WTabs](/components/tabs) report their `hasChanges`, `hasValue` and errors to their tab, which marks its button. The tabs switch to a tab that gets an error. `mandatory` counts a field in `hasValue` without making it required, and `initHasValue` and `initHasError` set these states while a tab's fields are not mounted.

## API

### WUniform

```ts
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Key the form registers under with its parent form and with tabs. Generated when unset. |
| `modelValue` | `Model` | — | The model to edit. A field gets its parent's model with the scope and reads the value at `field`. |
| `modelValueInit` | `Model` | — | Initial model that `hasChanges` compares against, when the form has no copy of its own. |
| `field` | `Field` | — | Key in the parent's model that this form or field edits. |
| `initData` | `((value: InnerModel) => ResultModel)` | — | Builds the editable model from the given or loaded value. With it, the form keeps its own copy of the model instead of emitting `update:model-value`. |
| `apiMethod` | `((value: Partial<ResultModel>) => void \| InnerModel \| Promise<RequestResponse<InnerModel, RequestData>> \| Promise<InnerModel> \| undefined)` | — | Saves the model on submit. Gets only the changed fields unless `fullPayload`. The result becomes the new initial model and is emitted with `success`; the field errors of a rejected `ApiError` are shown on the fields. |
| `readonly` | `boolean` | — | Passed to the slots, and with the scope to every field of the form. |
| `disabled` | `boolean` | — | Passed to the slots, and with the scope to every field of the form. |
| `tag` | `string` | — | Element to wrap the content in. Renders no wrapper when unset. |
| `title` | `string` | — | Title of the field, passed to the `field` slot. Also names the field in validation messages. |
| `required` | `boolean` | — | The field must have a value. Checked before `validate` and passed to the `field` slot. |
| `mandatory` | `boolean` | — | Counts the field in the form's `hasValue`, which tabs show with `showHasValue`, without making it required. |
| `skeleton` | `boolean` | — | Passed to the slots, and with the scope to every field of the form. Set on its own while `useQueryFn` loads. |
| `async` | `boolean` | — | Saves every change right away. The changed field shows a spinner instead of the whole form being disabled. Only changed fields are checked and sent: an invalid one shows its error and waits until it is fixed, while the rest are saved. A change made while saving is sent once the save ends. |
| `validate` | `ValidateFn \| ValidateFn[]` | — | Functions returning an error message for an invalid value. Errors show after a submit attempt, or on each change with `async`, and clear as soon as the value is valid. |
| `submitting` | `boolean` | — | Submitting state of a parent form, received with the scope. |
| `noInit` | `boolean` | — | Keeps the current model after a successful submit instead of taking the result as the new initial model. |
| `fullPayload` | `boolean` | — | Submits the whole model instead of only the changed fields. On a field, sends its whole object when anything in it changed. |
| `initHasValue` | `boolean \| null` | — | Overrides the `hasValue` state reported to the parent, e.g. while the fields are not mounted. |
| `initHasError` | `boolean` | — | Overrides the error state reported to the parent, e.g. while the fields are not mounted. |
| `noChanges` | `boolean` | — | Never reports unsaved changes. |
| `confimGetter` | `((payload: ResultModel, data: Model) => ConfirmProps \| Promise<ConfirmProps \| undefined> \| undefined)` | — | Returns the props of a confirm modal to show before a change is applied. The change is dropped on cancel, along with the field's unsaved draft; returning nothing applies it at once. |
| `useQueryFn` | `UseQueryDefault<InnerModel, QueryParams> \| UseQueryDefault<InnerModel, undefined>` | — | Query that loads the model when `modelValue` is not given. The form shows skeletons until it loads. |
| `queryParams` | `QueryParams` | — | Params of `useQueryFn`. |
| `noParams` | `true` | — | `useQueryFn` takes no params. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(ResultModel, (string \| number)[])` | A changed value and the path of keys to it, from a form without its own copy of the model. |
| `success` | `(InnerModel)` | `apiMethod` resolved, with its result or, when it returned nothing, the submitted payload. |
| `unmounted` | `(string)` | The form was unmounted, with its `id`. |
| `init-model` | — | Asks the parent to take the current model as the initial one, from a form without its own copy of the model. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `field` | `UniformScopeField<ResultModel>` | Renders the control of a field. Spread the scope onto it with `v-bind`: it carries the model, title, error message and states. |
| `default` | `UniformScope<ResultModel, InnerModel>` | Renders the fields of a form. Spread the scope onto each nested WUniform with `v-bind`; it also has `submit`, `submitting` and `hasChanges`. |

### WUniformErrorMessage

```ts
import WUniformErrorMessage from 'eco-vue-js/dist/components/Uniform/WUniformErrorMessage.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `string \| ValidateResponse` | **required** | Validation result of a form: a message, or the messages of its fields by title, nested for nested forms. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/button-group.md
description: >-
  WButtonGroup — a segmented control that picks one value out of a short list,
  bound with v-model.
---

# Button group

## Basic usage

`WButtonGroup` is a segmented control bound with `v-model`. `list` takes plain values; for objects, also pass `valueGetter` to pick the model value out of each item.

Options have no default label: render each one through the `option` slot, or pass an `optionComponent` that receives `option` and `selected`.

```vue
<template>
  <WButtonGroup
    v-model="period"
    :list="periods"
    title="Period"
  >
    <template #option="{option}">
      {{ option }}
    </template>
  </WButtonGroup>

  <p class="mt-2 text-sm text-description">
    Selected: {{ period }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'

const periods = ['day', 'week', 'month'] as const

const period = ref<typeof periods[number]>('week')
</script>
```

## API

### WButtonGroup

```ts
import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `list` | `Entity[] \| readonly Model[]` | **required** | Options, each passed to the `option` slot. A primitive is its own value, an object needs `valueGetter`. |
| `valueGetter` | `ValueGetter \| ((value: Entity) => Model)` | — | Value of an option. Needed when `list` holds objects. |
| `optionComponent` | `ButtonGroupOptionComponent<Entity> \| ButtonGroupOptionComponent<Model>` | — | Renders an option's content. The `option` slot replaces it. |
| `modelValue` | `Model` | **required** | Value of the pressed option. |
| `wrap` | `boolean` | — | Wraps the options onto new lines instead of overflowing. |
| `col` | `boolean` | — | Stacks the options vertically. |
| `semanticType` | `SemanticType` | `SemanticType.PRIMARY` | Color scheme of the pressed option. |
| `loading` | `boolean` | — | Shows a spinner in the last clicked option and disables the others, while its change is saved. |
| `stretch` | `boolean` | — | Stretches the group to the full width, sharing it equally between the options. |
| `allowClear` | `boolean` | — | A click on the pressed option emits `null`. |
| `disabledItems` | `Model[]` | — | Values of the options to disable. |

::: details Inherited from `src/components/FieldWrapper/types.ts` (23)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `maxLength` | `number` | — | Shows a `length / maxLength` counter under the field while it is focused. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Shows the value without allowing changes. When unset, inherits the readonly state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(Model)` | Value of the clicked option, or `null` when the pressed one is clicked with `allowClear`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the options. |
| `option` | `{ option: ValueGetter extends undefined ? Model : Entity; selected: boolean; }` | Content of an option's button. While readonly, only the pressed option is shown. |
| `right` | — | Content to the right of the options. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/date-picker.md
description: >-
  WDatePicker and WDatePickerSingle — calendars for picking a date range or a
  single day, limited by minDate and maxDate.
---

# Date picker

Calendars for picking dates by pointing at them. They have no title or form-field frame of their own — put them in the `field` slot of a [`WFieldWrapper`](/components/field-wrapper) or next to your own label. In a form, [`WInputDate`](/components/input#date) is usually the one to use: it is a field with this calendar in a dropdown.

`WDatePicker` picks a range: the first click starts it, the range follows the pointer, and the second click ends it and emits `{from, to}`, in order whichever day was clicked first. The two cards on top show the ends; clicking one goes to its month.

`WDatePickerSingle` picks one day on the first click.

`minDate` and `maxDate` limit the days that can be picked and the months the calendar goes to. Days come at the start of the day, in local time. Helpers such as `getStartOfDay`, `addDay` and `dateFormat` are in [Formatting](/utilities/formatting#dates).

```vue
<template>
  <div class="grid gap-8 md:grid-cols-2">
    <div class="grid content-start gap-2">
      <WDatePicker
        v-model="range"
        :max-date="today"
      />

      <span class="text-description text-sm">
        {{ range ? `${ dateFormat(range.from) } – ${ dateFormat(range.to) }` : 'No range' }}
      </span>
    </div>

    <div class="grid content-start gap-2">
      <WDatePickerSingle
        v-model="day"
        :min-date="today"
      />

      <span class="text-description text-sm">
        {{ day ? dateFormat(day) : 'No day' }}
      </span>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import type {DateRange} from 'eco-vue-js/dist/components/DatePicker/models/types'
import {addDay, dateFormat, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import WDatePicker from 'eco-vue-js/dist/components/DatePicker/WDatePicker.vue'
import WDatePickerSingle from 'eco-vue-js/dist/components/DatePicker/WDatePickerSingle.vue'

const today = getStartOfDay()

const range = ref<DateRange | undefined>({from: addDay(today, -6), to: today})
const day = ref<Date>()
</script>
```

## API

### WDatePicker

```ts
import WDatePicker from 'eco-vue-js/dist/components/DatePicker/WDatePicker.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `DateRange \| undefined` | **required** | Picked range, from its first to its last day. The calendar opens at its month. |
| `minDate` | `Date` | — | First day that can be picked. The calendar doesn't go to earlier months. |
| `maxDate` | `Date` | — | Last day that can be picked. The calendar doesn't go to later months. |
| `readonly` | `boolean` | — | Shows the calendar without picking a range. When unset, inherits the readonly state provided by a parent. |
| `disabled` | `boolean` | — | Shows the calendar without picking a range. When unset, inherits the disabled state provided by a parent. |
| `skeleton` | `boolean` | — | Shows the calendar without picking a range. When unset, inherits the skeleton state provided by a parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: DateRange \| undefined)` | The picked range, once its second day is clicked. The days are in order whichever was clicked first. |

### WDatePickerSingle

```ts
import WDatePickerSingle from 'eco-vue-js/dist/components/DatePicker/WDatePickerSingle.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Date \| undefined` | **required** | Picked day. The calendar opens at its month. |
| `minDate` | `Date` | — | First day that can be picked. The calendar doesn't go to earlier months. |
| `maxDate` | `Date` | — | Last day that can be picked. The calendar doesn't go to later months. |
| `readonly` | `boolean` | — | Shows the calendar without picking a day. When unset, inherits the readonly state provided by a parent. |
| `disabled` | `boolean` | — | Shows the calendar without picking a day. When unset, inherits the disabled state provided by a parent. |
| `skeleton` | `boolean` | — | Shows the calendar without picking a day. When unset, inherits the skeleton state provided by a parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: Date \| undefined)` | The clicked day, at the start of the day. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/field-wrapper.md
description: >-
  WFieldWrapper — the frame every control is built on, with title, description,
  messages, changes marker and states, used on its own for read-only values and
  for controls of your own.
---

# Field wrapper

`WFieldWrapper` is the frame that the inputs, selects and other controls are built on: the title (with `required` and `titleIcon`), a `description` under the field, the error message, the unsaved changes dot (`hasChanges`), a length counter (`maxLength`) and a tooltip, with the skeleton, disabled and readonly states inherited like any control.

On its own it shows a value that can't be edited, such as a detail on a record page. `modelValue` is formatted — numbers with thousands separators, `null` as "N / A" — or the default slot replaces it with anything, such as a chip. `allowCopy` adds a copy button and `mono` a monospace font.

The `field` slot replaces the whole field, to give a control of your own — here a slider — the same title and messages as the kit's controls. The slot gets an `id` to label it, and `setFocused` for the counter.

```vue
<template>
  <div class="grid gap-8 md:grid-cols-2">
    <div>
      <WFieldWrapper
        title="Sensor"
        model-value="greenhouse-2/moisture-07"
        mono
        allow-copy
      />

      <WFieldWrapper
        title="Seeds sown"
        :model-value="12840"
        description="Across all beds."
      />

      <WFieldWrapper
        title="Caretaker"
        :model-value="null"
      />
    </div>

    <div>
      <WFieldWrapper
        title="Moisture threshold"
        :has-changes="threshold !== 7"
        description="The sprinklers start below it."
        required
      >
        <template #field>
          <WSlider
            v-model="threshold"
            :min="1"
            :max="10"
          >
            <template #right>
              <span class="w-6 text-right font-semibold">{{ threshold }}</span>
            </template>
          </WSlider>
        </template>
      </WFieldWrapper>

      <WFieldWrapper title="Status">
        <WChip
          text="Thriving"
          :semantic-type="SemanticType.POSITIVE"
        />
      </WFieldWrapper>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
import WFieldWrapper from 'eco-vue-js/dist/components/FieldWrapper/WFieldWrapper.vue'
import WSlider from 'eco-vue-js/dist/components/Slider/WSlider.vue'

const threshold = ref(7)
</script>
```

## Layout

* `subgrid` puts the title and the field on the parent grid's columns, so that the titles of a column of fields line up — the parent needs a grid with those columns.
* `seamless` hides the title and the field's frame until it is hovered or focused, for editing in place, such as in a table cell. `embedded` fits a field inside another component, without title or margin.
* `filterField` adds a filter button to the title, which toggles the value as a query param — e.g. from a plant's bed to the list of that bed's plants.
* `noMargin` drops the space under the field, `topText` moves the messages above it and `leftError` aligns the error to the left.

## API

### WFieldWrapper

```ts
import WFieldWrapper from 'eco-vue-js/dist/components/FieldWrapper/WFieldWrapper.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `string \| number \| boolean \| null` | — | Value shown in the field — numbers with thousands separators and `null` as "N / A". Also what `allowCopy` copies. |
| `title` | `string` | — | Label above the field; the `title` slot replaces it. |
| `titleIcon` | `SVGComponent` | — | Icon before the title text. |
| `description` | `string` | — | Secondary text under the field. |
| `errorMessage` | `string` | — | Validation message under the field, which also colors the changes marker. |
| `tooltipText` | `string` | — | Tooltip on hover over the whole field. Not shown while readonly or loading as a skeleton. |
| `maxLength` | `number` | — | Shows a `length / maxLength` counter under the field while it is focused. |
| `mono` | `boolean` | — | Monospace font for the value. |
| `hasChanges` | `boolean` | — | Shows a dot in the field's corner, marking an unsaved change. |
| `skeleton` | `boolean` | — | Renders skeleton placeholders for the title, field and description. When unset, inherits the skeleton state provided by a parent. |
| `disabled` | `boolean` | — | Blocks input and dims the field. When unset, inherits the disabled state provided by a parent. |
| `readonly` | `boolean` | — | Shows the value without allowing changes. When unset, inherits the readonly state provided by a parent. |
| `required` | `boolean` | — | Adds an asterisk to the title. |
| `noMargin` | `boolean` | — | Drops the default bottom margin. |
| `allowCopy` | `boolean` | — | Adds a button that copies the value. |
| `leftError` | `boolean` | — | Aligns the error message to the left instead of the right. |
| `filterField` | `string` | — | Route query key for a filter button next to the title — clicking it toggles `filterField=<value>` in the URL. |
| `filterValue` | `unknown` | — | Value the filter button puts in the query. Defaults to `modelValue`. |
| `subgrid` | `boolean` | — | Lays the field out on the parent grid's columns, with the title in the first column, so titles and fields line up across rows. |
| `seamless` | `boolean` | — | Hides the title and drops the field's own chrome until it is hovered or focused, for inline editing. |
| `topText` | `boolean` | — | Moves the counter and messages above the field instead of below it. |
| `allowDropFile` | `boolean` | — | Accepts files dropped onto the field. |
| `hideTitle` | `boolean` | — | Hides the title while keeping the rest of the layout. |
| `embedded` | `boolean` | — | For a field placed inside another component, such as a dropdown: no title, no margin, and horizontal padding. |
| `noLabelFor` | `boolean` | — | Renders the title without `for`, for a field that is not a form control, such as a contenteditable — clicking the title still focuses the field. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The field was clicked. |
| `drop` | `(value: DataTransferItemList)` | Items were dropped onto the field, with `allowDropFile`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `subtitle` | — | Content between the title and the field. |
| `right` | — | Content to the right of the field. |
| `bottom` | — | Content between the field and the description. |
| `field` | `{ id: string; focused: boolean; setFocused: (value: boolean) => void; isDragover: boolean; }` | The whole field, replacing the value row — for a control of your own. `id` labels it, and `setFocused` shows the length counter while it is focused. |
| `default` | `{ id: string; focused: boolean; setFocused: (value: boolean) => void; isDragover: boolean; }` | Content of the value row, replacing the formatted `modelValue`. The copy button stays after it. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/file-picker.md
description: >-
  WFilePicker — a drop zone with a browse button for one or several files, with
  a placeholder for a file that is already saved.
---

# File picker

`WFilePicker` is a drop zone with a browse button. Dropped or picked files replace the model; each one shows with its name and a button to remove it. Without `multiple`, only the first dropped file is taken. `accept` limits what the browse dialog offers, but not what can be dropped — check the files before uploading them.

`placeholder` shows a file that is already saved, such as the current avatar, by its name, until another file is picked. Removing it emits `clear:placeholder`. The `positive` and `negative` slots replace the file's icon, e.g. with a preview of an image.

The drop zone lights up while a file is dragged anywhere over the page, once the app has called `preventDragFile()` at startup — which also stops the browser from opening a file dropped beside the zone. See [Helpers](/utilities/helpers#browser).

```vue
<template>
  <div class="grid max-w-xl gap-4">
    <WFilePicker
      v-model="files"
      title="Attachments"
      accept="image/*,.pdf"
      multiple
    />

    <WFilePicker
      v-model="avatar"
      title="Avatar"
      :placeholder="current"
      accept="image/*"
      @update:model-value="current = undefined"
      @clear:placeholder="current = undefined"
    />
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WFilePicker from 'eco-vue-js/dist/components/FilePicker/WFilePicker.vue'

const files = ref<File[]>([])

// The file that is already saved, shown until a new one is picked or it is removed.
const avatar = ref<File[]>([])
const current = ref<string | undefined>('avatar.png')
</script>
```

## API

### WFilePicker

```ts
import WFilePicker from 'eco-vue-js/dist/components/FilePicker/WFilePicker.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `File[]` | **required** | Picked files. |
| `placeholder` | `string` | — | Name of a file that is already saved, such as the current avatar, shown while no file is picked. Removing it emits `clear:placeholder`. |
| `multiple` | `boolean` | — | Lets several files be picked at once. |
| `accept` | `string` | — | File types the browse dialog offers, as in the input's `accept` attribute, e.g. `image/*,.pdf`. |
| `errorMessage` | `string` | — | Error shown under the drop zone. The files get a cross instead of a check. |
| `title` | `string` | — | Label above the drop zone. |
| `skeleton` | `boolean` | — | Shows a placeholder for the title and stops picking. When unset, inherits the skeleton state provided by a parent. |
| `readonly` | `boolean` | — | Stops picking. When unset, inherits the readonly state provided by a parent. |
| `disabled` | `boolean` | — | Stops picking. When unset, inherits the disabled state provided by a parent. |
| `required` | `boolean` | — | Marks the title with a red asterisk. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `clear:placeholder` | — | The `placeholder` file was removed. |
| `update:model-value` | `(value: File[])` | Files picked with the dialog or dropped, replacing the previous ones, or the files left after one is removed. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Replaces the `title` text. |
| `positive` | `{ file?: File \| undefined; }` | Icon of a file, replacing the check. `file` is unset for the `placeholder`. |
| `negative` | `{ file?: File \| undefined; }` | Icon of a file while there is an error, replacing the cross. `file` is unset for the `placeholder`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/slider.md
description: >-
  WSlider and WSliderRange — pick a number or a range by dragging, with an eager
  value while dragging and colors set by utilities.
---

# Slider

`WSlider` picks a number and `WSliderRange` a range, from `min` to `max` in steps of `step`. They have no title or form-field frame of their own — put them in the `field` slot of a [`WFieldWrapper`](/components/field-wrapper) or next to your own label.

Dragging emits `update-eager:model-value` at every step and `update:model-value` once it ends, so the value can be shown as it moves while the model — and a query using it — changes only once. The `right` slot is the place for it.

`WSlider` is colored by `semanticType`. `WSliderRange` fades from one end's color to the other's, set with the `w-slider-from-*` and `w-slider-to-*` utilities from the kit's Tailwind base, e.g. `w-slider-from-positive w-slider-to-negative`. Both ends are primary by default.

For a scale the colors run along, such as hues, set `--w-slider-track` and `--w-slider-fill` to background images: the first paints the whole track, the second the picked part over the end colors.

```vue
<template>
  <div class="grid max-w-md gap-6">
    <WSlider
      v-model="rating"
      :min="1"
      :max="10"
      @update-eager:model-value="ratingEager = $event"
    >
      <template #right>
        <span class="w-8 text-right font-semibold">{{ ratingEager ?? rating }}</span>
      </template>
    </WSlider>

    <WSliderRange
      v-model="score"
      :min="0"
      :max="100"
      :step="10"
      class="w-slider-from-positive w-slider-to-negative"
      @update-eager:model-value="scoreEager = $event"
    >
      <template #right>
        <span class="w-16 text-right font-semibold">{{ (scoreEager ?? score).from }}–{{ (scoreEager ?? score).to }}</span>
      </template>
    </WSliderRange>
  </div>
</template>

<script lang="ts" setup>
import {ref, watch} from 'vue'

import WSlider from 'eco-vue-js/dist/components/Slider/WSlider.vue'
import WSliderRange from 'eco-vue-js/dist/components/Slider/WSliderRange.vue'

const rating = ref(7)
const ratingEager = ref<number>()

const score = ref({from: 30, to: 70})
const scoreEager = ref<{from: number, to: number}>()

// The eager value is only for showing the drag; the picked value takes over once it ends.
watch(rating, () => ratingEager.value = undefined)
watch(score, () => scoreEager.value = undefined)
</script>
```

## API

### WSlider

```ts
import WSlider from 'eco-vue-js/dist/components/Slider/WSlider.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `number` | **required** | Picked value, from `min` to `max`. |
| `min` | `number` | `1` | Value at the left end. |
| `max` | `number` | `10` | Value at the right end. |
| `step` | `number` | `1` | Values snap to steps of this size from `min`. |
| `semanticType` | `SemanticType` | `SemanticType.PRIMARY` | Color of the filled part. |
| `disabled` | `boolean` | — | Grays the slider out and stops dragging. |
| `readonly` | `boolean` | — | Stops dragging. |
| `errorMessage` | `string` | — | Error shown under the slider. The filled part turns red. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: number)` | The value where dragging ended. |
| `update-eager:model-value` | `(value: number)` | The value under the pointer while dragging, for showing it before it is picked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `right` | — | Content to the right of the slider, such as the value. |

### WSliderRange

```ts
import WSliderRange from 'eco-vue-js/dist/components/Slider/WSliderRange.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `Range` | **required** | Picked range, with `from` no greater than `to`. |
| `min` | `number` | `1` | Value at the left end. |
| `max` | `number` | `10` | Value at the right end. |
| `step` | `number` | `1` | Values snap to steps of this size from `min`. |
| `disabled` | `boolean` | — | Grays the slider out and stops dragging. |
| `readonly` | `boolean` | — | Stops dragging. |
| `errorMessage` | `string` | — | Error shown under the slider. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:model-value` | `(value: Range)` | The range where dragging ended. |
| `update-eager:model-value` | `(value: Range)` | The range under the pointer while dragging, for showing it before it is picked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `right` | — | Content to the right of the slider, such as the range. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/tabs.md
description: >-
  WTabs and WTabsItem — tabbed content with icons, counters and disabled tabs,
  closable and added tabs, a side layout, and status marks for forms.
---

# Tabs

`WTabs` takes `WTabsItem` children and renders a header of tab buttons above the active tab's content. Each item needs a unique `name`; `title`, `icon` and `count` go on its button, the count as a badge. `divider` draws a line under the buttons. The first tab opens unless `initTab`, `initTabIndex` or an item's `init` says otherwise.

```vue
<template>
  <WTabs
    :init-tab="current"
    divider
    @update:current="current = $event"
  >
    <WTabsItem
      name="profile"
      title="Profile"
      :icon="markRaw(IconUser)"
    >
      <p>Name, avatar and contact details.</p>
    </WTabsItem>

    <WTabsItem
      name="security"
      title="Security"
      :icon="markRaw(IconLock)"
    >
      <p>Password, two-factor authentication and active sessions.</p>
      <p>Tabs keep the height of the tallest one opened so far, so the page below doesn't jump.</p>
    </WTabsItem>

    <WTabsItem
      name="notifications"
      title="Notifications"
      :icon="markRaw(IconAlarm)"
      :count="3"
    >
      <p>Three unread notifications.</p>
    </WTabsItem>

    <WTabsItem
      name="billing"
      title="Billing"
      disabled
    >
      <p>Not available on the free plan.</p>
    </WTabsItem>
  </WTabs>

  <p class="text-description mt-4 text-sm">
    Current tab: {{ current }}
  </p>
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'

import IconAlarm from 'eco-vue-js/dist/assets/icons/IconAlarm'
import IconLock from 'eco-vue-js/dist/assets/icons/IconLock'
import IconUser from 'eco-vue-js/dist/assets/icons/IconUser'

const current = ref('security')
</script>
```

Switching slides the content in from the side of the new tab, and the content area keeps the height of the tallest tab opened so far, so what's below it doesn't jump — `disableMinHeight` turns that off, `lessTransitions` fades instead of sliding.

The slide moves content its full width plus `--inner-margin` past the edge of the tabs, and WTabs doesn't clip it: the container decides where it shows. Spanning the page, the content slides in from the screen edge. Inside a card, a modal or a column, give the container `overflow-x-clip` — unlike `overflow-hidden`, it keeps sticky elements inside working. A header wider than its space scrolls sideways and keeps the active tab in view.

`update:current` and `update:current-index` emit the active tab, and `update:current-title` its title — for putting it in a page header when the tabs' own header is hidden with `noHeader`. To switch from code, call `updateCurrent(name)` or `updateIndex(index)` on a template ref. The first `update:current` comes during setup, so when the parent shows the current tab, seed it and pass it as `initTab`, as the demo does — otherwise a server-rendered page shows a different value than the first client render.

## Tabs as routes

Give each `WTabsItem` a `to`, and the route opens the tab: the one whose location has the current route's path, whatever the query and hash. The tab buttons become links that replace the history entry, so Back leaves the page instead of stepping through tabs, and they open in a new browser tab on a middle click. Anything else that links to a tab's location — a summary card above the tabs, say, with filters in the query — switches to it, and `updateCurrent` navigates. `initTab` is only used when no tab matches the route.

```vue
<WTabs>
  <WTabsItem name="findings" :to="{name: 'asset', params: {assetId, tab: 'findings'}}" />
  <WTabsItem name="settings" :to="{name: 'asset', params: {assetId, tab: 'settings'}}" />
</WTabs>
```

## Closable and added tabs

A tab with a `close` listener gets a close button. Children that aren't `WTabsItem` render in the header after the tab buttons, which is where an add button goes; `switchToNew` opens a tab as soon as it is added. When the active tab is removed, the one before it opens.

```vue
<template>
  <WTabs switch-to-new>
    <WTabsItem
      v-for="tab in tabs"
      :key="tab.id"
      :name="String(tab.id)"
      :title="tab.title"
      v-bind="tabs.length > 1 ? {onClose: () => remove(tab.id)} : {}"
    >
      <p>Contents of {{ tab.title }}.</p>
    </WTabsItem>

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      class="ml-2 self-center"
      @click="add"
    >
      <IconAdd class="square-4" />
    </WButton>
  </WTabs>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'

let nextId = 3

const tabs = ref([
  {id: 1, title: 'Query 1'},
  {id: 2, title: 'Query 2'},
])

const add = () => {
  tabs.value.push({id: nextId, title: `Query ${ nextId }`})
  nextId++
}

const remove = (id: number) => {
  tabs.value = tabs.value.filter(tab => tab.id !== id)
}
</script>
```

## Side layout

`side` puts the tab buttons in a column to the left of the content, `w-tabs-side-width-*` sets the column's maximum width. On phones the column and the content become two full-width screens side by side, and picking a tab scrolls to its content.

```vue
<template>
  <WTabs
    side
    class="w-tabs-side-width-48"
  >
    <WTabsItem
      name="general"
      title="General"
      :icon="markRaw(IconSettings)"
    >
      <p>Workspace name, language and time zone.</p>
    </WTabsItem>

    <WTabsItem
      name="members"
      title="Members"
      :icon="markRaw(IconUser)"
      :count="12"
    >
      <p>Twelve members, two of them admins.</p>
    </WTabsItem>

    <WTabsItem
      name="integrations"
      title="Integrations"
      :icon="markRaw(IconLink)"
    >
      <p>Connected services and API tokens.</p>
    </WTabsItem>
  </WTabs>
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'

import IconLink from 'eco-vue-js/dist/assets/icons/IconLink'
import IconSettings from 'eco-vue-js/dist/assets/icons/IconSettings'
import IconUser from 'eco-vue-js/dist/assets/icons/IconUser'
</script>
```

`WButtonTab` is the tab button on its own, for a button among the tab buttons that isn't a tab — such as "New chat" at the top of a side column of chats. With `side` it lines up with the side column's buttons; `title`, `icon` and `count` show as on a tab, and it emits `click`.

`WTabsColumns` shows its `WTabsItem` items as tabs on phones and as columns side by side from `sm` up, e.g. for the two halves of a form in a modal.

## Tabs in forms

An item's `hasError`, `hasChanges` and `hasValue` mark its button — `statusIcon` shows them as icons, `showHasValue` marks tabs with a value. When a tab gets an error while another is open, the tabs switch to it; `noSwitchOnInvalid` turns that off. Inside a Uniform form the tab items pick these states up from their fields on their own.

`stepper` turns the tabs into steps: the tabs after the first one with `hasValue` set to `false` are disabled, and `next()`, `previous()` and `jump(name)` on a template ref move between steps. Before `next()` and `jump(name)` leave a step, `validate` on its item runs, then the Uniform fields inside it are checked: invalid fields show their errors, a warning lists them, and the step stays open. `update:progress`, `update:first` and `update:last` emit where the stepper is, for the buttons around it.

`stepperControls` lets the stepper bring those buttons itself: Back, or on the first step in an overlay Close — Cancel once something is changed — and Next, or the submit on the last, named by `submitText`. `submitting` shows a spinner in it while a submit on `submit` runs, and `disabledNext` disables it. The texts come from `setTexts` ([Getting started](/guide/getting-started#texts)). The submit checks the last step and submits the Uniform form with `api-method` around it, or emits `submit`. In an overlay frame, or in a WModalWrapper on a page, the step's title, a progress line and the buttons go to the frame's title, subtitle and actions — the form's own title, if it has one, stays instead of the step's. A frame shows one stepper: the first one to mount takes it, and another one, such as a stepper inside a step, keeps its progress and buttons in itself.

## API

### WTabs

```ts
import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `customSlots` | `VNode[]` | — | Tab items rendered instead of the `default` slot. |
| `lessTransitions` | `boolean` | — | Fades between tabs instead of sliding. |
| `initTab` | `string` | — | Name of the tab opened first. |
| `initTabIndex` | `number` | — | Index of the tab opened first, when `initTab` is not set. |
| `side` | `boolean` | — | Puts the tab buttons in a column beside the content. On small screens the buttons and the content become two swipeable screens, and picking a tab scrolls to its content. |
| `disableMinHeight` | `boolean` | — | Lets the content shrink to the current tab's height. By default it keeps the height of the tallest tab shown so far. |
| `noHeader` | `boolean` | — | Hides the tab buttons. Switch tabs through the exposed methods. |
| `headerClass` | `string` | — | Classes for the row of tab buttons. |
| `switchToNew` | `boolean` | — | Switches to a tab when it is added. |
| `stepper` | `boolean` | — | Numbers the tab titles and disables every tab after the first one with `hasValue` false. The exposed `next` and `jump` check the Uniform fields of the tab they leave and stay on it if one is invalid. Enables `update:progress`, `update:first` and `update:last`. |
| `stepperControls` | `boolean` | — | With `stepper`, brings its own controls: the open step's title, a progress line, and Back, Next and submit buttons — Close on the first step in an overlay. In a frame, such as a modal or a page WModalWrapper, they go to its title, subtitle and actions, under a title of the form's own if there is one; the first stepper in the frame takes it. The submit checks the last step and submits the enclosing form with `api-method`, or emits `submit`. |
| `submitText` | `string` | — | Text of the submit button on the last step with `stepperControls`. Defaults to the `submit` text of `setTexts`. |
| `submitting` | `boolean` | — | With `stepperControls`, shows a spinner in the Next or submit button and disables Back and Close, such as while a submit on `submit` runs. A form with `api-method` around the stepper does it on its own. |
| `disabledNext` | `boolean` | — | With `stepperControls`, disables the Next or submit button, such as until something is picked on the step. |
| `showHasValue` | `boolean` | — | Colors the titles of tabs that have a value. |
| `noSwitchOnInvalid` | `boolean` | — | Stays on the current tab when another one gets an error. By default the first tab with an error is opened. |
| `wrap` | `boolean` | — | Wraps the tab buttons onto new lines instead of scrolling sideways. |
| `divider` | `boolean` | — | Draws a line under the row of tab buttons, which the open tab's underline covers. |
| `statusIcon` | `boolean` | — | Shows a value and error status icon next to each title. |
| `flat` | `boolean` | — | Renders all tabs one after another, each under its title, without the buttons. |
| `indicator` | `boolean` | — | Shows a large status circle on each tab button — error, has value or empty. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:current` | `(value: string)` | Name of the open tab. Also emitted on mount. |
| `update:current-index` | `(value: number)` | Index of the open tab. Also emitted on mount. |
| `update:has-changes` | `(value: boolean)` | Whether any tab has unsaved changes. |
| `update:current-title` | `(value: string \| undefined)` | Title of the open tab, also when the title itself changes. |
| `update:tabs-length` | `(value: number)` | Number of tabs. Also emitted on mount. |
| `update:progress` | `(value: number)` | With `stepper`, the share of steps reached, in percent. |
| `update:first` | `(value: boolean)` | With `stepper`, whether the first tab is open. |
| `update:last` | `(value: boolean)` | With `stepper`, whether the last tab is open. |
| `submit` | — | With `stepperControls`, the submit button was clicked on the last step and the step is valid. Not emitted inside a form with `api-method`, which is submitted instead. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | WTabsItem elements. Anything else is rendered among the tab buttons. |

### WTabsItem

```ts
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Title of the tab button. The `title` slot replaces it. |
| `name` | `string` | **required** | Unique key of the tab, used by `initTab`, `update:current` and the exposed methods. |
| `icon` | `SVGComponent` | — | Icon before the title. |
| `disabled` | `boolean` | — | Disables the tab button. |
| `removable` | `boolean` | — | Unmounts the content while the tab is not open, instead of hiding it. |
| `init` | `boolean` | — | Opens this tab first, when WTabs has no `initTab` or `initTabIndex`. |
| `hasValue` | `boolean \| null` | — | Marks the tab as filled in. By default it is read from the forms inside the tab. |
| `hasError` | `boolean` | — | Marks the tab as invalid. By default it is read from the forms inside the tab. |
| `hasChanges` | `boolean` | — | Shows the unsaved changes dot. By default it is read from the forms inside the tab. |
| `validate` | `(() => string \| undefined)` | — | Checks the tab before the exposed `next` and `jump` leave it. A returned error message is shown as a warning and the tab stays open. |
| `requireSave` | `boolean` | — | Submits the enclosing stepper form before moving forward past this tab, and stays on it if the submit fails. |
| `count` | `number` | — | Number shown in a badge after the title, tinted while the tab is open. |
| `to` | `RouteLocationRaw` | — | Router location of the tab. The tab button becomes a link that replaces the history entry. While any tab has one, the route decides the open tab — the one whose location has the current route's path, whatever the query and hash — and the exposed methods navigate to the tab instead of opening it. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close` | — | The close button was clicked. Listening to it adds the button to the tab. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content of the tab. |
| `title` | `StateScope` | Replaces the content of the tab button. |
| `suffix` | `StateScope` | Content after the title, inside the tab button. |
| `right` | `StateScope` | Content after the tab button. |

### WButtonTab

```ts
import WButtonTab from 'eco-vue-js/dist/components/Button/WButtonTab.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | — | Marks the button as the open tab: primary text and an underline. |
| `hasError` | `boolean` | — | Colors the button red, over the other states. |
| `hasValue` | `boolean` | — | Marks the tab as filled in, for `showHasValue`, `statusIcon` and `indicator`. |
| `hasChanges` | `boolean` | — | Shows the unsaved changes dot. |
| `disabled` | `boolean` | — | Grays the button out and ignores clicks. |
| `icon` | `SVGComponent` | — | Icon before the title. |
| `title` | `string` | — | Text of the button. The `title` slot replaces it. |
| `indicator` | `boolean` | — | Shows a large status circle — error, has value or empty — before the title. |
| `side` | `boolean` | — | Aligns the title to the start, for a column of tab buttons. |
| `statusIcon` | `boolean` | — | Shows a value and error status icon after the title. |
| `showHasValue` | `boolean` | — | Colors the title green when `hasValue` is set and the tab isn't open. |
| `enableOverflow` | `boolean` | — | Scrolls a title that doesn't fit into view on hover. |
| `count` | `number` | — | Number shown in a badge after the title, tinted while the tab is open. |
| `to` | `RouteLocationRaw` | — | Router location — renders a link that replaces the current history entry, unless `disabled`. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The button was clicked, unless it is disabled. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | `{ hasChanges?: boolean \| undefined; hasError?: boolean \| undefined; hasValue?: boolean \| undefined; }` | Content of the button, replacing the title, icon, count and status icon. |
| `suffix` | `{ hasChanges?: boolean \| undefined; hasError?: boolean \| undefined; hasValue?: boolean \| undefined; }` | Content after the title, such as a close button. |

### WTabsColumns

```ts
import WTabsColumns from 'eco-vue-js/dist/components/Tabs/WTabsColumns.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | WTabsItem items: tabs on phones, and columns side by side from `sm` up. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/chip.md
description: >-
  WChip — a short label in a colored box, such as a tag or a status flag, with a
  skeleton state.
---

# Chip

`WChip` is a short label in a colored box, such as a tag on a card or the status of a row. The `text` prop is the label and `icon` puts an icon before it; the default slot replaces the label.

The color comes from `semanticType`. The classes behind each type are set once per app with `setSemanticTypeChipMap` from `eco-vue-js/dist/utils/SemanticType` — [WCounter](/components/counter) reads the same map. `soft` turns the box into a rounded pill with a tinted background and colored text, for a status that sits on its own rather than inside a dense row; its classes come from `setSemanticTypeChipSoftMap`. `skeleton` shows a placeholder the size of a chip, and a form or an area can set it for everything inside — see [Conventions](/guide/conventions).

```vue
<template>
  <div class="grid gap-6">
    <div class="flex flex-wrap items-center gap-2">
      <WChip
        v-for="type in semanticTypes"
        :key="type"
        :text="type"
        :semantic-type="type"
      />
    </div>

    <div class="flex flex-wrap items-center gap-2">
      <WChip
        v-for="type in semanticTypes"
        :key="type"
        :text="type"
        :semantic-type="type"
        soft
      />
    </div>

    <div class="flex flex-wrap items-center gap-2">
      <WChip
        text="Watered"
        :semantic-type="SemanticType.POSITIVE"
        :icon="IconCheck"
      />

      <WChip
        text="Watered"
        :semantic-type="SemanticType.POSITIVE"
        :icon="IconCheck"
        soft
      />

      <WChip
        text="Gardener"
        :skeleton="loading"
      />

      <WToggle
        v-model="loading"
        title="Loading"
        class="ml-4"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

import IconCheck from 'eco-vue-js/dist/assets/icons/IconCheck'

const semanticTypes = Object.values(SemanticType)

const loading = ref(false)
</script>
```

## API

### WChip

```ts
import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | Label of the chip. The default slot replaces it. |
| `semanticType` | `SemanticType` | `SemanticType.SECONDARY` | Color scheme of the chip. |
| `soft` | `boolean` | — | Renders a rounded pill with a tinted background and colored text instead of a filled box. |
| `icon` | `SVGComponent` | — | Icon shown before the label. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the chip. When unset, inherits the skeleton state provided by a parent. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content of the chip, replacing `text`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/counter.md
description: >-
  WCounter — a round badge with a number in compact notation, which shakes when
  the count changes.
---

# Counter

`WCounter` is a round badge with a number, usually pinned to the corner of a button or a nav item. Large numbers are shortened, 1234 to 1.2K. It shakes when the count changes and is at least `trigger` — 2 by default, so a single item doesn't draw attention.

It takes a `semanticType` for its color, from the same map as [WChip](/components/chip). The counter is sized in `em`, so a text size class sets its size. [WButtonAction](/components/actions-bar#action-buttons) and [WNavItem](/components/nav-bar) have a `counter` or `count` of their own.

```vue
<template>
  <div class="flex flex-wrap items-center gap-6">
    <span class="relative">
      Inbox

      <WCounter
        :count="count"
        :trigger="1"
        class="absolute -top-2 left-full text-xs"
      />
    </span>

    <WCounter
      :count="1234"
      :semantic-type="SemanticType.INFO"
      class="text-sm"
    />

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      @click="count++"
    >
      New message
    </WButton>

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      @click="count = 0"
    >
      Read all
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WCounter from 'eco-vue-js/dist/components/Counter/WCounter.vue'

const count = ref(3)
</script>
```

## API

### WCounter

```ts
import WCounter from 'eco-vue-js/dist/components/Counter/WCounter.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | **required** | Number shown, in compact notation — 1.2K for 1200. |
| `trigger` | `number` | `2` | Lowest count that makes the counter shake when it changes. |
| `semanticType` | `SemanticType` | `SemanticType.NEGATIVE` | Color scheme of the badge. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/expansion.md
description: >-
  WExpansion and WExpansionItem — content that expands and collapses with an
  animated height, and a toggle row with a title for accordions.
---

# Expansion

`WExpansion` expands and collapses its content with `isOpen`, animating its height. Collapsed content is kept alive, so a form inside keeps what was typed. `isShown` hides it at once instead, without the animation.

`WExpansionItem` adds a toggle row with a title and an arrow. It doesn't open itself: it emits `toggle` and takes `isOpen`, so the page decides — e.g. one item open at a time, as below. `hasFlag` puts a dot after the title. The row spans the content's inner margin (`--inner-margin`), like list rows.

```vue
<template>
  <div class="grid gap-8">
    <div class="rounded-xl border border-solid border-line-subtle [--inner-margin:1rem]">
      <WExpansionItem
        v-for="(item, index) in sections"
        :key="item.title"
        :title="item.title"
        :is-open="open === index"
        :has-flag="item.flag"
        @toggle="open = open === index ? null : index"
      >
        <p class="text-description px-4 pb-4">
          {{ item.text }}
        </p>
      </WExpansionItem>
    </div>

    <div class="grid gap-2">
      <WToggle
        v-model="details"
        title="Show details"
      />

      <WExpansion :is-open="details">
        <div class="grid grid-cols-[auto_1fr] gap-x-6 gap-y-1 rounded-xl bg-surface-muted p-4">
          <span class="text-description">Sown</span>
          <span>March 12</span>

          <span class="text-description">Sprouted</span>
          <span>March 20</span>
        </div>
      </WExpansion>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WExpansion from 'eco-vue-js/dist/components/Expansion/WExpansion.vue'
import WExpansionItem from 'eco-vue-js/dist/components/Expansion/WExpansionItem.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

const sections = [
  {title: 'When should I repot?', text: 'When roots grow out of the drainage holes — usually every year or two, in spring.'},
  {title: 'Which soil is best?', text: 'A light, well-draining mix: add bark for aroids and grit for succulents.'},
  {title: 'What changed this month?', text: 'The days are getting shorter, so move sun lovers closer to the window.', flag: true},
]

const open = ref<number | null>(0)
const details = ref(false)
</script>
```

## API

### WExpansion

```ts
import WExpansion from 'eco-vue-js/dist/components/Expansion/WExpansion.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | `true` | Expands the content, animating its height. Collapsed content stays alive, keeping its state. |
| `isShown` | `boolean` | `true` | Shows the content. `false` hides it at once, without the animation. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:visible` | `(value: boolean)` | `true` as the content starts to expand, `false` once it has collapsed. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content that expands and collapses. |

### WExpansionItem

```ts
import WExpansionItem from 'eco-vue-js/dist/components/Expansion/WExpansionItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | — | Expands the content. The item doesn't toggle itself: set it on `toggle`. |
| `title` | `string` | — | Text of the toggle row. |
| `icon` | `SVGComponent` | — | Icon before the title. |
| `hasFlag` | `boolean` | — | Shows a dot after the title, e.g. for new content inside. |
| `minTitle` | `boolean` | — | Smaller title text. |
| `toggleClass` | `string` | — | Class of the toggle row. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `toggle` | — | The toggle row was clicked, or Enter or Space was pressed on it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content that expands under the toggle row. The component's class goes on it. |
| `title` | — | An empty element that the toggle row renders as instead of a `div`, e.g. `<h3 />` for a heading. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/image-viewer.md
description: >-
  WImageViewer — an image URL as a thumbnail with its file name that opens the
  full image in a modal.
---

# Image viewer

`WImageViewer` shows an image URL as a thumbnail, under an optional `title`. Hovering it shows the file name, taken from the end of the URL, and a click opens the full image in a modal, which closes on Escape or a click outside. Without a `modelValue`, or with `skeleton`, it shows a placeholder of the same size.

The modal opens with the [modal manager](/components/modal), so the app needs its [global containers](/guide/getting-started#global-containers).

```vue
<template>
  <div class="flex flex-wrap gap-6">
    <WImageViewer
      :model-value="monstera"
      title="Photo"
    />

    <WImageViewer
      :model-value="monstera"
      title="Loading"
      skeleton
    />
  </div>
</template>

<script lang="ts" setup>
import WImageViewer from 'eco-vue-js/dist/components/ImageViewer/WImageViewer.vue'

import monstera from './images/monstera.svg?url&no-inline'
</script>
```

## API

### WImageViewer

```ts
import WImageViewer from 'eco-vue-js/dist/components/ImageViewer/WImageViewer.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `string` | — | URL of the image. Clicking the thumbnail opens it full size in a modal. Without it, a placeholder is shown. |
| `title` | `string` | — | Label above the thumbnail. |
| `skeleton` | `boolean` | — | Shows placeholders for the title and the thumbnail. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/info-card.md
description: >-
  WInfoCard and WInfoCardNegative — notes with an icon in the color of their
  semantic type, and a card for an error or an empty state.
---

# Info card

`WInfoCard` is a note with an icon, in the color of its `semanticType`: gray by default, with an info icon, or an exclamation mark for `WARNING` and `NEGATIVE`. `icon` sets another icon, `noIcon` hides it, and `noBg` drops the background for a note inside other content. The `top` and `bottom` slots go above and under the text, e.g. for actions. On phones the card spans the screen edge to edge.

`WInfoCardNegative` is a gray card with a warning icon, a `title` and a description, for an error or an empty state that explains what to do.

```vue
<template>
  <div class="grid gap-4">
    <WInfoCard>
      Plants are grouped by the bed they grow in. Open a bed to see its plants.
    </WInfoCard>

    <WInfoCard :semantic-type="SemanticType.WARNING">
      The moisture sensors haven't reported for 3 days — readings may be out of date.

      <template #bottom>
        <WButton
          :semantic-type="SemanticType.SECONDARY"
          class="mt-4"
        >
          Check now
        </WButton>
      </template>
    </WInfoCard>

    <WInfoCard
      :semantic-type="SemanticType.POSITIVE"
      :icon="markRaw(IconCheckCircle)"
    >
      All plants are watered.
    </WInfoCard>

    <WInfoCard
      :semantic-type="SemanticType.INFO"
      no-bg
    >
      Without a background, for a note inside other content.
    </WInfoCard>

    <WInfoCardNegative title="The greenhouse sensor can't be reached">
      Check its battery and that it is still in range of the Wi-Fi.
    </WInfoCardNegative>
  </div>
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WInfoCard from 'eco-vue-js/dist/components/InfoCard/WInfoCard.vue'
import WInfoCardNegative from 'eco-vue-js/dist/components/InfoCard/WInfoCardNegative.vue'

import IconCheckCircle from 'eco-vue-js/dist/assets/icons/IconCheckCircle'
</script>
```

## API

### WInfoCard

```ts
import WInfoCard from 'eco-vue-js/dist/components/InfoCard/WInfoCard.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `noBg` | `boolean` | — | Drops the colored background, leaving the icon and text. |
| `noIcon` | `boolean` | — | Hides the icon. |
| `icon` | `SVGComponent` | — | Icon before the text. Defaults to an info icon, or an exclamation mark for `WARNING` and `NEGATIVE`. |
| `semanticType` | `SemanticType` | — | Color scheme of the background and icon. Defaults to `SECONDARY`. |
| `iconClass` | `string` | — | Class to apply to icon |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Text of the card, next to the icon. |
| `top` | — | Content above the icon and text. |
| `bottom` | — | Content under the icon and text, such as actions. |

### WInfoCardNegative

```ts
import WInfoCardNegative from 'eco-vue-js/dist/components/InfoCard/WInfoCardNegative.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | **required** | Heading of the card, after a warning icon. |
| `semanticType` | `SemanticType` | — | Color of the icon. Defaults to `NEGATIVE`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Description under the title. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/number-formatter.md
description: >-
  WNumberFormatter — a number with thousands separators, a fraction as a
  percentage, or a compact number with the full value in a tooltip.
---

# Number formatter

`WNumberFormatter` shows a number with thousands separators and up to three decimals, or a fraction as a percentage with `percent` — 0.25 is 25%. `compact` shortens it, 12840 to 13K, with the full number in a tooltip; `noTouch` skips the tooltip on touch devices.

Without `tag` the number is plain text and the tooltip attaches to the parent element — so the parent's whole box is the hover target. With `tag`, the number gets its own element.

The formatters behind it are exported for use in code — see [Formatting](/utilities/formatting#numbers).

```vue
<template>
  <div class="grid max-w-sm grid-cols-[auto_1fr] gap-x-6 gap-y-2">
    <span class="text-description">Seeds sown</span>
    <WNumberFormatter
      :model-value="12840"
      tag="span"
    />

    <span class="text-description">Compact</span>
    <WNumberFormatter
      :model-value="12840"
      tag="span"
      compact
    />

    <span class="text-description">Sprouted</span>
    <WNumberFormatter
      :model-value="0.4375"
      tag="span"
      percent
    />

    <span class="text-description">Of the region</span>
    <WNumberFormatter
      :model-value="0.000125"
      tag="span"
      percent
      compact
    />
  </div>
</template>

<script lang="ts" setup>
import WNumberFormatter from 'eco-vue-js/dist/components/NumberFormatter/WNumberFormatter.vue'
</script>
```

## API

### WNumberFormatter

```ts
import WNumberFormatter from 'eco-vue-js/dist/components/NumberFormatter/WNumberFormatter.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `number` | **required** | Number to show. With `percent`, a fraction: 0.25 is 25%. |
| `percent` | `boolean` | — | Formats the number as a percentage. |
| `compact` | `boolean` | — | Formats the number in compact notation, 1.2K for 1234, with the full number in a tooltip. |
| `tag` | `string` | — | Element to wrap the number in. Without it the number is plain text, and the tooltip attaches to the parent element. |
| `noTouch` | `boolean` | — | Skips the tooltip on touch devices. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/page-error.md
description: >-
  WPageError — replaces a page whose query failed with the status, the server's
  message, Back and, when asking again may help, Retry.
---

# Page error

`WPageError` wraps a page that shows one item. While the query's `error` is set, the page is replaced with the status and the server's `detail`, and a Back button. When the server could not be reached or failed with a 5xx, it also offers Retry, which fetches again every failed query on screen.

Without a `detail` from the server, the message comes from the [texts](/utilities/helpers): `serverUnavailable`, `serverError` or `pageNotFound`. Set them with `setTexts` to translate them, along with `errorTitle`, `back` and `retry`.

```vue
<template>
  <div class="grid gap-4">
    <div class="flex flex-wrap gap-2">
      <WButton
        v-for="(item, key) in errors"
        :key="key"
        :semantic-type="SemanticType.SECONDARY"
        @click="error = item"
      >
        {{ key }}
      </WButton>
    </div>

    <WPageError :error="error">
      <div class="text-description py-24 text-center">
        The greenhouse page
      </div>
    </WPageError>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {ApiError, ApiErrorUnavailable} from 'eco-vue-js/dist/utils/api'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WPageError from 'eco-vue-js/dist/components/ErrorPage/WPageError.vue'

const request = new Request('https://example.com/api/greenhouses/7/')

const errors: Record<string, Error | null> = {
  Loaded: null,
  'Not found': new ApiError({data: {detail: 'No greenhouse matches the given query.'}, status: 404, request}),
  'Server down': new ApiErrorUnavailable({data: undefined, request}),
  'Server error': new ApiError({data: {}, status: 500, request}),
}

const error = ref<Error | null>(null)
</script>
```

## API

### WPageError

```ts
import WPageError from 'eco-vue-js/dist/components/ErrorPage/WPageError.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `error` | `Error \| null` | **required** | The error of the query the page shows, such as `query.error.value`. While it is set, the page is replaced with the error, its status and the server's `detail`; a failure that may pass also gets a Retry button. |
| `tag` | `keyof HTMLElementTagNameMap` | — | Element that wraps the page when there is no error. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | The page, shown while there is no error. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/progress.md
description: >-
  WProgress, WProgressStriped and WProgressBar — a thin line, a slim striped bar
  and a large bar with the percentage, for the progress of a task.
---

# Progress

Three bars for the progress of a task:

* `WProgress` — a thin line, from 0 to 100, e.g. under a modal's title for the steps of a stepper.
* `WProgressStriped` — a slim rounded bar, from 0 to 100, with a light sweeping the fill while in progress. A band sweeps the empty track at 0, and the full bar pulses at 100. It has no height of its own, so give it one, e.g. `h-1.5`.
* `WProgressBar` — a large bar with the percentage in it, from 0 to 1; the label changes color where the fill passes under it. `null` sweeps the empty bar and shows a spinner, for a task that hasn't reported its progress yet.

```vue
<template>
  <div class="grid max-w-md gap-6">
    <div class="flex gap-2">
      <WButton
        :semantic-type="SemanticType.SECONDARY"
        :disabled="running"
        @click="start"
      >
        Start
      </WButton>

      <WButton
        :semantic-type="SemanticType.SECONDARY"
        :disabled="running"
        @click="percent = 0"
      >
        Reset
      </WButton>
    </div>

    <WProgress :model-value="percent" />

    <WProgressStriped
      :model-value="percent"
      class="h-1.5"
    />

    <WProgressBar
      :model-value="waiting ? null : percent / 100"
      :semantic-type="SemanticType.PRIMARY"
    />
  </div>
</template>

<script lang="ts" setup>
import {onBeforeUnmount, ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WProgress from 'eco-vue-js/dist/components/Progress/WProgress.vue'
import WProgressBar from 'eco-vue-js/dist/components/Progress/WProgressBar.vue'
import WProgressStriped from 'eco-vue-js/dist/components/Progress/WProgressStriped.vue'

const percent = ref(0)
const running = ref(false)
const waiting = ref(false)

let timer: ReturnType<typeof setInterval> | undefined

// Waits a second before the task reports progress, then fills in steps.
const start = () => {
  percent.value = 0
  running.value = true
  waiting.value = true

  setTimeout(() => {
    waiting.value = false

    timer = setInterval(() => {
      percent.value = Math.min(100, percent.value + 10)

      if (percent.value === 100) {
        clearInterval(timer)
        running.value = false
      }
    }, 400)
  }, 1000)
}

onBeforeUnmount(() => clearInterval(timer))
</script>
```

## API

### WProgress

```ts
import WProgress from 'eco-vue-js/dist/components/Progress/WProgress.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `number` | **required** | Filled part, from 0 to 100. |

### WProgressStriped

```ts
import WProgressStriped from 'eco-vue-js/dist/components/Progress/WProgressStriped.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `number` | **required** | Filled part, from 0 to 100. At 0 a band sweeps the empty track, while waiting to start; at 100 the full bar pulses. |

### WProgressBar

```ts
import WProgressBar from 'eco-vue-js/dist/components/Progress/WProgressBar.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `number \| null` | **required** | Filled part, from 0 to 1, shown as a percentage. `null` sweeps the empty bar and shows a spinner, for progress not known yet. |
| `semanticType` | `SemanticType` | `SemanticType.INFO` | Color scheme of the fill. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/query-boundary.md
description: >-
  WQueryBoundary — stops the skeletons of a card whose query failed and shows
  why, with Retry when asking again may help.
---

# Query boundary

A card shows skeletons while its queries load. When one of them fails, the skeletons would shimmer forever. `WQueryBoundary` wraps the card and takes the queries it shows: once one fails without data, the skeletons stop and grey out under a short message, and the card keeps its size and layout.

The message is the server's short `detail`, or the `serverUnavailable` or `loadError` [text](/utilities/helpers). When the server could not be reached or failed with a 5xx, Retry fetches the failed queries again, and the skeletons shimmer while they load. A failure that will not pass, such as a 403, shows only the message.

A query that already has data keeps showing it when a later refetch fails.

With a [`WQueryStatus`](/components/query-status) in the app, a failure asking again may fix is told once for the whole page instead of on each card: the card only greys out its skeletons, so it is clear which card failed. A failure that will not pass, such as a 403, still shows its message on the card.

```vue
<template>
  <div class="grid max-w-sm gap-4">
    <div class="flex flex-wrap gap-2">
      <WButton
        v-for="(item, key) in errors"
        :key="key"
        :semantic-type="SemanticType.SECONDARY"
        @click="fail(item)"
      >
        {{ key }}
      </WButton>
    </div>

    <WQueryBoundary
      :queries="[query]"
      class="grid gap-2 rounded-xl border border-solid border-line-subtle p-4"
    >
      <div class="font-semibold">
        Harvest this week
      </div>

      <template v-if="query.data.value">
        <div
          v-for="item in query.data.value"
          :key="item"
        >
          {{ item }}
        </div>
      </template>

      <template v-else>
        <WSkeleton
          v-for="index in 3"
          :key="index"
        />
      </template>
    </WQueryBoundary>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {ApiError, ApiErrorUnavailable} from 'eco-vue-js/dist/utils/api'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WQueryBoundary from 'eco-vue-js/dist/components/QueryBoundary/WQueryBoundary.vue'
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

const request = new Request('https://example.com/api/harvest/')

const errors: Record<string, Error> = {
  'Server down': new ApiErrorUnavailable({data: undefined, request}),
  Forbidden: new ApiError({data: {detail: 'You cannot see the harvest.'}, status: 403, request}),
}

const query = {
  data: ref<string[] | undefined>(['Tomatoes, 12 kg', 'Basil, 3 bunches', 'Zucchini, 7']),
  error: ref<Error | null>(null),
  refetch: () => {
    query.error.value = null

    return new Promise<void>(resolve => setTimeout(() => {
      query.data.value = ['Tomatoes, 12 kg', 'Basil, 3 bunches', 'Zucchini, 7']
      resolve()
    }, 1500))
  },
}

const fail = (error: Error) => {
  query.data.value = undefined
  query.error.value = error
}
</script>
```

## API

### WQueryBoundary

```ts
import WQueryBoundary from 'eco-vue-js/dist/components/QueryBoundary/WQueryBoundary.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `queries` | `BoundaryQuery[]` | **required** | The queries the content shows, such as `[queryStats, queryItems]`. When one of them failed without data, its skeletons stop and grey out under a message, with Retry when asking again may help. With a `WQueryStatus` in the app, a failure asking again may fix is told there instead, and the content only greys out. |
| `tag` | `keyof HTMLElementTagNameMap` | — | Element that wraps the content. Inside a card that is a link or has its own layout, `class="contents"` keeps the card's layout, and the message centers on the nearest positioned ancestor. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | The content, with its own skeletons while the queries load. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/query-status.md
description: >-
  WQueryStatus — one message for the whole app when queries on screen fail to
  load, with Retry, and frozen skeletons while the server is down.
---

# Query status

`WQueryStatus` watches every query on screen. When one fails without data and asking again may help — the server could not be reached, or answered 5xx, 408 or 429 — a single message shows under the header with a Retry button that fetches every failed query again. Mount it once, next to the other [global containers](/guide/getting-started#global-containers):

```vue
<template>
  <RouterView />

  <WQueryStatus />
  <WNotify />
</template>

<script lang="ts" setup>
import WNotify from 'eco-vue-js/dist/components/Notify/WNotify.vue'
import WQueryStatus from 'eco-vue-js/dist/components/QueryStatus/WQueryStatus.vue'
</script>
```

While the server cannot be reached, every skeleton on the page stops and greys out, since none of them will load. Once [`watchServerRecovery`](/guide/data-layer) sees the server again, the failed queries are fetched again and the message goes away on its own.

A failure a component already shows stays out of the message: a list page with its error and Retry, or a [page error](/components/page-error). A [query boundary](/components/query-boundary) around a card greys out only that card's skeletons, and leaves the message to `WQueryStatus`. Errors that will not pass by asking again, such as 403 and 404, are never shown here.

The texts are `serverUnavailable`, `partialLoadError` and `retry` — see [Texts](/guide/getting-started#texts).

## API

### WQueryStatus

```ts
import WQueryStatus from 'eco-vue-js/dist/components/QueryStatus/WQueryStatus.vue'
```

#### Props

*No props.*

---

---
url: https://rsmple.github.io/eco-vue-js/components/skeleton.md
description: >-
  WSkeleton — a shimmering placeholder for content that is still loading, shaped
  with the w-skeleton-* utilities.
---

# Skeleton

`WSkeleton` is a shimmering placeholder for content that is still loading. It is one line of text tall and a random width between 40% and 80%, so a column of them doesn't look like a grid. Utilities from the kit's Tailwind base set its shape:

* `w-skeleton-w-*` and `w-skeleton-h-*` — width and height, e.g. `w-skeleton-h-12` for an avatar.
* `w-skeleton-rounded-*` — corner radius.
* `w-skeleton-static` — stops the shimmer, on the skeleton or any parent.

Controls, chips and list fields have a `skeleton` prop that renders their own skeleton. A form or an area can set it for everything inside at once — see [Conventions](/guide/conventions) and [Component states](/utilities/composables#component-states).

```vue
<template>
  <div class="grid max-w-md gap-4">
    <WToggle
      v-model="loading"
      title="Loading"
    />

    <div class="flex items-center gap-4 rounded-xl border border-solid border-line-subtle p-4">
      <WSkeleton
        v-if="loading"
        class="w-skeleton-w-12 w-skeleton-h-12 w-skeleton-rounded-full shrink-0"
      />

      <div
        v-else
        class="tone-primary surface-fill flex square-12 shrink-0 items-center justify-center rounded-full text-lg font-semibold"
      >
        CL
      </div>

      <div class="grid flex-1">
        <WSkeleton v-if="loading" />

        <span
          v-else
          class="font-semibold"
        >
          Carl Linnaeus
        </span>

        <WSkeleton v-if="loading" />

        <span
          v-else
          class="text-description"
        >
          Herb bed, greenhouse, orchard
        </span>
      </div>

      <WChip
        text="Gardener"
        :skeleton="loading"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

const loading = ref(true)
</script>
```

## API

### WSkeleton

```ts
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content inside the placeholder. With `w-skeleton-w-max` and hidden with `opacity-0`, it sizes the skeleton to the content it stands for. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/spinner.md
description: >-
  WSpinner — an indeterminate spinner in the current text color, sized with
  square-*.
---

# Spinner

`WSpinner` is an indeterminate spinner in the current text color. `square-*` sets its size, 20px by default. Buttons show one over their label while `loading`.

For a spinner among regular icons, such as in a menu item, use `IconSpinner` — the same drawing as an icon component.

```vue
<template>
  <div class="flex flex-wrap items-center gap-6">
    <WSpinner />

    <WSpinner class="tone-primary square-8 text-tone" />

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      :loading="saving"
      @click="save"
    >
      Save
    </WButton>

    <span class="text-description flex items-center gap-2 text-sm">
      <WSpinner class="square-4" />
      Syncing the greenhouse sensors
    </span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WSpinner from 'eco-vue-js/dist/components/Spinner/WSpinner.vue'

const saving = ref(false)

const save = () => {
  saving.value = true
  setTimeout(() => saving.value = false, 1500)
}
</script>
```

## API

### WSpinner

```ts
import WSpinner from 'eco-vue-js/dist/components/Spinner/WSpinner.vue'
```

#### Props

*No props.*

---

---
url: https://rsmple.github.io/eco-vue-js/components/status-icon.md
description: >-
  WStatusIcon — a check, an exclamation mark or a dimmed slash for whether
  something is filled in or has errors.
---

# Status icon

`WStatusIcon` shows whether something is filled in: a check with `hasValue`, an exclamation mark with `hasError`, and a dimmed slash with neither. [WTabs](/components/tabs) use it with `statusIcon` to mark the tabs that are done or have errors. Size it with `square-*`.

```vue
<template>
  <div class="flex flex-wrap items-center gap-4 [&_svg]:square-5">
    <span class="flex items-center gap-2"><WStatusIcon /> Not set</span>
    <span class="flex items-center gap-2"><WStatusIcon has-value /> Done</span>
    <span class="flex items-center gap-2"><WStatusIcon has-error /> Failed</span>
  </div>
</template>

<script lang="ts" setup>
import WStatusIcon from 'eco-vue-js/dist/components/Status/WStatusIcon.vue'
</script>
```

## API

### WStatusIcon

```ts
import WStatusIcon from 'eco-vue-js/dist/components/Status/WStatusIcon.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hasValue` | `boolean` | — | Shows a green check. |
| `hasError` | `boolean` | — | Shows a red exclamation mark, over `hasValue`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/text-overflow.md
description: >-
  WTextOverflow — one line cut at its width that scrolls the rest into view on
  hover, of itself or of a group/overflow parent.
---

# Text overflow

`WTextOverflow` shows one line cut at its width, and scrolls the rest into view on hover — or on hover of a parent with the `group/overflow` class, such as a list row or a card. Text that fits doesn't move.

The content has to stay on one line, so give it `whitespace-nowrap`.

```vue
<template>
  <div class="grid max-w-60 gap-4">
    <div class="grid gap-1">
      <span class="text-description text-sm">Hover the name:</span>

      <WTextOverflow>
        <span class="whitespace-nowrap font-semibold">Monstera deliciosa 'Thai Constellation', half-moon variegation</span>
      </WTextOverflow>
    </div>

    <div class="group/overflow grid gap-1 rounded-xl border border-solid border-line-subtle p-3 hover:bg-surface-muted">
      <span class="text-description text-sm">Hover the card:</span>

      <WTextOverflow>
        <span class="whitespace-nowrap">North greenhouse, bench 4, row 2 — next to the fig cuttings</span>
      </WTextOverflow>
    </div>
  </div>
</template>

<script lang="ts" setup>
import WTextOverflow from 'eco-vue-js/dist/components/TextOverflow/WTextOverflow.vue'
</script>
```

## API

### WTextOverflow

```ts
import WTextOverflow from 'eco-vue-js/dist/components/TextOverflow/WTextOverflow.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | One line of text. When it is wider than the component, hovering scrolls it to its end. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/charts.md
description: >-
  WChartLinear and WChartLine for values over time, with bands, areas, gradients
  and tooltips, and WChartHeatmap for a year of daily values.
---

# Charts

Small SVG charts of values over time. They are drawn in the current text color, so a text color class on the chart or the line sets its color.

## Lines

`WChartLinear` is the frame: a time axis over `xDomain`, a value axis on the left or `yRight`, and the plot between them. It fills its parent's height unless `height` is set, and follows its width. Its default slot gets the scales and sizes — bind them to each `WChartLine` with `v-bind="scope"`, or use `scaleX` and `scaleY` to draw your own marks, such as a threshold line.

`WChartLine` draws one line from `data`, newest point first, picking the time and value by `xKey` and `yKey`. The line runs on flat from its first and last points to the edges of the chart. The value axis fits all the lines in the chart, from 0 or with `calcMin` from their lowest value.

* `yKeyMin` and `yKeyMax` draw a faint band around the line, e.g. for a range or a confidence interval. `hasArea` fills the area under the line instead.
* `strokeStyle` and `strokeWidth` set the line; the `gradient` slot colors it by value, with `stop` elements placed with `scaleYPercent`.
* The `tooltip` slot adds a tooltip for the point nearest the pointer, with its data and the points before and after it.

```vue
<template>
  <div class="grid gap-2">
    <div class="flex gap-4 text-sm">
      <span class="tone-primary text-tone">— Seedlings</span>
      <span class="tone-positive text-tone">- - Planted out</span>
    </div>

    <WChartLinear
      :x-domain="[from, today]"
      :height="200"
      :y-format="value => numberCompactFormatter.format(value)"
      y-right
    >
      <template #default="scope">
        <WChartLine
          v-bind="scope"
          :data="seedlings"
          x-key="date"
          y-key="value"
          y-key-min="min"
          y-key-max="max"
          class="tone-primary text-tone"
        >
          <template #tooltip="{d, prev}">
            <div class="grid text-sm">
              <span class="text-description">{{ dateFormat(new Date(d.date)) }}</span>
              <span class="font-semibold">{{ d.value }} seedlings</span>
              <span
                v-if="prev"
                class="text-description"
              >{{ d.value - prev.value >= 0 ? '+' : '' }}{{ d.value - prev.value }} since the day before</span>
            </div>
          </template>
        </WChartLine>

        <WChartLine
          v-bind="scope"
          :data="plantedOut"
          x-key="date"
          y-key="value"
          stroke-style="dashed-small"
          has-area
          class="tone-positive text-tone"
        />
      </template>
    </WChartLinear>
  </div>
</template>

<script lang="ts" setup>
import {addDay, dateFormat, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'
import {numberCompactFormatter} from 'eco-vue-js/dist/utils/utils'

import WChartLine from 'eco-vue-js/dist/components/Chart/WChartLine.vue'
import WChartLinear from 'eco-vue-js/dist/components/Chart/WChartLinear.vue'

const today = +getStartOfDay()
const from = +addDay(getStartOfDay(), -29)

// Points go newest first, one a day for the last 30 days.
const seedlings = Array.from({length: 30}, (_, index) => {
  const value = Math.round(120 + 30 * Math.sin(index / 4) - index)
  return {date: +addDay(getStartOfDay(), -index), value, min: value - 12, max: value + 12}
})

const plantedOut = Array.from({length: 30}, (_, index) => ({date: +addDay(getStartOfDay(), -index), value: Math.max(0, 60 - 2 * index + (index % 5) * 3)}))
</script>
```

## Heatmap

`WChartHeatmap` shows a value per day over the last year as a grid of weeks, in five shades of the current color: `text-tone-fill` gives it a tone's fill color, as bright as its buttons. The legend's steps are round numbers up to the highest value. The grid scrolls to today; the `tooltip` slot describes a day.

```vue
<template>
  <WChartHeatmap
    :data="waterings"
    x-key="date"
    y-key="count"
    title="Waterings in the last year"
    class="tone-primary text-tone-fill"
  >
    <template #tooltip="{d}">
      {{ d.count }} waterings on {{ dateFormat(new Date(d.date)) }}
    </template>
  </WChartHeatmap>
</template>

<script lang="ts" setup>
import {addDay, dateFormat, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import WChartHeatmap from 'eco-vue-js/dist/components/Chart/WChartHeatmap.vue'

// A made-up count for every weekday of the last year, more on some weeks than others.
const waterings = Array.from({length: 365}, (_, index) => {
  const date = addDay(getStartOfDay(), -index)
  const weekday = date.getDay() !== 0 && date.getDay() !== 6

  return {date: +date, count: weekday ? (index * 7) % 23 + (Math.floor(index / 30) % 3) * 5 : 0}
}).filter(item => item.count > 0)
</script>
```

## API

### WChartLinear

```ts
import WChartLinear from 'eco-vue-js/dist/components/Chart/WChartLinear.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `xDomain` | `[number, number]` | **required** | Time range of the x axis, as `[from, to]` timestamps in ms. The axis labels are dates, and "Today", in the locale set with `setLocale`. |
| `yDomainGetter` | `((extent: [number, number]) => [number, number])` | — | Range of the y axis from the range of all the lines' values. By default it is rounded out to tens or hundreds and starts at 0 or below. |
| `height` | `number` | `0` | Height of the chart in px. By default it fills the height of its parent. |
| `xHidden` | `boolean` | — | Hides the x axis. |
| `yHidden` | `boolean` | — | Hides the y axis. |
| `yRight` | `boolean` | — | Puts the y axis on the right. |
| `yFormat` | `((value: number) => string)` | — | Labels of the y axis. |
| `top` | `number` | `16` | Space above the plot in px, for the axis labels. |
| `bottom` | `number` | `16` | Space under the plot in px. |
| `left` | `number` | `3` | Space left of the plot in px. |
| `right` | `number` | `3` | Space right of the plot in px. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the chart. When unset, inherits the skeleton state provided by a parent. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `ChartContext` | SVG content of the chart, such as WChartLine lines — bind the scope to each one. Gets the scales and sizes for drawing your own marks. |

### WChartLine

```ts
import WChartLine from 'eco-vue-js/dist/components/Chart/WChartLine.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `Data[]` | **required** | Points of the line, newest first. The line runs on flat to both edges of the chart. |
| `xKey` | `keyof Data` | **required** | Key of the timestamp of a point, in ms. |
| `yKey` | `keyof Data` | **required** | Key of the value of a point. |
| `yKeyMin` | `keyof Data` | — | Key of the lower bound of a point, for a band around the line with `yKeyMax`. |
| `yKeyMax` | `keyof Data` | — | Key of the upper bound of a point, for a band around the line with `yKeyMin`. |
| `strokeStyle` | `"solid" \| "dashed" \| "dashed-small" \| "dotted"` | — | Style of the line. |
| `strokeWidth` | `number` | — | Width of the line in px. Defaults to 2. |
| `hasArea` | `boolean` | — | Fills the area under the line with a fading color. |
| `pointRadius` | `number` | — | Radius in px of the point marked under the tooltip. Defaults to 3. |
| `emptyStub` | `string` | — | Text shown when there are no points in range, instead of the `noData` text set with `setTexts`. The `empty` slot replaces it. |
| `calcMin` | `boolean` | — | Lets the y axis start above 0, at the lowest value. By default it includes 0. |
| `scaleX` | `(value: number) => number` | **required** | Converts a timestamp to an x position in px. |
| `scaleY` | `(value: number) => number` | **required** | Converts a value to a y position in px. |
| `svgWidth` | `number` | **required** | Width of the chart in px. |
| `svgHeight` | `number` | **required** | Height of the chart in px. |
| `top` | `number` | **required** | Space above the plot in px. |
| `bottom` | `number` | **required** | Space under the plot in px. |
| `left` | `number` | **required** | Space left of the plot in px. |
| `right` | `number` | **required** | Space right of the plot in px. |
| `xExtent` | `[number, number]` | **required** | Time range of the x axis, as `[from, to]` timestamps in ms. |
| `onUpdateDomain` | `(lineId: string, yExtent: [number, number]) => void` | **required** | Reports the range of a line's values, for the chart to fit the y axis to all its lines. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `tooltip` | `{ d: Data; x: number; y: number; index: number \| null; prev: Data \| undefined; next: Data \| undefined; }` | Content of the tooltip for the point nearest the pointer, with its data, the older point's data as `prev` and the newer one's as `next`, and its position. The line only has a tooltip with this slot. |
| `gradient` | `{ scaleY: (value: number) => number; scaleYPercent: (value: number) => number; topPercent: number; bottomPercent: number; }` | `stop` elements of a vertical gradient for the line's color, e.g. green below a threshold and red above it. `scaleYPercent` places a value on it. By default the line is the current text color. |
| `empty` | — | Content shown when there are no points in range, replacing `emptyStub`. |

### WChartHeatmap

```ts
import WChartHeatmap from 'eco-vue-js/dist/components/Chart/WChartHeatmap.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `Data[]` | **required** | Values by day, over the last year. |
| `xKey` | `keyof PickByType<Required<Data>, number, false>` | **required** | Key of the timestamp of a day, in ms. |
| `yKey` | `keyof PickByType<Required<Data>, number, false>` | **required** | Key of the day's value, which sets its shade. |
| `title` | `string` | — | Heading above the grid, next to the legend. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the chart. When unset, inherits the skeleton state provided by a parent. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `tooltip` | `{ d: Data; index: number; }` | Tooltip of a day with data, with the day's data and its index in `data`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/drag-container.md
description: >-
  WDragContainer — lets the user reorder a list by dragging its items by a
  handle, emitting the new order once an item is dropped.
---

# Drag container

`WDragContainer` lets the user reorder `list` by dragging its items. It doesn't render the items itself: the default slot renders each one, and binds `container` — the drag attributes and its place in the order — to the item's root. An item becomes draggable when `initDrag` is called, usually on mousedown of a drag handle, so that text in the item can still be selected. The items move as the dragged one passes over them; `update:list` emits the new order once it is dropped. Items are tracked by their position, so `list` may hold equal values — the same string twice, or the same object.

The `w-drag-item-overlay-*` utility sets the color laid over the item being dragged.

```vue
<template>
  <div class="grid max-w-md gap-4">
    <WDragContainer
      :list="steps"
      @update:list="steps = $event"
    >
      <template #default="{item, index, container, initDrag}">
        <div
          v-bind="container"
          class="bg-surface mb-2 flex items-center gap-3 rounded-xl border border-solid border-line-subtle p-3"
        >
          <IconDrag
            class="text-description square-5 cursor-grab"
            @mousedown="initDrag"
          />

          <span class="text-description w-4">{{ index + 1 }}</span>

          <span>{{ item }}</span>
        </div>
      </template>
    </WDragContainer>

    <span class="text-description text-sm">Saved order: {{ steps.join(' → ') }}</span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WDragContainer from 'eco-vue-js/dist/components/DragContainer/WDragContainer.vue'

import IconDrag from 'eco-vue-js/dist/assets/icons/IconDrag'

const steps = ref(['Sow', 'Prick out', 'Pot on', 'Harden off', 'Plant out'])
</script>
```

## API

### WDragContainer

```ts
import WDragContainer from 'eco-vue-js/dist/components/DragContainer/WDragContainer.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `list` | `Data[]` | **required** | Items in their saved order. |
| `disabled` | `boolean` | — | Stops dragging and dims the items. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:list` | `(Data[])` | The items in their new order, once an item is dropped. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ item: Data; index: number; last: boolean; orderedList: Data[]; dragging: boolean; initDrag: () => void; container: HTMLAttributes; }` | An item. Bind `container` to its root element, and call `initDrag` on mousedown of its drag handle — or of the whole item — to make it draggable. `index` and `last` follow the order while dragging, and `dragging` is true while an item of this list is dragged. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/infinite-list.md
description: >-
  WInfiniteList — items of a paginated query loaded page by page as you scroll,
  with a sticky header, skeletons while loading and scrolling inside any
  element.
---

# Infinite list

`WInfiniteList` loads a paginated query page by page as it is scrolled, and renders each item with its default slot. It lays out nothing itself, so it fits any item layout — [WList](/components/list) and the async selects are built on it. You give it:

* `useQueryFn` and `queryParams` — a paginated query. Each page is its own query with `page` and `size` added to the params.
* `pageLength` — the page size the query returns.
* A default slot for an item. While a page loads, the slot renders placeholders with `skeleton` set.

A change of `queryParams`, such as a new search, resets the list to the first page. Only a few pages stay rendered (`maxPages`). Scrolling further drops pages at the other end and keeps their height, so the scrollbar stays true to the whole list.

```vue
<template>
  <WInfiniteListScrollingElement class="h-96 overflow-y-auto overscroll-contain rounded-xl border border-solid border-line-subtle">
    <WInfiniteList
      :use-query-fn="plantModelApi.paginated.use"
      :query-params="{search}"
      :page-length="10"
      page-class="grid"
      empty-stub="No plants found"
      min-height-only
      @update:count="count = $event"
    >
      <template #header>
        <div class="flex items-center gap-4 px-4 pb-3">
          <WInput
            v-model="search"
            placeholder="Search by name or species"
            class="flex-1"
            no-margin
          />

          <span class="text-description text-sm whitespace-nowrap">
            {{ count }} plants
          </span>
        </div>
      </template>

      <template #default="{item, skeleton, position}">
        <div class="flex items-baseline gap-3 border-t border-solid border-line-subtle px-4 py-2">
          <span class="text-description w-6 text-right text-sm">
            {{ position + 1 }}
          </span>

          <WSkeleton v-if="skeleton" />

          <span v-else>
            {{ item.name }} <span class="text-description italic">— {{ item.species }}</span>
          </span>
        </div>
      </template>
    </WInfiniteList>
  </WInfiniteListScrollingElement>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WInfiniteList from 'eco-vue-js/dist/components/InfiniteList/WInfiniteList.vue'
import WInfiniteListScrollingElement from 'eco-vue-js/dist/components/InfiniteList/WInfiniteListScrollingElement.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

// The `use` of any paginated query — here the plant model from the list recipe, 10 plants a page.
import {plantModelApi} from '../../../../../docs/examples/recipes/plant-list/api/Plant'

const search = ref<string>()
const count = ref(0)
</script>
```

## Scrolling inside an element

By default the list loads as the page scrolls. `WInfiniteListScrollingElement` makes an element the scroll container instead, for the lists and sticky headers inside it — give it a height and `overflow-y-auto`, as above. Modals are scroll containers of their own already.

## Sticky header

The `header` slot sticks above the items while they scroll: under the app header on a page, and at the top of a modal or scroll container. It gets `refetchAll`, `isFetching` and `isRefetchingAll` for a toolbar with a refresh button. `updateHeader` re-measures it right away, when its content changes in a way the list has to know about at once.

`WInfiniteListWrapper` is the same sticky header for any content, without a list:

```vue
<WInfiniteListWrapper>
  <template #header>
    <PageToolbar />
  </template>

  <ReportSections />
</WInfiniteListWrapper>
```

## Items

Besides `item` and `skeleton`, the default slot gets:

* `setter` — writes a changed item to the query cache, which updates it in every loaded page and every other query of the same model. Called with nothing, it removes the item.
* `refetch` — refetches this page and the pages after it, e.g. after an item moved.
* `previous` and `next` — the neighbouring items, across page borders; `first` and `last` for the ends of the list.
* `position` — the item's index in the whole list; `page` and `index` — its page and index in the page.

## Pages

A template ref gives `refetchAll`, `resetPage(page)` to start over from a page, and `goto(page, index)` to scroll to an item. A page that isn't rendered is rendered in its place, with the pages around it; before the list knows the page count, it starts over from the page instead.

`update:page` reports the page reached by scrolling. Keeping it in the URL and passing it back as `page` in `queryParams` opens the list at that page after a reload — the pages before it load when scrolling up.

## Long lists

However long the query, the list keeps only `maxPages` pages in the DOM. Pages scrolled past are dropped and leave a space of their height, and their queries stay cached, so scrolling back renders them again at once. Spacers above and below the rendered pages stand in for the rest, sized by the number of pages times the average height of those rendered, so the scrollbar covers the whole list from the first page on. Browsers cap the height of an element, so for a list too long to fit under 15M px — about a million rows — the spacers shrink to fit, and the scrollbar moves through the list faster than the rows scroll.

The demo below pages through 10,000 events, 50 at a time. The counter shows how many rows are in the DOM while scrolling. "Go to row" calls `goto` with the row's page and its index in the page, and the pages around it load in place.

```vue
<template>
  <div
    ref="container"
    class="grid gap-3"
  >
    <div class="flex flex-wrap items-center gap-x-6 gap-y-2">
      <form
        class="flex items-center gap-2"
        @submit.prevent="jump"
      >
        <WInput
          v-model="row"
          type="number"
          :min="1"
          :max="EVENT_COUNT"
          placeholder="Row"
          class="w-28"
          no-margin
        />

        <WButton
          :semantic-type="SemanticType.SECONDARY"
          type="submit"
        >
          Go to row
        </WButton>
      </form>

      <span class="text-description text-sm tabular-nums">
        {{ rendered }} of {{ count.toLocaleString('en') }} rows rendered
      </span>
    </div>

    <WInfiniteListScrollingElement class="h-96 overflow-y-auto overscroll-contain rounded-xl border border-solid border-line-subtle">
      <WInfiniteList
        ref="list"
        :use-query-fn="eventModelApi.paginated.use"
        :query-params="{}"
        :page-length="PAGE_LENGTH"
        page-class="grid"
        min-height-only
        @update:count="count = $event"
      >
        <template #default="{item, skeleton, position}">
          <div
            class="event-row flex h-9 items-center gap-3 border-b border-solid border-line-subtle px-4 text-sm"
          >
            <span class="text-description w-12 text-right tabular-nums">
              {{ position + 1 }}
            </span>

            <WSkeleton v-if="skeleton" />

            <template v-else>
              <span
                class="w-16 font-semibold"
                :class="levelClass[item.level]"
              >
                {{ item.level }}
              </span>

              <span class="text-description w-12 tabular-nums">
                {{ timeFormatter.format(item.at) }}
              </span>

              <span class="truncate">{{ item.message }}</span>
            </template>
          </div>
        </template>
      </WInfiniteList>
    </WInfiniteListScrollingElement>
  </div>
</template>

<script lang="ts" setup>
import {onBeforeUnmount, onMounted, ref, useTemplateRef} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WInfiniteList from 'eco-vue-js/dist/components/InfiniteList/WInfiniteList.vue'
import WInfiniteListScrollingElement from 'eco-vue-js/dist/components/InfiniteList/WInfiniteListScrollingElement.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import {EVENT_COUNT, EventLevel, eventModelApi} from './api/Event'

const PAGE_LENGTH = 50

const levelClass: Record<EventLevel, string> = {
  [EventLevel.INFO]: 'tone-info text-tone',
  [EventLevel.WARNING]: 'tone-warning text-tone',
  [EventLevel.ERROR]: 'tone-negative text-tone',
}

const timeFormatter = Intl.DateTimeFormat('en', {hour: '2-digit', minute: '2-digit', hourCycle: 'h23'})

const listRef = useTemplateRef('list')
const containerRef = useTemplateRef('container')

const count = ref(0)
const row = ref<number>()

// Scrolls to a loaded page, or starts the list over from the row's page.
const jump = () => {
  if (!row.value) return

  const index = Math.min(Math.max(row.value, 1), count.value || EVENT_COUNT) - 1

  listRef.value?.goto(Math.floor(index / PAGE_LENGTH) + 1, index % PAGE_LENGTH)
}

// Only for the demo: counts the rows in the DOM, to show that only a few pages are rendered at a time.
const rendered = ref(0)

let observer: MutationObserver | undefined

onMounted(() => {
  observer = new MutationObserver(() => {
    rendered.value = containerRef.value?.querySelectorAll('.event-row').length ?? 0
  })

  if (containerRef.value) observer.observe(containerRef.value, {childList: true, subtree: true})
})

onBeforeUnmount(() => observer?.disconnect())
</script>
```

## API

### WInfiniteList

```ts
import WInfiniteList from 'eco-vue-js/dist/components/InfiniteList/WInfiniteList.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `useQueryFn` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | **required** | Paginated query the pages are loaded with. Each page gets `queryParams` with its `page` and `size`. |
| `queryParams` | `QueryParams` | **required** | Params of the query. A change resets the list to the first page. A `page` starts the list at that page. |
| `skeletonLength` | `number` | — | Number of skeleton items while the first pages load, e.g. the known total count. Defaults to a full page. |
| `transition` | `boolean` | — | Animates items as they are added or removed. |
| `minHeight` | `boolean` | — | Renders without the sticky header and fills the height of its container, e.g. for a list inside a dropdown. |
| `minHeightOnly` | `boolean` | — | Drops the full-screen minimum height and the bottom padding, for a list inside other content. |
| `noHeaderUpdate` | `boolean` | — | Keeps the sticky header out of the app header bar's padding while scrolled. |
| `excludeParams` | `(keyof QueryParams)[]` | — | Params whose change refetches the loaded pages in place instead of resetting the list to the first page. |
| `emptyStub` | `string` | — | Text shown when the query returns no items. The `empty` slot replaces it. |
| `pageClass` | `string` | — | Class of the element holding the items of all loaded pages, e.g. a grid layout. The pages render no element of their own, so a grid row runs on from one page into the next. |
| `pageStyle` | `StyleValue` | — | Style of the element holding the items, e.g. the columns of a grid. |
| `maxPages` | `number` | — | Number of pages kept rendered, 5 by default. Scrolling further drops pages at the other end, keeping their height as space. |
| `refetchInterval` | `number \| false` | — | Refetches the pages in view every this many ms. |
| `queryOptions` | `DefaultQueryOptions<PaginatedResponse<Data>>` | — | Options for every page query. |
| `pageLength` | `number` | `24` | Page size, sent to the query as `size`. Must match the size the query returns. |
| `valueGetter` | `((data: Data) => Model)` | `(item as unknown as {     id: Model; }).id` | Unique value of an item, for the item's key and the `value` slot prop. Defaults to its `id`. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:page` | `(number \| undefined)` | The page reached by scrolling, for keeping it in the URL. `undefined` after a reset to the first page. |
| `update:count` | `(number)` | Total number of items, from the query's `count`. |
| `update:error` | `(ApiError<{}, ErrorResponse<{}>>)` | A page query failed. A page that answers 404 or 400 is dropped, and the list ends before it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ item: Data; setter: (newItem?: Data \| undefined) => void; skeleton: boolean; refetch: () => void; previous: Data \| undefined; next: Data \| undefined; first: boolean; last: boolean; resetting: boolean; page: number; index: number; position: number; value: Model; results: Data[] \| undefined; intersecting: boolean; }` | An item, or a skeleton placeholder while its page loads. `setter` writes a changed item to the query cache, or removes it when called with nothing; `position` is the item's index in the whole list. |
| `header` | `InfiniteListHeaderScope & Partial<InfiniteListScope>` | Sticky content above the items, such as a toolbar. Gets `refetchAll`, `resetPage`, `goto`, `isFetching` and `isRefetchingAll`, and `updateHeader` to re-measure it right away. |
| `empty` | — | Shown when the query returns no items. Replaces `emptyStub`. |
| `error` | `{ error: Error; retry: () => Promise<void>; isFetching: boolean; }` | Shown instead of a page that failed to load and has nothing cached. Gets the `error`, `retry` to load the page again, and `isFetching`. Replaces the message and Retry button. |

### WInfiniteListScrollingElement

```ts
import WInfiniteListScrollingElement from 'eco-vue-js/dist/components/InfiniteList/WInfiniteListScrollingElement.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parent` | `boolean` | — | Uses the parent element as the scroll container instead of this one. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content with infinite lists and sticky headers that scroll inside this element instead of the page. |

### WInfiniteListWrapper

```ts
import WInfiniteListWrapper from 'eco-vue-js/dist/components/InfiniteList/WInfiniteListWrapper.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `initIsIntersecting` | `boolean` | — | Whether the top of the content starts in view, before the first scroll is observed. `false` when opening at a later page. |
| `noHeaderUpdate` | `boolean` | — | Keeps the sticky header out of the app header bar's padding while scrolled. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `header` | `InfiniteListHeaderScope` | Content that sticks to the top while the page scrolls. `updateHeader` re-measures it right away. |
| `default` | `InfiniteListHeaderScope` | The scrolling content. Gets the header's `headerHeight` and `headerTop`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/list.md
description: >-
  WList — paginated, sortable collections shown as a table on desktop and cards
  on mobile, with one field component per column.
---

# List

`WList` renders a paginated collection as a table on desktop and as cards on mobile. It owns pagination, selection, column settings (show, hide, reorder, resize) and ordering. You give it:

* `useQueryFn` and `queryParams` — a paginated query.
* `fields` — one component per column. Each has a `meta` export with its title, width, ordering field and CSS class, and renders one cell from `item`.
* `cardColumns` and `cardAreas` — the card layout as a CSS grid, with field labels as area names. Every field must appear in `cardAreas`, even ones hidden by default; a field left out renders in an extra grid column.
* Optionally an expansion component for a detail row and a menu component for row actions.

The [List with fields](/recipes/list-with-fields) recipe builds this step by step; the list below is its result.

## Layout variables

The sticky header, the checkbox column and full-width rows position themselves from the app's layout variables — `--header-height`, `--nav-bar-width`, `--actions-bar-width` and `--inner-margin` — so the app has to set them (see [App shell](/guide/app-shell)). Inside a modal, the modal sets its own.

## Bulk actions

Above the table is the selection bar, `WButtonSelection`. While nothing is selected it shows the `action` components and the list settings; while items are selected, the `bulk` components and a "Selected N items" counter with a clear button. Actions that don't fit move into a More menu.

Each action is a component that renders a `WButtonSelectionAction` — an icon with a title, hidden on phones. A bulk action gets `BulkProps`: `selectionCount`, `queryParamsGetter()` for the query params narrowed to the selection, `readonly`, `disableMessage`, which disables the button with that text as its tooltip while nothing is selected, and `clearSelection()` to reset the selection when it is done.

Call `clearSelection` rather than emitting `clear:selected`, which still works but is deprecated. An action that doesn't fit the bar renders in the More menu, and a confirm opened from there takes the menu's place, unmounting the action — an emit after the confirm is accepted never arrives.

```vue
<template>
  <WButtonSelectionAction
    title="Archive"
    :icon="markRaw(IconArchiveBook)"
    :disable-message="disableMessage"
    :disabled="readonly"
    @click="archive"
  />
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import type {BulkProps} from 'eco-vue-js/dist/components/List/types'

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

import IconArchiveBook from 'eco-vue-js/dist/assets/icons/IconArchiveBook'

const props = defineProps<BulkProps<QueryParamsPlants>>()

const archive = () => plantApi.archive(props.queryParamsGetter()).then(() => props.clearSelection())
</script>
```

`WButtonUnselect` is the small round clear button of the select chips.

## Filters

`WListFilter` renders filter components for query params held in a Uniform form's `scope` — usually a form over the route query. Each filter is a component with a `meta` export (its `title`, `icon` and the `fields` it sets) that gets `scope`, `global` and `readonly`. `search` adds a text search for the `search` param, or `filterSearch` for your own.

In place, the filters are chips in a row: the set ones are shown, and a button adds another. With `global` they go into the app shell instead — the filters into the actions bar's panel and the search into the header bar — with a button that resets them. `disabledFilterFields` leaves out filters for params the page fixes. `pinned` filters are always shown, first, and their remove button only clears them. The [List with fields](/recipes/list-with-fields#filters) recipe builds a set of filters for its list.

`WListHeader` and `WListHeaderItem` are the table header row of the list, with the select-all checkbox and sortable, resizable column titles. `WList` renders them from `fields`.

### Filters in the selection bar

Put the `WListFilter` in WList's `filter` slot to show it at the start of the selection bar, on one line with the list actions and the list settings. Chips that do not fit go into a "more" chip that opens them as a list, and the list actions, which move to the end of the bar, fold into More before any chip does. While rows are selected, the selection with its bulk actions replaces the filters, so the bar keeps its height. On phones the filters take a row of their own above the actions, and the search narrows for them. `--w-list-toolbar-height` (`w-list-toolbar-h-*`) sets the height of the bar's inputs, chips and actions, by default the inherited input height.

Each chip names its filter and, when set, the picked values. A filter's `meta.summary` returns them from the query params, such as the titles of the picked options; without it the chip shows how many values are picked. A chip in the "more" list can be removed there too.

## Groups

`groupBy` tells whether two neighbouring items belong to the same group, and the `group` slot renders a heading before the first item of each group and before the first item rendered. Only neighbours are compared, so the query has to sort by the field the list groups by.

The items of all loaded pages share one layout. A group runs on across pages without a new heading, and in the grid a page that ends in the middle of a row is continued in that row by the next one. The list places the heading: it takes a row of its own in the grid, stays under the toolbar while its group scrolls past and, in list mode, stays at the left edge when the rows scroll sideways. The slot gives its content and lays it out.

## Nested fields

A field's `meta` can hold `fields` instead of being a column itself. Its columns then show a related object or every item of an array:

* `keyEntity`, or `getterEntity` for a computed one, gives the nested field components that object as `item`.
* `keyArray`, or `getterArray`, repeats the columns once per array item, one line each. The items need an `id`. `componentItem` wraps each line, for example to draw a separator between them.
* With neither, `fields` only groups the columns, such as to place them in one card area.

In the table, nested columns are list columns like any other: each has its own header and width, can be hidden in the list settings, and lines up across the rows, including each line of an array. In a card, a nested field is a flex row. `cssClass` styles it, `cssClassArray` styles the wrapper of an array's lines, and `[grid-area:…]` places it in one of `cardAreas`; pick labels without `_` for that, since Tailwind reads `_` in a class as a space.

In the table, the root of `componentItem` is a line of the table, and each of its children spans the whole line. Put a separator next to `<slot />`, not around it.

Rows with lines of an array are taller than one line, so the demo uses `align-top`. The checkbox and the row menu then sit `--w-list-align-top` from the top of the row. Set it with `w-list-align-top-*` on WList to match the row's top padding and first line: here the rows have `py-2`, and `w-list-align-top-2.5` centers the box on the first line.

## API

### WList

```ts
import WList from 'eco-vue-js/dist/components/List/WList.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | — | Total number of items, when known in advance. Sizes the skeleton and the select-all. Defaults to the count the query returns. |
| `fields` | `Fields` | **required** | Field components, one per column, each with a `meta` export for its title, label, ordering field and classes. A meta with `fields` groups nested fields. |
| `expansion` | `ExpansionComponent<Data, QueryParams>` | — | Detail component shown under a row when the row is clicked. Receives the same props as a field, except `config`. |
| `useQueryFn` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | **required** | Paginated query the pages are loaded with. |
| `useQueryFnExport` | `UseQueryDefault<PaginatedResponse<Data>, QueryParams>` | — | Paginated query for export, when it differs from `useQueryFn`. |
| `queryParams` | `QueryParams` | **required** | Params for `useQueryFn`. An `ordering` param drives the sort controls and the sortable column headers. |
| `queryOptions` | `DefaultQueryOptions<PaginatedResponse<Data>>` | — | Options for every page query. |
| `bulkDisableMessage` | `string` | — | Tooltip on the `bulk` actions while nothing is selected. Defaults to "No selected items". |
| `selectionTitle` | `string` | **required** | Singular noun in the "Selected N items" counter of the selection bar. |
| `bulk` | `BulkComponent<QueryParams>[]` | — | Actions in the selection bar while items are selected. Each gets the selection count and a getter of the query params narrowed to the selection. The ones that do not fit the bar move into a More menu. |
| `action` | `ActionComponent<QueryParams>[]` | — | Actions in the selection bar while nothing is selected, with the current query params. |
| `menu` | `MenuComponent<Data>[]` | — | Row menu items, opened by the row's more button or a right click. A `[component, props]` tuple passes extra props. |
| `readonlyGetter` | `((item: Data) => boolean)` | — | Makes a single row readonly. |
| `cardClass` | `string` | — | Classes for each row's content box. |
| `cardWrapperClass` | `string` | — | Classes for each row's outer box. |
| `selectAllTextGetter` | `(isUnselect: boolean, count: number) => string` | **required** | Tooltip of the select-all checkbox in the table header. |
| `hasBorder` | `boolean` | — | Draws a border around each row. |
| `configKey` | `string` | **required** | `localStorage` key the column settings and view mode are saved under. |
| `defaultConfigMap` | `FieldConfigMap<Fields>` | **required** | Width, visibility, order and stickiness of each field by label, until the user changes them. |
| `defaultMode` | `ListMode` | `ListMode.TABLE` | Table or grid view, until the user picks one. Small screens always show cards. |
| `alignTop` | `boolean` | — | Aligns cells, the checkbox and the row menu to the top of the row instead of centering them. `--w-list-align-top` (`w-list-align-top-*`) sets how far the checkbox and the menu are from the top, `1.125rem` by default, so they line up with the first line of the cells. |
| `disableMore` | `boolean` | — | Disables the row menu, both the more button and the right click. |
| `readonly` | `boolean` | — | Makes every row readonly, and passes `readonly` to the `bulk`, `action` and `menu` components. When unset, inherits the readonly state provided by a parent. |
| `noOrdering` | `boolean` | — | Hides the sort control and makes the column headers not sortable. |
| `formFieldGetter` | `((data: Data, index: number) => string \| undefined)` | — | Wraps a row in WUniform for the returned field of `uniformScope`, so its fields can edit the item as part of a form. `undefined` leaves the row unwrapped. |
| `uniformScope` | `UniformScope<Data[]>` | — | Form scope of the items, for `formFieldGetter`. |
| `groupBy` | `((a: Data, b: Data) => boolean)` | — | Whether two neighbouring items are in the same group. The `group` slot renders before each new group. |
| `cardColumns` | `CardColumns` | **required** | Column widths of the card grid. |
| `cardAreas` | `CardAreas<Fields, CardColumns["length"]>` | **required** | Rows of the card grid, as area names: field labels, `AREA_SELECT`, `AREA_MORE` or `.`. Areas of hidden fields are dropped, and so are rows and columns left empty. |
| `cardTo` | `((item: Data) => RouteLocationRaw \| undefined)` | — | Route a row links to. |
| `hasAction` | `boolean` | — | Makes a row click emit `click:action`. |
| `noHeaderSettings` | `boolean` | — | Hides the column settings button, and neither loads nor saves column settings. |
| `noRefetch` | `boolean` | — | Hides the refetch button. |
| `refetchInterval` | `number` | — | Refetches the loaded pages every this many ms. |
| `apiMethodExport` | `((queryParams: QueryParams) => Promise<Data[]>)` | — | Loads the items to export in one call, instead of paging through the export query. |
| `exportFileName` | `string` | — | Name of the exported file. |
| `disableExport` | `boolean` | — | Hides the export button. Rows are then selectable only with `bulk` or `alwaysSelect`. |
| `alwaysSelect` | `boolean` | — | Shows the checkboxes even without `bulk` or export, and makes a row click toggle its selection. With `cardTo`, the row link moves into a View menu item. |
| `selection` | `Selection<number>` | — | Selected items, controlled from outside with `update:selection`. By default the selection is kept in the URL hash. |
| `noHeaderUpdate` | `boolean` | — | Keeps the sticky list header out of the app header bar's padding while scrolled. |
| `minHeight` | `boolean` | — | Drops the full-screen minimum height and the bottom padding, for a list inside other content. |
| `toMarkdown` | `((data: Data, index: number) => string)` | — | Converts an item to Markdown. Adds a Copy as Markdown item to the row menu and a Markdown option to export. |
| `noMode` | `boolean` | — | Hides the table and grid switch in the column settings. |
| `disableSelect` | `boolean` | — | Hides the checkboxes and turns selection off. |
| `selectOnly` | `boolean` | — | Allows only picking rows one by one — no select-all and no Shift range selection. |
| `contentVisibility` | `boolean` | — | Skips rendering rows outside the viewport with `content-visibility: auto`, for long lists. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:error` | `(ApiError<{}, ErrorResponse<{}>>)` | A page query failed. |
| `click:action` | `(CardActionParams<Data>)` | A row was clicked, with `hasAction`. Carries the item, a setter that replaces it and its form scope. |
| `update:query-params` | `(QueryParams)` | The changed params only — the new `ordering`, from the sort control or a column header. |
| `update:count` | `(number \| undefined)` | Total count returned by the query. |
| `update:selection` | `(Selection<number>)` | The new selection, with `selection`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `header` | `{ count: number \| undefined; }` | Content above the selection bar, with the count returned by the query. |
| `filter` | — | Filters at the start of the selection bar, usually a WListFilter. They keep to one line, the chips that do not fit go to a menu, the list actions move to the end and fold into More first, and a selection replaces them. `--w-list-toolbar-height` sets the bar's height, the inherited input height by default. |
| `selection` | — | Replaces the buttons at the end of the selection bar — range select, refetch, sort and column settings. |
| `group` | `{ item: Data; previous: Data \| undefined; skeleton: boolean; }` | Content of the heading before each group of rows, with `groupBy`. The heading spans the whole row, sticks under the toolbar and, in list mode, to the left edge while the rows scroll sideways. Its content is laid out by the slot. `skeleton` is true while the page loads. |
| `empty` | — | Shown instead of the rows when the query returns no items. |
| `error` | `{ error: Error; retry: () => Promise<void>; isFetching: boolean; }` | Shown instead of a page that failed to load and has nothing cached. Gets the `error`, `retry` to load the page again, and `isFetching`. Replaces the message and Retry button. |

### WListCardField

```ts
import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `string \| number` | — | Value shown as truncated text. The `inner` and `default` slots replace it. |
| `skeleton` | `boolean` | — | Shows a placeholder instead of the content. |
| `allowOpen` | `boolean` | — | Lets clicks through to the row, so they open its expansion. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Replaces the whole content, including the truncating wrapper. |
| `inner` | — | Replaces `modelValue` inside the truncating wrapper. |

### WButtonSelection

```ts
import WButtonSelection from 'eco-vue-js/dist/components/Button/WButtonSelection.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"item"` | Singular noun in the "Selected N items" counter. An "s" is added for more than one. |
| `disableMessage` | `string` | `"No selected items"` | Tooltip of the actions while nothing is selected, which also disables them. |
| `selectedCount` | `number` | — | Number of selected items. While it is above 0, the counter with a clear button replaces the `settings` slot. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `clear:selection` | — | The clear button of the counter was clicked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ disableMessage: string \| undefined; cssClass: string; visibleCount: number; }` | WButtonSelectionAction buttons. Pass them `disableMessage`, and `cssClass` for the dividers between them. Hide the ones from `visibleCount` on, which do not fit — the `more` slot shows them instead. |
| `more` | `{ disableMessage: string \| undefined; cssClass: string; visibleCount: number; }` | Actions in the More menu at the end of the row: the ones of the `default` slot from `visibleCount` on, which do not fit the row. The menu shows only when some do not. |
| `filter` | — | Filters at the start of the bar while nothing is selected. The actions then move to the end, beside `settings`, and the selection replaces the filters. |
| `settings` | `{ isFilterShown: boolean; }` | Content at the end of the bar while nothing is selected, such as list settings. |

### WButtonSelectionAction

```ts
import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Text after the icon. Hidden on phones, except in the More menu. |
| `label` | `string` | — | Name for screen readers. Defaults to `tooltipText`, then `title`. |
| `icon` | `SVGComponent` | **required** | Icon of the action. |
| `disableMessage` | `string` | — | Disables the action and shows this text in its tooltip, e.g. "No selected items". |
| `disabled` | `boolean` | — | Disables the action. |
| `active` | `boolean` | — | Marks the action as on, e.g. a filter that is applied. |
| `loading` | `boolean` | — | Shows a spinner over the action and ignores clicks. |
| `tooltipText` | `string` | — | Tooltip text. |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |
| `tag` | `keyof HTMLElementTagNameMap` | — | Element rendered without `to`, e.g. `a` for a link with `href`. Defaults to `button`. |
| `href` | `string` | — | Link URL when `tag` is `a`. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | `target` attribute of the link. |
| `replace` | `boolean` | — | Replaces the current history entry instead of adding one, with `to`. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The action was clicked, unless it is disabled or loading. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Slot for absolute positioned content, like counter |
| `tooltip` | — | Rich content of the tooltip, replacing `disableMessage` or `tooltipText`. |

### WButtonSelectionState

```ts
import WButtonSelectionState from 'eco-vue-js/dist/components/Button/WButtonSelectionState.vue'
```

#### Props

*No props.*

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The clear button was clicked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | The selection count, such as "Selected 3 items". |

### WButtonUnselect

```ts
import WButtonUnselect from 'eco-vue-js/dist/components/Button/WButtonUnselect.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Disables the button. |
| `loading` | `boolean` | — | Ignores clicks, e.g. while the value is saving. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The button was clicked, unless it is disabled or loading. |
| `mousedown` | `(value: MouseEvent)` | A mouse button was pressed on it, unless it is disabled or loading. |

### WListFilter

```ts
import WListFilter from 'eco-vue-js/dist/components/List/WListFilter.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `UniformScope<QueryParams>` | **required** | Scope of the Uniform form that holds the query params, usually synced with the route query. |
| `filter` | `FilterComponent<QueryParams>[]` | — | Filter components, one per filter, each with a `meta` export. A tuple adds props for it. |
| `pinned` | `FilterComponent<QueryParams>[]` | — | Filters of `filter` always shown as chips, first, instead of behind "Add filter". Their remove button only clears them. |
| `filterSearch` | `FilterComponent<QueryParams>` | — | Component for the search field, instead of the default text search on `search`. |
| `disabledFilterFields` | `(keyof QueryParams)[]` | — | Query params that can't be changed, e.g. fixed by the page. Their filters are left out. |
| `search` | `boolean` | — | Adds a search field for the `search` query param. |
| `global` | `boolean` | — | Puts the filters in the actions bar's filter panel and the search in the header bar, instead of in a row in place. |
| `readonly` | `boolean` | — | Shows the filters without changing them. |
| `searchVisible` | `boolean` | — | **Deprecated**: No effect: the search field is always shown in place, and behind the header's search button with `global`. |

### WListHeader

```ts
import WListHeader from 'eco-vue-js/dist/components/List/WListHeader.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `string` | **required** | Track sizes of the columns between the checkbox and the end cap, as in `grid-template-columns`. The rows use the same tracks, so the cells line up with them. |
| `allowSelect` | `boolean` | — | Shows the select-all checkbox. |
| `selectOnly` | `boolean` | — | Keeps the checkbox column's space without the checkbox, for lists without select-all. |
| `hideMore` | `boolean` | — | Narrows the end cap when the rows have no menu. |
| `disabled` | `boolean` | — | Disables the checkbox. |
| `count` | `number` | — | Total number of items. The checkbox is disabled while it is 0 or unknown. |
| `selection` | `boolean \| null` | — | State of the select-all checkbox: `true` for all, `null` for some, `false` for none. |
| `tooltipText` | `string` | **required** | Tooltip of the select-all checkbox. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:header` | — | The header was mounted or unmounted, for the sticky header to measure it. |
| `toggle:selection` | `(value: boolean)` | The select-all checkbox was toggled. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | WListHeaderItem cells, one per column. |
| `settings` | — | Content of the end cap, such as the column settings button. |

### WListHeaderItem

```ts
import WListHeaderItem from 'eco-vue-js/dist/components/List/WListHeaderItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Title of the column. The default slot replaces it. |
| `field` | `Field` | **required** | Ordering field of the column. Without it, the title isn't a sort button. |
| `ordering` | `OrderItem<Field>[]` | **required** | Current ordering, to show the column's direction and position in it. |
| `disabled` | `boolean` | — | Turns sorting off. |
| `allowResize` | `boolean` | — | Adds a handle to resize the column. |
| `itemClass` | `string` | — | Class of the title, replacing the default bold one-line style. |
| `styleValue` | `Record<string, string \| undefined> \| undefined` | **required** | Style of the column, such as its sticky offsets. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:width` | `(number)` | The column is being resized to this width. |
| `save:width` | — | Resizing ended, to save the width. |
| `update:ordering` | `(OrderItem<Field>[])` | The title was clicked: descending, then ascending, then off. Other columns stay in the ordering after it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Title of the column, replacing `title`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/report-pages.md
description: >-
  WPage — A4 pages for printable reports, with numbered sections, a footer with
  logo, date and page number, and content that continues on the next page;
  WPageTitle, WPageNumerator and WPageBreadcrumbs.
---

# Report pages

`WPage` is an A4 page for a report that is read on screen and printed from the browser. Each page is 21 × 29.7 cm with print margins, and breaks to a new sheet when printed. Its footer has a logo (`logoComponent` or the `logo` slot), the `date` and the page number; `watermark` writes large faint text across it, such as "Draft".

A page with a `title` starts a numbered section: the number and an `eyebrow` caption go above the title, and the `meta` slot to the right of it. `WPageTitle` is a heading inside a page, numbered in the same sequence; `big` makes it a large cover heading. Wrap the pages in `WPageNumerator` so the numbers start from 1. `empty` leaves a page, such as the cover, out of the page count.

`WPageBreadcrumbs` lists the titles of the pages on the screen, marks the one in view and scrolls to a page when clicked — put it in the header of the report view.

```vue
<template>
  <div class="grid gap-4">
    <WPageBreadcrumbs />

    <div class="h-[40rem] overflow-auto rounded-xl bg-surface-muted p-4">
      <WPageNumerator class="grid justify-center gap-4 [zoom:0.5]">
        <WPage
          :date="date"
          watermark="Draft"
          empty
        >
          <div class="grid h-full content-center gap-4">
            <WPageTitle
              title="Greenhouse survey"
              big
            />

            <span class="text-2xl text-subtle">Riverside community garden</span>
          </div>
        </WPage>

        <WPage
          title="Summary"
          eyebrow="Overview"
          :date="date"
          watermark="Draft"
        >
          <template #meta>
            Site: greenhouse 2<br>
            Surveyor: J. Doe
          </template>

          <div class="grid gap-4 text-lg">
            <p>{{ observations.length }} observations, a third of them high priority.</p>

            <p>
              <WPageTitle title="Method" />
            </p>

            <p>A walk along every bench, checking the leaves, roots and soil, with readings from the moisture sensors.</p>
          </div>
        </WPage>

        <WPage
          title="Observations"
          :date="date"
          watermark="Draft"
        >
          <template #header>
            <div class="grid grid-cols-[4rem_1fr_6rem] border-b border-solid border-line-subtle py-2 font-semibold">
              <span>#</span><span>Observation</span><span>Priority</span>
            </div>
          </template>

          <!-- Rows of a `w-page-inner` element move one by one, so the table continues on the next page. -->
          <div class="w-page-inner">
            <div
              v-for="(item, index) in observations"
              :key="index"
              class="border-b border-solid border-line-raised py-3 text-lg"
            >
              <!-- One element inside, so the row moves whole. -->
              <div class="grid grid-cols-[4rem_1fr_6rem]">
                <span class="text-subtle">{{ index + 1 }}</span>
                <span>{{ item.title }}</span>
                <span>{{ item.priority }}</span>
              </div>
            </div>
          </div>
        </WPage>
      </WPageNumerator>
    </div>
  </div>
</template>

<script lang="ts" setup>
import WPage from 'eco-vue-js/dist/components/Page/WPage.vue'
import WPageBreadcrumbs from 'eco-vue-js/dist/components/Page/WPageBreadcrumbs.vue'
import WPageNumerator from 'eco-vue-js/dist/components/Page/WPageNumerator.vue'
import WPageTitle from 'eco-vue-js/dist/components/Page/WPageTitle.vue'

const date = new Date(2026, 8, 30)

const TITLES = ['Root rot in the aloe', 'Spider mites on the monstera', 'Powdery mildew on the courgettes', 'Leggy basil seedlings', 'Yellow tips on the fern', 'Aphids on the roses']
const PRIORITIES = ['High', 'High', 'Medium', 'Low', 'Low', 'Medium']

const observations = Array.from({length: 36}, (_, index) => ({title: TITLES[index % TITLES.length]!, priority: PRIORITIES[index % PRIORITIES.length]!}))
</script>
```

## Content that doesn't fit

Content is measured once it renders. Blocks that don't fit move to a continuation page, which repeats the title small at the top and the `header` slot, such as a table header, and so on until everything fits. By default a block moves whole. The children of an element with the `w-page-inner` class — the slot's `INNER_CLASS` — move one by one instead, so a long list continues where the page ends, inside a copy of that element. A child with one element inside or none moves whole; a child with several is a group, and its own children move one by one into a copy of it — so wrap a row's cells in one element to keep the row together.

While the data loads, set `skeleton`: content that doesn't fit stays on the page until it turns `false`. When content changes size later, call the slot's `updateOverflow`.

Content is moved as DOM elements, outside Vue: after it is split, keep it static. To show new data, re-render the page with a new `key`.

## API

### WPage

```ts
import WPage from 'eco-vue-js/dist/components/Page/WPage.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Title of the section the page starts, numbered and listed in WPageBreadcrumbs. Continuation pages repeat it small at the top. |
| `eyebrow` | `string` | — | Caption after the section number above the title. |
| `empty` | `boolean` | — | Leaves the page out of the page count and hides its number, e.g. for a cover. |
| `centerLogo` | `boolean` | — | Centers the logo in the footer, in place of the date. |
| `logoComponent` | `Component` | — | Logo in the footer. The `logo` slot replaces it. |
| `topTitle` | `boolean` | — | Shows `title` small at the top instead of as a heading. Set on continuation pages. |
| `date` | `Date` | — | Date in the middle of the footer, such as the date of the report. |
| `prerendered` | `HTMLElement[]` | — | Elements moved from the previous page because they didn't fit. Set on continuation pages. |
| `skeleton` | `boolean` | — | While `true`, content that doesn't fit stays on the page. It is split into continuation pages once loading ends. |
| `watermark` | `string` | — | Large faint text across the page, such as "Draft". |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ updateOverflow: () => void; INNER_CLASS: string; }` | Content of the page. Blocks that don't fit move to a continuation page. Children of an element with the `INNER_CLASS` class (`w-page-inner`) move one by one, so a long list or table continues on the next page. Call `updateOverflow` when the content changes size after loading. |
| `header` | — | Content above the page's content, repeated on continuation pages, such as a table header. |
| `intro` | — | Content under the title, on the first page only. |
| `meta` | — | Content to the right of the title, such as the report's details. |
| `logo` | — | Logo in the footer, replacing `logoComponent`. |

### WPageTitle

```ts
import WPageTitle from 'eco-vue-js/dist/components/Page/WPageTitle.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | **required** | Text of the heading, after its section number. |
| `big` | `boolean` | — | A large heading, with the number in two digits, e.g. for a cover. |

### WPageNumerator

```ts
import WPageNumerator from 'eco-vue-js/dist/components/Page/WPageNumerator.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | WPage pages and WPageTitle headings, numbered from 1. |

### WPageBreadcrumbs

```ts
import WPageBreadcrumbs from 'eco-vue-js/dist/components/Page/WPageBreadcrumbs.vue'
```

#### Props

*No props.*

---

---
url: https://rsmple.github.io/eco-vue-js/components/bottom-sheet.md
description: >-
  WBottomSheet and WDismissable — the phone version of a dropdown, a sheet that
  slides up from the bottom and closes when swiped down.
---

# Bottom sheet

`WBottomSheet` is the phone version of a dropdown: a sheet that slides up from the bottom with the toggle repeated at its top. The kit's menus and selects switch to it on phones on their own — through [`WDropdownAdaptive`](/components/dropdown-menu#custom-dropdown) and the overlay manager — so use it directly only for your own phone UI.

The `toggle` slot is rendered in place and again at the top of the sheet: `unclickable` is `true` for the one in place and `false` for the copy, so the copy can be made inert. The `content` slot scrolls under it. The sheet emits `close` when swiped down or when the backdrop is tapped — set `isOpen` to `false` on it. `compact` sizes it to its content, up to 90% of the screen, and `noOverlay` leaves the page in view without the backdrop; a tap on the page then closes it.

`WDismissable` is the swipe under the sheet: a full-screen layer whose content scrolls up into view when `isOpen` turns on, and emits `close` when it is scrolled mostly out of view. Build on it for another swipe-away panel.

```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <WBottomSheet
      :is-open="isOpen"
      compact
      @close="isOpen = false"
    >
      <template #toggle="{unclickable}">
        <WButton
          :semantic-type="SemanticType.SECONDARY"
          :class="{'pointer-events-none': !unclickable}"
          @click="isOpen = true"
        >
          {{ plant }}
        </WButton>
      </template>

      <template #content>
        <div class="grid pb-6">
          <WMenuItem
            v-for="item in plants"
            :key="item"
            :active="item === plant"
            @click="pick(item)"
          >
            {{ item }}
          </WMenuItem>
        </div>
      </template>
    </WBottomSheet>

    <span class="text-description text-sm">Swipe it down, or tap the backdrop, to close it.</span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WBottomSheet from 'eco-vue-js/dist/components/BottomSheet/WBottomSheet.vue'
import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WMenuItem from 'eco-vue-js/dist/components/MenuItem/WMenuItem.vue'

const plants = ['Basil', 'Lavender', 'Mint', 'Rosemary', 'Thyme']

const plant = ref(plants[0]!)
const isOpen = ref(false)

const pick = (value: string) => {
  plant.value = value
  isOpen.value = false
}
</script>
```

## API

### WBottomSheet

```ts
import WBottomSheet from 'eco-vue-js/dist/components/BottomSheet/WBottomSheet.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | **required** | Opens the sheet. |
| `compact` | `boolean` | — | Sizes the sheet to its content, up to 90% of the screen, instead of always taking 90%. |
| `noOverlay` | `boolean` | — | Leaves the page in view without the dimmed backdrop. A tap outside the sheet still closes it, and also reaches the page. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close` | — | The sheet was swiped down, or the backdrop — with `noOverlay`, the page — was tapped. Set `isOpen` to `false` on it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `toggle` | `{ unclickable: boolean; isTop?: boolean \| undefined; }` | Element that opens the sheet, rendered in place and again at the top of the sheet — `unclickable` is `true` for the one in place and `false` for the copy. |
| `content` | — | Content of the sheet, which scrolls under the toggle. |
| `footer` | — | Pinned at the bottom of the sheet, under the content that scrolls, such as a form's buttons. |

### WDismissable

```ts
import WDismissable from 'eco-vue-js/dist/components/Dismissable/WDismissable.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | **required** | Shows the layer and scrolls the content into view. |
| `contentClass` | `string` | — | Class of the content's box. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close` | — | The content was swiped or scrolled mostly out of view, or the space above it was clicked. Set `isOpen` to `false` on it. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ hide: () => Promise<void>; }` | Content that slides up from the bottom. `hide` slides it out, which then emits `close`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/dropdown.md
description: >-
  WDropdown and WDropdownTip — content placed in a fixed layer against an
  element or a text selection, following it as the page scrolls, with a tip
  pointing at it.
---

# Dropdown

`WDropdown` is the positioning layer under the kit's menus, selects and tooltips. It places its default slot in a fixed layer against `parentElement` — an element, or anything with `getBoundingClientRect`, such as a text selection `Range` — and follows it as the page scrolls. For a menu with a toggle, [`WDropdownMenu`](/components/dropdown-menu#custom-dropdown) adds the toggle and the teleport to `<body>`; use `WDropdown` directly for anything else, such as a toolbar over selected text.

* **`horizontalAlign`** lines the content up with the parent, as in `WDropdownMenu`. When it doesn't fit the screen, the next placement in order is tried.
* **Vertically** it opens below the parent, or above when there's more room there; `top` prefers above and `bottom` always opens below. The slot gets `isTop`, `isLeft` and `isRight` for the side it picked.
* **`updateAlign`** picks the placement again as the parent moves. `emitUpdate` stops following and emits `update:rect` on scroll and resize instead, e.g. to close it; `freeze` keeps the current position, e.g. while the parent leaves the page.
* **`innerClass`** goes on the content's box, `w-max` by default.

It is `position: fixed`, so put it in a `<Teleport to="body">`: a transformed or filtered ancestor would otherwise become what it's positioned in.

`WDropdownTip` is the small arrow of the kit's dropdowns and tooltips, drawn in the surface color of its tone with the raised line around it. Put it first in the slot with `top` set from `isTop`: it moves after the content when the dropdown opens above. `left` and `right` point it sideways, for content beside the parent.

```vue
<template>
  <div class="grid max-w-xl gap-2">
    <span class="text-description text-sm">Select a few words:</span>

    <p
      ref="text"
      class="leading-relaxed"
      @mouseup="updateRange"
      @keyup="updateRange"
    >
      Monstera likes bright, indirect light and a chunky, well-draining mix. Water it when the top few centimetres of
      soil are dry, and wipe the leaves now and then so they can breathe.
    </p>

    <Teleport to="body">
      <WDropdown
        v-if="range"
        :parent-element="range"
        :horizontal-align="HorizontalAlign.CENTER"
        inner-class="w-max tone-surface-raised flex flex-col items-center"
        update-align
        top
        class="z-50"
      >
        <template #default="{isTop}">
          <WDropdownTip :top="isTop" />

          <div class="w-dropdown-frame w-tooltip-center-x flex gap-1 p-1">
            <WMenuItem @click="add">
              Add to notes
            </WMenuItem>
          </div>
        </template>
      </WDropdown>
    </Teleport>

    <ul
      v-if="notes.length"
      class="text-description list-disc pl-5 text-sm"
    >
      <li
        v-for="note in notes"
        :key="note"
      >
        {{ note }}
      </li>
    </ul>
  </div>
</template>

<script lang="ts" setup>
import {onBeforeUnmount, onMounted, ref, shallowRef, useTemplateRef} from 'vue'

import {HorizontalAlign} from 'eco-vue-js/dist/utils/HorizontalAlign'

import WDropdown from 'eco-vue-js/dist/components/Dropdown/WDropdown.vue'
import WDropdownTip from 'eco-vue-js/dist/components/Dropdown/WDropdownTip.vue'
import WMenuItem from 'eco-vue-js/dist/components/MenuItem/WMenuItem.vue'

const textRef = useTemplateRef('text')

const range = shallowRef<Range>()
const notes = ref<string[]>([])

// The dropdown follows the selected text, a `Range`, as the page scrolls.
const updateRange = () => {
  const selection = document.getSelection()
  const selected = selection?.rangeCount ? selection.getRangeAt(0) : undefined

  range.value = selected && !selected.collapsed && textRef.value?.contains(selected.commonAncestorContainer) ? selected : undefined
}

const add = () => {
  const text = range.value?.toString().trim()

  if (text) notes.value.push(text)

  document.getSelection()?.removeAllRanges()
  range.value = undefined
}

onMounted(() => document.addEventListener('selectionchange', updateRange))
onBeforeUnmount(() => document.removeEventListener('selectionchange', updateRange))
</script>
```

## API

### WDropdown

```ts
import WDropdown from 'eco-vue-js/dist/components/Dropdown/WDropdown.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `horizontalAlign` | `HorizontalAlign` | **required** | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `top` | `boolean` | — | Prefers opening above the parent. |
| `bottom` | `boolean` | — | Always opens below the parent. |
| `parentElement` | `Pick<Element, "getBoundingClientRect"> & { contextElement?: Element \| undefined; }` | **required** | Element (or range) the dropdown is positioned against. A virtual one names the element it sits in with `contextElement`, so the dropdown follows its scrolling. |
| `updateAlign` | `boolean` | — | Picks the placement again as the parent moves, instead of keeping the first one. |
| `emitUpdate` | `boolean` | — | Emits `update:rect` on scroll and resize instead of following the parent. |
| `freeze` | `boolean` | — | Stops following the parent and keeps the current position, e.g. once the parent is leaving the page. |
| `innerClass` | `string` | — | Classes for the dropdown's content box. Defaults to `w-max`. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:rect` | — | The page scrolled or resized while `emitUpdate` is set, e.g. to close the dropdown. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `DropdownDefaultSlotScope` | Content of the dropdown. `isTop` is true when it opened above the parent, `isLeft` and `isRight` when it opened to that side, and `atBottom` when the parent is in the lower half of the screen. |

### WDropdownTip

```ts
import WDropdownTip from 'eco-vue-js/dist/components/Dropdown/WDropdownTip.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top` | `boolean` | — | Points down, placed after the content — for a dropdown above its parent. Without a side, it points up. |
| `left` | `boolean` | — | Points right, placed after the content — for a dropdown to the left of its parent. |
| `right` | `boolean` | — | Points left, placed before the content — for a dropdown to the right of its parent. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `mouseover` | `(value: MouseEvent)` | The pointer entered the tip, e.g. to keep a tooltip open while it moves onto the content. |
| `mouseleave` | `(value: MouseEvent)` | The pointer left the tip. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/dropdown-menu.md
description: >-
  Menus and dropdowns — WButtonMore and WButtonDropdown for action menus,
  WDropdownMenu for any content anchored to an element, WDropdownAdaptive for a
  bottom sheet on phones, and WMenuItem rows.
---

# Dropdown menu

For a menu of actions, use a ready-made button. For anything else anchored to an element — a column picker, a filter, a date range — build it on `WDropdownMenu`.

## Action menus

* `WButtonMore` is the "⋯" button: its default slot is the menu, and any click closes it. Only one menu is open at a time, and on phones it opens as a bottom sheet. The menu is rendered by `WModal` at the app root, with the slot keeping its context, and a confirm opened from an item with `useOverlay` takes its place — see [Anchored confirm](/components/modal#anchored-confirm). The `toggle` slot swaps the "⋯" for another button, such as a `WButtonInput`: it gets `toggle` for the click, `attrs` for the button and `active` for its highlight.
* `WButtonDropdown` is a button with an arrow next to it: the `button` slot holds the main action and the `content` slot the others. The `content` slot gets `close`.

Menu items are `WButtonMoreItem`s: a `text` (or the default slot), an `icon`, and `to` or `href` to make the item a link. A disabled item can explain itself with `tooltipText`. `semanticType` colors an item, like the red Delete below.

```vue
<template>
  <div class="flex items-center gap-6">
    <span>Herb bed</span>

    <WButtonMore>
      <WButtonMoreItem
        text="Rename"
        :icon="markRaw(IconEdit)"
        @click="action = 'Rename'"
      />

      <WButtonMoreItem
        text="Duplicate"
        :icon="markRaw(IconCopy)"
        @click="action = 'Duplicate'"
      />

      <WButtonMoreItem
        text="Archive"
        :icon="markRaw(IconArchiveBook)"
        disabled
        tooltip-text="Only the head gardener can archive a bed"
      />

      <WButtonMoreItem
        text="Delete"
        :icon="markRaw(IconTrash)"
        :semantic-type="SemanticType.NEGATIVE"
        @click="action = 'Delete'"
      />
    </WButtonMore>

    <WButtonDropdown>
      <template #button>
        <WButton @click="action = 'Export as CSV'">
          Export as CSV
        </WButton>
      </template>

      <template #content="{close}">
        <WButtonMoreItem
          text="Export as JSON"
          @click="action = 'Export as JSON'; close()"
        />

        <WButtonMoreItem
          text="Export as PDF"
          @click="action = 'Export as PDF'; close()"
        />
      </template>
    </WButtonDropdown>

    <WButtonMore>
      <template #toggle="{toggle, active, attrs}">
        <WButtonInput
          :icon="markRaw(IconSort)"
          tooltip-text="Sort beds"
          :active="active"
          v-bind="attrs"
          @click="toggle"
        />
      </template>

      <WButtonMoreItem
        text="Sort by name"
        @click="action = 'Sort by name'"
      />

      <WButtonMoreItem
        text="Sort by planting date"
        @click="action = 'Sort by planting date'"
      />
    </WButtonMore>
  </div>

  <p class="text-description mt-4 text-sm">
    Last action: {{ action ?? 'none' }}
  </p>
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WButtonDropdown from 'eco-vue-js/dist/components/Button/WButtonDropdown.vue'
import WButtonInput from 'eco-vue-js/dist/components/Button/WButtonInput.vue'
import WButtonMore from 'eco-vue-js/dist/components/Button/WButtonMore.vue'
import WButtonMoreItem from 'eco-vue-js/dist/components/Button/WButtonMoreItem.vue'

import IconArchiveBook from 'eco-vue-js/dist/assets/icons/IconArchiveBook'
import IconCopy from 'eco-vue-js/dist/assets/icons/IconCopy'
import IconEdit from 'eco-vue-js/dist/assets/icons/IconEdit'
import IconSort from 'eco-vue-js/dist/assets/icons/IconSort'
import IconTrash from 'eco-vue-js/dist/assets/icons/IconTrash'

const action = ref<string>()
</script>
```

## Custom dropdown

`WDropdownMenu` renders the `toggle` slot in place and, while `isOpen` is true, the `content` slot in a layer on `<body>`, positioned against the toggle. It has no state of its own: the parent opens and closes it, usually with a [`WClickOutside`](/components/click-outside) around the content to close it on a click elsewhere. It is built on [`WDropdown`](/components/dropdown), which also works without a toggle, e.g. against a text selection.

```vue
<template>
  <WDropdownMenu
    :is-open="isOpen"
    :horizontal-align="HorizontalAlign.LEFT_INNER"
  >
    <template #toggle>
      <WButton
        :semantic-type="SemanticType.SECONDARY"
        class="w-max"
        @click="isOpen = !isOpen"
      >
        Columns: {{ visible.length }} of {{ COLUMNS.length }}
      </WButton>
    </template>

    <template #content>
      <WClickOutside
        class="surface-raised my-2 grid w-64 gap-1 rounded-xl p-3 shadow-md border border-line-raised"
        @click="isOpen = false"
      >
        <WCheckbox
          v-for="column in COLUMNS"
          :key="column"
          :model-value="visible.includes(column)"
          :title="column"
          no-margin
          @update:model-value="visible = $event ? [...visible, column] : visible.filter(item => item !== column)"
        />
      </WClickOutside>
    </template>
  </WDropdownMenu>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {HorizontalAlign} from 'eco-vue-js/dist/utils/HorizontalAlign'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WCheckbox from 'eco-vue-js/dist/components/Checkbox/WCheckbox.vue'
import WClickOutside from 'eco-vue-js/dist/components/ClickOutside/WClickOutside.vue'
import WDropdownMenu from 'eco-vue-js/dist/components/DropdownMenu/WDropdownMenu.vue'

const COLUMNS = ['Name', 'Species', 'Height', 'Kind', 'Watered']

const isOpen = ref(false)
const visible = ref(['Name', 'Species', 'Height'])
</script>
```

* **`horizontalAlign`** lines the content up with the toggle: `LEFT_INNER` and `RIGHT_INNER` align their left or right edges, `FILL` makes the content as wide as the toggle, `CENTER` centres it, and the `OUTER` values put it beside the toggle.
* **Vertically** it opens below the toggle, or above when there's more room there; `top` forces above. The `content` slot gets `isTop`, `isLeft` and `isRight`, to round the right corners or place an arrow.
* **`parentElement`** anchors the content to another element than the toggle. `updateAlign` picks the sides again when the toggle moves while the dropdown is open.
* **`dropdownClass`** goes on the positioned box, for its width or max height.

`WDropdownAdaptive` opens its `content` with the overlay manager, like the list's sort and filter menus: a dropdown in the standard `w-dropdown-frame`, or a [bottom sheet](/components/bottom-sheet) on phones. Only one is open at a time, and it emits `close` when it closes on its own — a click outside, Escape, a swipe, or another dropdown taking its place. Without `horizontalAlign` it is centered on the toggle with a tip. The sheet starts with the `header` slot, or else a copy of the toggle with `unclickable` false. Opened from inside a dropdown with `closeOnClick` it takes that one's place; from any other, such as a filter, it opens over it.

`WMenuItem` is a row for the content of a custom menu — the row that `WButtonMoreItem` and the list menus are built from. It is a button, a router link with `to`, or a plain link with `href` (and `download` for a file). `active` marks the picked option with a check; `false` keeps room for the check, so that the rows of a picker line up. `loading` shows a spinner over it while its action runs.

## API

### WDropdownMenu

```ts
import WDropdownMenu from 'eco-vue-js/dist/components/DropdownMenu/WDropdownMenu.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | **required** | Shows the menu. |
| `parentElement` | `(Pick<Element, "getBoundingClientRect"> & { contextElement?: Element \| undefined; })` | — | Element the menu is positioned against. Defaults to the element rendered by the `toggle` slot. |
| `dropdownClass` | `string` | — | Classes for the menu's content box. Defaults to `w-max`. |

::: details Inherited from `src/components/Dropdown/types.ts` (6)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `horizontalAlign` | `HorizontalAlign` | **required** | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |
| `top` | `boolean` | — | Prefers opening above the parent. |
| `bottom` | `boolean` | — | Always opens below the parent. |
| `updateAlign` | `boolean` | — | Picks the placement again as the parent moves, instead of keeping the first one. |
| `emitUpdate` | `boolean` | — | Emits `update:rect` on scroll and resize instead of following the parent. |
| `freeze` | `boolean` | — | Stops following the parent and keeps the current position, e.g. once the parent is leaving the page. |

:::

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:rect` | — | The parent moved on scroll or resize, with `emitUpdate` set. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `toggle` | `{ isTop: boolean; unclickable: undefined; }` | Element that opens the menu, and that it is positioned against. `isTop` is true while the menu is open above it. |
| `content` | `DropdownDefaultSlotScope` | Menu content, rendered while open. `isTop`, `isLeft` and `isRight` tell where it opened relative to the parent, `atBottom` that it sits in the lower half of the viewport. |

### WDropdownAdaptive

```ts
import WDropdownAdaptive from 'eco-vue-js/dist/components/DropdownMenu/WDropdownAdaptive.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isOpen` | `boolean` | **required** | Shows the dropdown. |
| `parentElement` | `(Pick<Element, "getBoundingClientRect"> & { contextElement?: Element \| undefined; }) \| null` | — | Element the dropdown opens at. Defaults to the element rendered by the `toggle` slot. |
| `horizontalAlign` | `HorizontalAlign` | — | Aligns the dropdown to the parent without a tip, such as a field's menu with `HorizontalAlign.FILL`. Otherwise it is centered on the parent with a tip pointing at it. |
| `dialog` | `boolean` | — | The content is a small form, such as a filter: the `header` slot is its title on every screen, and the frame pads the content and sizes to it. |
| `frameClass` | `string` | — | Classes of the dropdown's box, replacing the default frame. |
| `closeOnClick` | `boolean` | — | A click on the content closes the layer, as in a menu. What is opened from it takes its place; from a dropdown without it, such as a filter, it stays over it. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close` | — | The dropdown closed without `isOpen` turning false — a click outside, Escape, a swipe, or another dropdown taking its place. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `toggle` | `{ isTop: boolean; unclickable: boolean \| undefined; }` | Element that opens the dropdown, which it points at. `isTop` is true while the dropdown is open above it. On phones it is repeated at the top of the bottom sheet, unless there is a `header` — `unclickable` is true for the one on the page and false for the copy in the sheet. |
| `header` | — | Heading of the bottom sheet on phones, instead of the copy of `toggle`. With `dialog`, the title of the dropdown too. |
| `content` | — | Content of the dropdown, which brings its own padding, unless it is a `dialog`. A click inside closes it with `closeOnClick`. |

### WButtonMore

```ts
import WButtonMore from 'eco-vue-js/dist/components/Button/WButtonMore.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `SVGComponent` | — | Icon of the button. Defaults to three dots. |
| `disabled` | `boolean` | — | Blocks opening and dims the button. |
| `anchor` | `(Pick<Element, "getBoundingClientRect"> & { contextElement?: Element \| undefined; })` | — | Element the menu is positioned against instead of the button, aligned to its right edge — for a menu opened at a cursor or row. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close` | — | The menu closed — by a click on the button or inside the menu, or by something opened from it taking its place. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Menu items, usually WButtonMoreItem. A click inside closes the menu. Only one menu is open at a time, and on phones it is a bottom sheet. A confirm opened from an item with `useOverlay` takes the menu's place at the same anchor. |
| `toggle` | `{ toggle: () => void; active: boolean; attrs: { 'aria-expanded': boolean; }; }` | Replaces the three-dots button, such as with WButtonInput: call `toggle` on click, bind `attrs` to the button and `active` to its highlight — `active` stays off while the menu is open at a custom anchor. |

### WButtonDropdown

```ts
import WButtonDropdown from 'eco-vue-js/dist/components/Button/WButtonDropdown.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `semanticType` | `SemanticType` | — | Color scheme of the arrow button. |
| `leftToggle` | `boolean` | — | Puts the arrow button before the `button` slot instead of after it. |
| `disabled` | `boolean` | — | Disables the arrow button. Buttons in the `button` slot keep their own state. |
| `tooltipText` | `string` | — | Tooltip over the whole button row. |
| `horizontalAlign` | `HorizontalAlign` | `HorizontalAlign.LEFT_INNER` | Horizontal placement relative to the parent. When it does not fit the viewport, the next placement in order is tried. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `button` | — | Buttons joined to the arrow button. They keep their own click handlers. |
| `content` | `{ close: () => void; }` | Menu content, usually WButtonMoreItem. A click inside closes the menu, and so does `close`. On phones it is a bottom sheet. |

### WMenuItem

```ts
import WMenuItem from 'eco-vue-js/dist/components/MenuItem/WMenuItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Grays the item out and ignores clicks. |
| `href` | `string` | — | URL of a plain link, when there is no `to`. |
| `download` | `string` | — | `download` attribute of the `href` link — the file name to save it as. |
| `replace` | `boolean` | — | With `to`, replaces the current history entry instead of pushing a new one. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | Native `target` of the link, with `href` or `to`. |
| `rel` | `string` | — | Native `rel` of the link, with `href` or `to`. |
| `active` | `boolean` | — | Marks the item as picked, with primary text and a check. `false` leaves room for the check, to line up with picked items. |
| `tooltipText` | `string` | — | Tooltip text on the left of the item. |
| `loading` | `boolean` | — | Shows a spinner over the item and ignores clicks. |
| `semanticType` | `SemanticType` | `SemanticType.PRIMARY` | Color of the item. Types other than `primary` and `secondary` color the text at rest — a red "Delete". |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The item was clicked, unless it is disabled or loading. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content of the item, laid out in a row. |

### WButtonMoreItem

```ts
import WButtonMoreItem from 'eco-vue-js/dist/components/Button/WButtonMoreItem.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | Label. The `default` slot replaces it. |
| `icon` | `SVGComponent` | — | Icon after the label. The `icon` slot replaces it. |
| `disabled` | `boolean` | — | Blocks clicks and dims the item. |
| `href` | `string` | — | Renders the item as a link to this URL. |
| `download` | `string` | — | Native `download` attribute, with `href`. |
| `replace` | `boolean` | — | With `to`, replaces the current history entry instead of pushing a new one. |
| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | Native `target` of the link, with `href` or `to`. |
| `rel` | `string` | — | Native `rel` of the link, with `href` or `to`. |
| `tooltipText` | `string` | — | Tooltip over the item. |
| `semanticType` | `SemanticType` | — | Color of the item. Types other than `primary` and `secondary` color the text at rest — a red "Delete". |
| `to` | `RouteLocationRaw` | — | Router location — renders a router link. Needs vue-router installed in the app. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(value: MouseEvent)` | The item was clicked. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Label. Replaces `text`. |
| `icon` | — | Icon after the label. Replaces `icon`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/modal.md
description: >-
  Opening modals with Modal.add and Modal.addConfirm, or useOverlay from a
  component — which also opens any component in a dropdown — anchoring a confirm
  to the element it is about, building a modal body with WModalWrapper, steps
  with a stepper WTabs, and closing it with close:modal.
---

# Modal

Modals are not placed in templates. They are opened from code, rendered by the single `WModal` container mounted at the app root (see [Getting started](/guide/getting-started#global-containers)), and stacked when several are open. The same container renders the menus of WButtonMore, so a confirm can take a menu's place.

## Confirm

`Modal.addConfirm` opens a ready-made dialog with a title, description and up to three actions. `onAccept` may return a promise — the accept button shows a spinner until it resolves, then the modal closes. If it rejects, the modal stays open.

```vue
<template>
  <WButton
    :semantic-type="SemanticType.NEGATIVE"
    @click="confirmDelete"
  >
    Delete bed
  </WButton>

  <p class="mt-2 text-sm text-description">
    {{ status }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {Modal} from 'eco-vue-js/dist/utils/Modal'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

const status = ref('Nothing happened yet.')

const confirmDelete = () => {
  Modal.addConfirm({
    title: 'Delete bed?',
    description: 'The bed and its planting history are removed for everyone.',
    acceptText: 'Delete',
    acceptSemanticType: SemanticType.NEGATIVE,
    onAccept: () => {
      status.value = 'Deleted.'
    },
    onCancel: () => {
      status.value = 'Cancelled.'
    },
  })
}
</script>
```

## Anchored confirm

A modal covers the page, so the user loses sight of the row or selection they are confirming for. Pass `anchor` and the same confirm opens as a dropdown under that element instead — a bottom sheet without the backdrop on phones. Use it for short yes-or-no questions; keep the modal for long descriptions and forms.

Open it with `useOverlay()`, called in setup, whose `add`, `addAutoclosable` and `addConfirm` work like `Modal` for the overlay the component is in:

* Opened from a menu — WButtonMore, or the More menu of a list's selection bar — the confirm takes the menu's place at the menu's anchor, without `anchor`: the `⋯` button, or the point where a row was right-clicked. The row stays highlighted until the confirm closes.

* Opened from a modal, it closes together with the modal, and a click beside the modal closes the confirm first.

* A click outside, Escape or a swipe down closes it and calls `onCancel`. Opening it again from the same anchor closes it too.

* While the `onAccept` promise is pending, clicks on the page are blocked, so the selection or filters it was confirmed for cannot change under it.

* When the anchor is no longer on the page, `addConfirm` opens the modal instead.

```vue
<template>
  <div class="flex flex-wrap items-center gap-2">
    <WButton
      :semantic-type="SemanticType.NEGATIVE"
      @click="confirmClear"
    >
      Clear bed
    </WButton>

    <WButtonMore>
      <WMenuClearBed @status="status = $event" />
    </WButtonMore>
  </div>

  <p class="mt-2 text-sm text-description">
    {{ status }}
  </p>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WButtonMore from 'eco-vue-js/dist/components/Button/WButtonMore.vue'

import WMenuClearBed from './parts/WMenuClearBed.vue'

const status = ref('Nothing happened yet.')

const overlay = useOverlay()

const confirmClear = (event: Event) => {
  overlay.addConfirm({
    title: 'Clear the bed?',
    description: 'Every plant in it is moved to the compost.',
    acceptText: 'Clear',
    acceptSemanticType: SemanticType.NEGATIVE,
    // The clicked button.
    anchor: event.currentTarget as Element,
    // The page is held still while the promise is pending.
    onAccept: () => new Promise<void>(resolve => setTimeout(resolve, 1000)).then(() => {
      status.value = 'Cleared.'
    }),
    onCancel: () => {
      status.value = 'Cancelled.'
    },
  })
}
</script>
```

```vue [WMenuClearBed.vue]
<template>
  <WButtonMoreItem
    text="Clear bed"
    :icon="markRaw(IconTrash)"
    :semantic-type="SemanticType.NEGATIVE"
    @click="confirmClear"
  />
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButtonMoreItem from 'eco-vue-js/dist/components/Button/WButtonMoreItem.vue'

import IconTrash from 'eco-vue-js/dist/assets/icons/IconTrash'

const emit = defineEmits<{
  (e: 'status', value: string): void
}>()

// Opened from a menu, the confirm takes its place at the menu's anchor — the `⋯` button, or the point a row was right-clicked.
const overlay = useOverlay()

const confirmClear = () => {
  overlay.addConfirm({
    title: 'Clear the bed?',
    description: 'Every plant in it is moved to the compost.',
    acceptText: 'Clear',
    acceptSemanticType: SemanticType.NEGATIVE,
    onAccept: () => emit('status', 'Cleared from the menu.'),
    onCancel: () => emit('status', 'Cancelled.'),
  })
}
</script>
```

## Dropdown or modal

`useOverlay()`, called in setup, opens any component and lets WModal frame it. Say how with `present`:

* `modal` — centered over the backdrop, stacked over other modals. The component brings its own frame, such as `WModalWrapper`.
* `dropdown` — at `anchor`, one at a time, and a bottom sheet on phones. It is centered on the anchor with a tip pointing at it, and near the edge of the screen the box shifts aside while the tip stays. `dropdown` options open it at a point instead (`cornered`) or aligned to the anchor without the tip (`align`, such as `HorizontalAlign.FILL` for a field's menu), set its box (`frameClass`), and whether a click inside closes it (`closeOnClick`). A layer opened from a dropdown with `closeOnClick` takes its place, as from a menu. Opened from any other dropdown, it stays over it — like a select's menu inside a filter, which closes first on Escape.

`open` returns a function that closes the layer, or `null` if nothing opened. The component closes the layer by emitting `close:modal`. Inside it:

* It sees the opener's injections, and its own `useOverlay()` opens what belongs to the same layer.
* `useOverlayFrame()` tells whether it is shown in a `modal`, a `dropdown` or a `sheet`, to adjust its layout.
* `useOverlayClose()` closes the layer it is in, as emitting `close:modal` does — for content deeper than the root, such as a step's own Cancel button.
* `useLayerBusy(() => loading.value)` keeps the layer open on Escape, outside clicks, swipes and a removed anchor while something runs.

A dropdown closes when the opener unmounts, unless it took a menu's place; a modal stays.

The frame owns the layout around the content. A component built on `WModalWrapper` opens as a modal, a dropdown or a bottom sheet unchanged: the frame takes its `title`, `subtitle` and `actions` and places them — a sticky header and footer in a modal, a compact heading and pinned buttons in a dropdown, a centered title and stacked buttons in a sheet — and pads the body by `--w-frame-padding`. The content brings no padding of its own; what reaches the edges, such as a list, takes `w-frame-bleed`. Outside an overlay, `WModalWrapper` lays the same parts out on the page. Content without it, such as a menu, is shown edge to edge; `useOverlayFrameOptions(() => ({padded: true}))` asks for the padding.

A `WUniform` with `api-method` keeps its layer open while it saves, and in a modal asks before the close button discards unsaved changes. A dropdown is dismissed without asking, as a menu is — keep forms in it small enough to fill again. `useLayerBusy` and `useLayerChanges` do the same for other content.

```ts
import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'

const overlay = useOverlay()

const openNotes = (event: MouseEvent) => {
  overlay.open({
    present: 'dropdown',
    anchor: event.currentTarget as Element,
    content: markRaw(WPlantNotes),
    props: {plantId: 42},
  })
}
```

## Custom modal

`Modal.add(component, props)` opens any component. Wrap its content in `WModalWrapper`, which provides the title, a scrolling body and a sticky footer with the actions. Its padding comes from `--w-modal-wrapper-padding`, set once for the app (`w-modal-wrapper-p---inner-margin` on `body`), and the frame pads the title, the body and the actions with it — the content brings no padding of its own. Content that reaches the edges, such as a list, takes `w-frame-bleed`; WTabs and WInfoCard do it on their own. Give the action buttons `w-full` to share the footer width. The modal closes when it emits `close:modal`, when the backdrop's close button is clicked, or when the function returned by `Modal.add` is called.

Pass callbacks as props to get results back. Load the modal with `defineAsyncComponent`, so its code is fetched on first open, and wrap it in `markRaw`, as for every component passed as a prop.

```vue
<template>
  <WButton @click="rename">
    Rename “{{ name }}”
  </WButton>
</template>

<script lang="ts" setup>
import {defineAsyncComponent, markRaw, ref} from 'vue'

import {Modal} from 'eco-vue-js/dist/utils/Modal'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

// Loaded on first open, so the modal's code stays out of the page bundle.
const RenameModal = defineAsyncComponent(() => import('./parts/RenameModal.vue'))

const name = ref('Herb bed')

const rename = () => {
  Modal.add(markRaw(RenameModal), {
    name: name.value,
    onSave: (value: string) => name.value = value,
  })
}
</script>
```

```vue [RenameModal.vue]
<template>
  <WModalWrapper>
    <template #title>
      Rename
    </template>

    <WInput
      v-model="value"
      title="Name"
      autofocus
    />

    <template #actions>
      <WButton
        outline
        class="w-full"
        @click="$emit('close:modal')"
      >
        Cancel
      </WButton>

      <WButton
        :disabled="!value"
        class="w-full"
        @click="save"
      >
        Save
      </WButton>
    </template>
  </WModalWrapper>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WModalWrapper from 'eco-vue-js/dist/components/Modal/WModalWrapper.vue'

const props = defineProps<{
  name: string
  onSave: (name: string) => void
}>()

const emit = defineEmits<{
  (e: 'close:modal'): void
}>()

const value = ref<string | undefined>(props.name)

const save = () => {
  if (!value.value) return

  props.onSave(value.value)
  emit('close:modal')
}
</script>
```

If the modal body contains a form with unsaved changes, exposing it as `formRef` with a `hasChanges` flag makes the close button ask before discarding them.

## Steps

A stepper `WTabs` with `stepper-controls` inside a `WModalWrapper` is a wizard: one `WTabsItem` per step. It hands the modal the current step's title, a progress line under it, and the buttons — Close, or Cancel once something is changed, or Back, and Next or the submit. `validate` on an item runs before Next leaves it, and so do the Uniform fields inside the step — an error message is shown and the step stays open — and `requireSave` submits the form inside first. The last step's button submits the form with `api-method` around the stepper, or emits `submit`; `submitText` names it. `submitting` shows its spinner while a submit on `submit` runs, and `disabledNext` disables it, e.g. until something is picked. A template ref gives `next()` and `previous()`, to move on after a pick. The button texts come from `setTexts`, so an app translates them once.

`WModalStepper` is deprecated: it is the same wizard with its own buttons, without Cancel or the form's submit. Move to a `WModalWrapper` around `WTabs stepper no-header stepper-controls`:

| WModalStepper | Instead |
| --- | --- |
| `loading` | `submitting` on WTabs, or nothing inside a form with `api-method` |
| `disabledNext`, `submitText`, `disableMinHeight` | the same props on WTabs |
| `disabled` | `submitting`, or `disabled` on the items |
| `@submit` | `@submit` on WTabs, or the form's `api-method` |
| `@close:modal` on the first step | not needed: Close closes the modal it is in |
| `#title` | `#title` on WModalWrapper, which stays over the step's title |
| `next()`, `previous()` | the same methods of WTabs |

```vue
<template>
  <div class="flex flex-wrap items-center gap-4">
    <WButton @click="invite">
      Invite a member
    </WButton>

    <span
      v-if="invited"
      class="text-description"
    >
      Invited {{ invited }}
    </span>
  </div>
</template>

<script lang="ts" setup>
import {defineAsyncComponent, markRaw, ref} from 'vue'

import {Modal} from 'eco-vue-js/dist/utils/Modal'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

const InviteModal = defineAsyncComponent(() => import('./parts/InviteModal.vue'))

const invited = ref<string>()

const invite = () => {
  Modal.add(markRaw(InviteModal), {
    onInvite: (email: string, role: string) => invited.value = `${ email } as ${ role }`,
  })
}
</script>
```

```vue [InviteModal.vue]
<template>
  <!-- The stepper brings the title, the progress and the buttons; the wrapper hands them to the modal. -->
  <WModalWrapper
    maximized
    class="w-modal-wrapper-w-160"
  >
    <WTabs
      :submitting="sending"
      submit-text="Send invite"
      stepper
      no-header
      stepper-controls
      @submit="send"
    >
      <WTabsItem
        title="Who to invite"
        name="email"
        :validate="() => email ? undefined : 'Enter an email to invite'"
      >
        <WInput
          v-model="email"
          title="Email"
          type="email"
          autofocus
          class="pt-4"
        />
      </WTabsItem>

      <WTabsItem
        title="Role"
        name="role"
      >
        <WButtonGroup
          v-model="role"
          :list="ROLES"
          title="Role"
          class="pt-4"
        >
          <template #option="{option}">
            {{ option }}
          </template>
        </WButtonGroup>
      </WTabsItem>

      <WTabsItem
        title="Check and send"
        name="summary"
      >
        <p class="pt-4">
          {{ email }} will join as {{ role }}.
        </p>
      </WTabsItem>
    </WTabs>
  </WModalWrapper>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WModalWrapper from 'eco-vue-js/dist/components/Modal/WModalWrapper.vue'
import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'

const ROLES = ['Viewer', 'Editor', 'Admin']

const props = defineProps<{
  onInvite: (email: string, role: string) => void
}>()

const emit = defineEmits<{
  (e: 'close:modal'): void
}>()

const email = ref<string>()
const role = ref('Viewer')
const sending = ref(false)

const send = () => {
  sending.value = true

  setTimeout(() => {
    props.onInvite(email.value!, role.value)
    emit('close:modal')
  }, 800)
}
</script>
```

## Export and import

`WModalExport` and `WModalImport` are the modals behind the list's export and import. `WModalExport` loads every item of a query page by page — or with `apiMethod` in one request — with a progress bar, builds a JSON, CSV or Markdown file and offers it for download. `WModalImport` creates a list of items with `createMethod`, all at once, with a progress bar and a button that aborts the requests still running. Open them with `Modal.add` like any modal.

## API

### WModalWrapper

```ts
import WModalWrapper from 'eco-vue-js/dist/components/Modal/WModalWrapper.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `maximized` | `boolean` | — | Fills the whole screen on small screens instead of floating with a margin. |
| `actionsCol` | `boolean` | — | Stacks the `actions` buttons vertically on every screen size, not only on small ones. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `title` | — | Heading of the dialog, also used as its accessible name. Stays pinned at the top while the content scrolls. |
| `subtitle` | — | Content under the heading, pinned with it. |
| `default` | — | Body of the modal. |
| `actions` | — | Buttons pinned at the bottom. |

### WModal

```ts
import WModal from 'eco-vue-js/dist/components/Modal/WModal.vue'
```

#### Props

*No props.*

### WModalStepper

```ts
import WModalStepper from 'eco-vue-js/dist/components/Modal/WModalStepper.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` | `boolean` | — | Shows a spinner in the Next or Submit button and disables Back and Close, e.g. while the form submits. |
| `disabled` | `boolean` | — | Disables all the buttons. |
| `disabledNext` | `boolean` | — | Disables the Next or Submit button, e.g. until something is picked on the step. |
| `submitText` | `string` | — | Text of the submit button on the last step. Defaults to "Submit". |
| `disableMinHeight` | `boolean` | — | Lets the modal shrink to the current step's height. By default it keeps the height of the tallest step shown so far. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close:modal` | — | Close was clicked on the first step. |
| `submit` | — | Submit was clicked on the last step. |
| `update:has-changes` | `(value: boolean)` | Whether a form inside has unsaved changes, for the modal to ask before closing. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | The steps, as WTabsItem items. Their `validate`, `hasValue` and `requireSave` work as in a stepper WTabs. |
| `title` | — | Replaces the title, which is the current step's title by default. |

### WModalExport

```ts
import WModalExport from 'eco-vue-js/dist/components/Modal/WModalExport.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `format` | `"json" \| "csv" \| "md"` | **required** | Format of the file: the items as JSON, rows of CSV, or Markdown sections. |
| `fileName` | `string` | — | Start of the file name, before the date. |
| `title` | `string \| ((count: number) => string)` | — | Title of the modal, or a function of the number of items. Defaults to one that names the format. |
| `cancelText` | `string` | — | Text of the close button. Defaults to "Close". |
| `downloadText` | `string` | — | Text of the download button. Defaults to "Download". |
| `useQueryFn` | `UseQueryDefault<PaginatedResponse<Model>, QueryParams> \| UseQueryDefault<Model[], QueryParams>` | — | Query the items are loaded with, page by page when it is paginated. |
| `initQueryParams` | `QueryParams` | **required** | Params of the query or `apiMethod`, such as the list's filters. |
| `apiMethod` | `((queryParams: QueryParams) => Promise<Model[]>)` | — | Loads all the items in one request, instead of `useQueryFn`. |
| `header` | `string[]` | — | Header row of the CSV. |
| `prepare` | `((item: Model, index: number) => string[][] \| Promise<string[][]>)` | — | Rows of the CSV for an item. Needed for `csv`. |
| `toMarkdown` | `((item: Model, index: number) => string)` | — | Markdown of an item. Needed for `md`. |
| `resolve` | `(() => void)` | — | Called once the file is downloaded. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close:modal` | — | The file was downloaded, or the modal was closed. |

### WModalImport

```ts
import WModalImport from 'eco-vue-js/dist/components/Modal/WModalImport.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `createMethod` | `(item: Item, config: RequestConfig<RequestData>) => Promise<RequestResponse<unknown, RequestData>>` | **required** | Creates one item. All items are sent at once; `config.signal` aborts a request. |
| `items` | `Item[]` | **required** | Items to create. |
| `title` | `string` | — | Title of the modal. Defaults to "Importing N items". |
| `successText` | `string` | — | Text of the button once every item is sent. Defaults to "Done". |
| `abortText` | `string` | — | Text of the button while items are being sent. Defaults to "Abort upload". |
| `resolve` | `(() => void)` | — | Called when every item is sent, or when the modal is closed after that. |
| `reject` | `((length: number) => void)` | — | Called with the number of aborted requests when the upload is aborted. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `close:modal` | — | Every item was sent, or the button was clicked. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/notify.md
description: >-
  Showing success, warning, error and in-progress notifications with Notify —
  title, caption, the user's input, a link and custom content, merged when
  repeated — and their history in the notify center with WNotifyCenter and
  WNotifyCenterButton.
---

# Notify

Notifications are shown from code, from anywhere — setup, a store, a query's error handler. `Notify.success`, `Notify.warn` and `Notify.error` add one to the `WNotify` container mounted once at the app root (see [Getting started](/guide/getting-started#global-containers)); before it is mounted, the calls do nothing.

```vue
<template>
  <div class="flex flex-wrap gap-4">
    <WButton
      :semantic-type="SemanticType.POSITIVE"
      @click="Notify.success({title: 'Project saved'})"
    >
      Success
    </WButton>

    <WButton
      :semantic-type="SemanticType.WARNING"
      @click="Notify.warn({title: 'Form contains invalid values', caption: 'Name is required.'})"
    >
      Warning
    </WButton>

    <WButton
      :semantic-type="SemanticType.NEGATIVE"
      @click="Notify.error({title: 'Upload failed', caption: 'The file is larger than 10 MB.', userInput: 'annual-report-final-v2.pdf'})"
    >
      Error
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {Notify} from 'eco-vue-js/dist/utils/Notify'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
</script>
```

Each call takes:

| Field | What it is |
| --- | --- |
| `title` | The message, as a string or a VNode. |
| `caption` | A second line with details. |
| `userInput` | What the user typed or picked, shown after the caption and broken anywhere to fit — a file name, a search term. |
| `to` | A route; the notification links to it, titled with the route's `meta.title`. |
| `channel` | `NotifyChannel.ACTIVITY` (the default) or `NotifyChannel.ACTION` — see [Notify center](#notify-center). |
| `group` | Shows notifications with the same group `key` as one entry — see [Groups](#groups). |
| `key` | Shows it once: the same key again returns the notification already there, and nothing comes back after the user closed it. |
| `toast` | `false` adds it to the notify center without a toast. |
| `component`, `componentProps` | Content under the caption — see [Custom content](#custom-content). |
| `onRemove` | Called when the user closes it. |

A toast closes after 5 seconds, unless it is in progress or needs the user. While the pointer is over the toasts, none of them close: their time stops and goes on from where it was once the pointer leaves. The same notification shown again within those 5 seconds doesn't stack: the one on screen stays, gets a counter, and its 5 seconds start over. Clicking the same failing button five times shows one error with a 5 on it.

Toasts show in the top right corner, under the header. `position` on `WNotify` moves them to `top-center`, `bottom-right` or `bottom-center`; at the bottom the newest toast is closest to the edge. On phones every position shows at the top edge of the screen, over the header or a modal's title — the bottom holds the buttons of a modal, a sheet or a page.

The kit shows notifications itself in a few places: copying and pasting, invalid form values when leaving a tab or submitting a form, a `validate` error in `WToggle`, and failed requests made through its API helpers.

## Progress

`Notify.process` shows something in progress with a spinner. Every call returns the notification's id — or `undefined` before `WNotify` is mounted — and `Notify.update` changes it later. Its toast stays on screen until then, and once it gets another type the toast shows again with the result — even after the user closed it — and closes after 5 seconds like any other. `Notify.remove` takes it away without calling `onRemove`.

```vue
<template>
  <WButton
    :semantic-type="SemanticType.PRIMARY"
    @click="water"
  >
    Water the greenhouse
  </WButton>
</template>

<script lang="ts" setup>
import {Notify, NotifyType} from 'eco-vue-js/dist/utils/Notify'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

const water = () => {
  const id = Notify.process({title: 'Watering 12 plants', caption: 'Greenhouse A'})

  if (id === undefined) return

  setTimeout(() => Notify.update(id, {type: NotifyType.SUCCESS, title: '12 plants watered'}), 3000)
}
</script>
```

A pending notification can't be closed in the notify center; closing its toast only hides the toast.

## Notify center

Every notification is also kept in a history of the last 50, shown by `WNotifyCenter`. `WNotifyCenterButton` is a bell for the [actions bar](/guide/app-shell) that opens it as a dropdown — a bottom sheet on phones. It counts the notifications that need action and runs a shimmer while any is pending. Toasts are hidden while the center is open. The center opens under the button with a tip; `horizontal-align` places it otherwise. `HorizontalAlign.LEFT_INNER` suits a bell at the right end of the header — it grows left from the button's right edge, without a tip. `HorizontalAlign.LEFT_CENTER` suits a bell in a side rail — it opens beside the button with the tip pointing at it, and near the top or bottom of the screen only the box shifts, keeping a margin from the edge.

```vue
<template>
  <WActionsBar>
    <WNotifyCenterButton>
      <template #footer>
        <WButton
          :to="{name: 'operations'}"
          :semantic-type="SemanticType.SECONDARY"
          @click="closeNotifyCenter"
        >
          All operations
        </WButton>
      </template>
    </WNotifyCenterButton>
  </WActionsBar>
</template>

<script lang="ts" setup>
import {closeNotifyCenter} from 'eco-vue-js/dist/utils/NotifyCenter'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WActionsBar from 'eco-vue-js/dist/components/ActionsBar/WActionsBar.vue'
import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WNotifyCenterButton from 'eco-vue-js/dist/components/Notify/WNotifyCenterButton.vue'
</script>
```

For a trigger of your own, such as the bell in this site's header, open it with `useNotifyCenter`, called in setup. It returns `isOpen`, `open(anchor)`, `close` and `toggle(anchor)`, and takes the center's props, footer and `horizontalAlign`:

```ts
import {HorizontalAlign} from 'eco-vue-js/dist/utils/HorizontalAlign'
import {useNotifyCenter} from 'eco-vue-js/dist/utils/NotifyCenter'

const {isOpen, toggle} = useNotifyCenter({
  props: () => ({title: 'Alerts'}),
  horizontalAlign: () => HorizontalAlign.LEFT_INNER,
})
```

`WNotifyCenter` can also be placed on a page as it is. Notifications on the `ACTION` channel need the user: they are pinned on top under their own heading, their toast stays until closed, and clearing the history keeps them — as it keeps pending ones.

```vue
<template>
  <div class="grid items-start gap-4 sm:grid-cols-[auto_1fr]">
    <div class="flex flex-wrap gap-2 sm:flex-col">
      <WButton
        :semantic-type="SemanticType.POSITIVE"
        @click="Notify.success({title: 'Repotted', caption: 'The monstera moved to a 30 cm pot.'})"
      >
        Activity
      </WButton>

      <WButton
        :semantic-type="SemanticType.NEGATIVE"
        @click="Notify.error({title: 'Sensor offline', caption: 'The greenhouse probe stopped reporting.', channel: NotifyChannel.ACTION})"
      >
        Needs action
      </WButton>

      <WButton
        :semantic-type="SemanticType.WARNING"
        @click="checkSoil"
      >
        Group
      </WButton>
    </div>

    <WNotifyCenter />
  </div>
</template>

<script lang="ts" setup>
import {Notify, NotifyChannel} from 'eco-vue-js/dist/utils/Notify'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WNotifyCenter from 'eco-vue-js/dist/components/Notify/WNotifyCenter.vue'

const DRY_SOIL_GROUP = {key: 'dry-soil', title: 'Soil is dry', caption: 'These beds need water.'}

const checkSoil = () => {
  ['Bed 1', 'Bed 4', 'Bed 7'].forEach(bed => {
    Notify.warn({title: 'Soil is dry', caption: bed, group: DRY_SOIL_GROUP})
  })
}
</script>
```

### Groups

Notifications with the same `group.key` show as one entry while there are two or more of them — in a toast and in the center — with the group's `title` and `caption`, the most severe type of its members, and a list of them to expand, newest first. A member is never merged into a repeat of itself — every one adds to the list, and the group's toast stays up for 5 seconds after its latest member. Closing the entry closes each member, or calls the group's `onRemoveItems` with all of them at once. A group's `component` gets its `items` along with `componentProps`.

## Custom content

`component` renders under the caption with `componentProps`, such as the progress of a background operation. It may emit `update` with new fields — `title`, `caption`, `type`, `channel` or `group` — and `remove` to take the notification away; type its emits with `NotifyContentEmits` from `eco-vue-js/dist/utils/Notify`. In a group's list it gets `compact`.

The toast and the center each render their own copy, so keep the state outside the component — in a query or a reactive object — rather than in it.

```vue
<template>
  <WButton
    :semantic-type="SemanticType.PRIMARY"
    @click="repot"
  >
    Repot the seedlings
  </WButton>
</template>

<script lang="ts" setup>
import {reactive} from 'vue'

import {Notify} from 'eco-vue-js/dist/utils/Notify'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

import NotifyRepotProgress from './parts/NotifyRepotProgress.vue'

const repot = () => {
  const task = reactive({done: 0, total: 8})

  Notify.process({title: 'Repotting seedlings', component: NotifyRepotProgress, componentProps: {task}})

  const interval = setInterval(() => {
    task.done++

    if (task.done === task.total) clearInterval(interval)
  }, 500)
}
</script>
```

## API

### WNotify

```ts
import WNotify from 'eco-vue-js/dist/components/Notify/WNotify.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `NotifyPosition` | `"top-right"` | Corner or edge of the screen the toasts show in. On top they sit under the header (`--header-height`); new toasts stack away from the edge. On phones they always show at the top edge, over the header or a modal's title, clear of the buttons at the bottom and the fields under the header. |

### WNotifyCenter

```ts
import WNotifyCenter from 'eco-vue-js/dist/components/Notify/WNotifyCenter.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Heading of the notify center. Defaults to `Notifications`. |
| `clearText` | `string` | — | Text of the button that clears the history. Defaults to `Clear`. |
| `emptyText` | `string` | — | Shown when there are no notifications. Defaults to `No notifications yet`. |
| `actionText` | `string` | — | Heading of the notifications that need action (`NotifyChannel.ACTION`). Defaults to `Action required`. |
| `activityText` | `string` | — | Heading of the rest of the history, shown under the ones that need action. Defaults to `Activity`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `footer` | — | Under the list, such as a link to a page with every operation. Close the center from it with `closeNotifyCenter`. |

### WNotifyCenterButton

```ts
import WNotifyCenterButton from 'eco-vue-js/dist/components/Notify/WNotifyCenterButton.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | Tooltip of the button and heading of the notify center. Defaults to `Notifications`. |
| `icon` | `SVGComponent` | — | Icon of the button. Defaults to a bell. |
| `horizontalAlign` | `HorizontalAlign` | — | Aligns the notify center to the button — such as `HorizontalAlign.LEFT_INNER` to grow left from its right edge, without a tip, or `HorizontalAlign.LEFT_CENTER` beside it with a tip, for a button in a side rail. Defaults to centered under the button with a tip. |
| `clearText` | `string` | — | Text of the button that clears the history. Defaults to `Clear`. |
| `emptyText` | `string` | — | Shown when there are no notifications. Defaults to `No notifications yet`. |
| `actionText` | `string` | — | Heading of the notifications that need action (`NotifyChannel.ACTION`). Defaults to `Action required`. |
| `activityText` | `string` | — | Heading of the rest of the history, shown under the ones that need action. Defaults to `Activity`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `footer` | — | Footer of the notify center. Close the center from it with `closeNotifyCenter`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/tooltip.md
description: >-
  WTooltip — a hover tooltip placed inside the element it describes, with text
  or rich content, placement, delay and overflow-only mode.
---

# Tooltip

`WTooltip` goes *inside* the element it describes and opens while the pointer is over that element — its parent. It renders nothing in place: the tooltip itself is drawn by the `WTooltipContainer` mounted once at the app root (see [Getting started](/guide/getting-started#global-containers)), so it is never clipped by an `overflow: hidden` ancestor.

```vue
<template>
  <div class="flex flex-wrap items-center gap-6">
    <span class="cursor-help underline decoration-dotted">
      Hardy
      <WTooltip text="Survives winters outdoors down to −15 °C." />
    </span>

    <span class="cursor-help underline decoration-dotted">
      On the right
      <WTooltip
        text="Placed to the right of its element."
        right
      />
    </span>

    <span class="cursor-help underline decoration-dotted">
      Rich content
      <WTooltip>
        <div class="grid gap-1">
          <b>Last watered</b>
          <span>2 days ago · 250 ml</span>
        </div>
      </WTooltip>
    </span>

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      tooltip-text="Buttons take the text as a prop."
    >
      Button
    </WButton>

    <span class="w-40 truncate">
      Monstera deliciosa 'Thai Constellation'
      <WTooltip
        text="Monstera deliciosa 'Thai Constellation'"
        overflow-only
      />
    </span>
  </div>
</template>

<script lang="ts" setup>
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WTooltip from 'eco-vue-js/dist/components/Tooltip/WTooltip.vue'
</script>
```

* **Content** is the `text` prop, or the default slot for markup. The slot stays reactive while the tooltip is open.
* **Placement** is above or below the element, whichever fits; `top` and `bottom` force one, `left` and `right` put it at the side.
* **`overflowOnly`** opens only when the parent's content is cut off — for truncated titles in narrow columns.
* **`delay`** waits that many milliseconds before opening.
* **`trigger`** listens on another element instead of the parent; `noTouch` skips the tooltip on touch devices.

The tooltip stays open while the pointer moves onto it, so its text can be selected and its links clicked; `static` makes it ignore the cursor instead, so it closes as soon as the pointer leaves the element. Use it for short hints, where a tooltip that holds on to the cursor only gets in the way of the content under it.

Many components take a `tooltipText` prop that does the same without a child — `WButton`, `WCheckbox`, `WButtonMoreItem` and others.

## API

### WTooltip

```ts
import WTooltip from 'eco-vue-js/dist/components/Tooltip/WTooltip.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | — | Plain text content, shown on one line. The default slot takes precedence. Nothing opens when both are empty. |
| `noTouch` | `boolean` | — | Skips the tooltip entirely on touch devices. |
| `overflowOnly` | `boolean` | — | Opens only when the trigger's content overflows it — for truncated text. |
| `trigger` | `Element` | — | Element that opens the tooltip on hover. Defaults to the tooltip's parent element. |
| `noTrigger` | `boolean` | — | Attaches no hover listeners; open and close it through the exposed `open` and `close`. |
| `top` | `boolean` | — | Prefers placing the tooltip above the parent. |
| `bottom` | `boolean` | — | Prefers placing the tooltip below the parent. |
| `left` | `boolean` | — | Places the tooltip to the left of the parent. |
| `right` | `boolean` | — | Places the tooltip to the right of the parent. |
| `static` | `boolean` | — | Makes the tooltip ignore the cursor, so it closes when the pointer leaves the trigger and its content cannot be interacted with. For small hints that would otherwise block content underneath. |
| `delay` | `number` | — | Milliseconds to wait on hover before opening. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Rich tooltip content, replacing `text`. It stays reactive while the tooltip is open. |

### WTooltipContainer

```ts
import WTooltipContainer from 'eco-vue-js/dist/components/Tooltip/WTooltipContainer.vue'
```

#### Props

*No props.*

---

---
url: https://rsmple.github.io/eco-vue-js/components/border-svg.md
description: >-
  WBorderSvg — a border drawn as SVG over a positioned element, for dashes a CSS
  border can't do or a border that moves.
---

# Border SVG

`WBorderSvg` draws a border as SVG over a positioned element — for dashes that a CSS border can't do, or a border that moves, as on the [file picker](/components/file-picker)'s drop zone while a file is dragged over the page.

`stroke` sets the color — `currentColor` follows the text color — and `strokeDasharray` the dashes. An `animate` element in the default slot animates the border, usually its `stroke-dashoffset`. Utilities from the kit's Tailwind base set the rest:

* `w-border-svg-rounded-*` — corner radius, to match the element's.
* `w-border-svg-stroke-*` — line width in pixels, 2 by default, e.g. `w-border-svg-stroke-3`.
* `w-border-svg-padding-*` — its inset.

```vue
<template>
  <div class="flex flex-wrap gap-6">
    <div class="text-description relative flex h-28 w-48 items-center justify-center text-sm">
      Dashed

      <WBorderSvg
        stroke="currentColor"
        stroke-dasharray="6px 6px"
        class="w-border-svg-rounded-xl"
      />
    </div>

    <div class="tone-primary text-tone relative flex h-28 w-48 items-center justify-center text-sm">
      Moving

      <WBorderSvg
        stroke="currentColor"
        stroke-dasharray="8px 6px"
        stroke-linecap="round"
        class="w-border-svg-rounded-xl w-border-svg-stroke-3"
      >
        <animate
          attributeName="stroke-dashoffset"
          from="0"
          to="-28"
          dur="1s"
          repeatCount="indefinite"
        />
      </WBorderSvg>
    </div>

    <div class="tone-positive surface-fill relative flex h-28 w-48 items-center justify-center rounded-xl text-sm">
      Dotted

      <WBorderSvg
        stroke="currentColor"
        stroke-dasharray="2px 4px"
        stroke-linecap="round"
        class="text-tone w-border-svg-rounded-2xl"
      />
    </div>
  </div>
</template>

<script lang="ts" setup>
import WBorderSvg from 'eco-vue-js/dist/components/BorderSvg/WBorderSvg.vue'
</script>
```

## API

### WBorderSvg

```ts
import WBorderSvg from 'eco-vue-js/dist/components/BorderSvg/WBorderSvg.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stroke` | `string` | — | Color of the border, e.g. `currentColor`. |
| `strokeDasharray` | `string` | — | Dash pattern of the border, e.g. `4px 8px`. |
| `strokeDashoffset` | `string` | — | Offset of the dash pattern, e.g. to animate it. |
| `strokeLinecap` | `"butt" \| "round" \| "square" \| "inherit"` | — | Shape of the dashes' ends. |
| `rectClass` | `string` | — | Class of the border's `rect`. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | SVG animation elements for the border, such as an `animate` of `stroke-dashoffset`. |

---

---
url: https://rsmple.github.io/eco-vue-js/components/click-outside.md
description: >-
  WClickOutside — emits click on a click or right-click anywhere outside it, to
  close or finish what's inside.
---

# Click outside

`WClickOutside` wraps content in a `div` and emits `click` on a click or right-click anywhere outside it — to close a custom dropdown, or to finish editing in place. The click that mounted it doesn't count, so it can wrap content that a click just opened. `noFilter` emits on clicks inside too.

[WDropdownMenu](/components/dropdown-menu#custom-dropdown) leaves its state to the parent, which usually closes it with a `WClickOutside` around the content.

```vue
<template>
  <div class="grid max-w-md gap-4">
    <WClickOutside
      class="rounded-xl border border-solid p-4"
      :class="active ? 'tone-primary border-tone' : 'border-line-subtle'"
      @click="clickOutside"
    >
      <button
        class="w-full cursor-pointer text-left"
        @click="active = true"
      >
        {{ active ? 'Editing — click anywhere else to finish' : 'Click to edit' }}
      </button>
    </WClickOutside>

    <span class="text-description text-sm">Clicks outside the card: {{ count }}</span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WClickOutside from 'eco-vue-js/dist/components/ClickOutside/WClickOutside.vue'

const active = ref(false)
const count = ref(0)

const clickOutside = () => {
  active.value = false
  count.value++
}
</script>
```

## API

### WClickOutside

```ts
import WClickOutside from 'eco-vue-js/dist/components/ClickOutside/WClickOutside.vue'
```

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `noFilter` | `boolean` | — | Emits `click` on clicks inside the element too. |

#### Events

| Event | Payload | Description |
| --- | --- | --- |
| `click` | `(event: Event)` | A click or right-click outside the element. Clicks in the same tick as mounting, such as the one that opened it, and presses that start inside, such as a drag let go outside, are ignored. |
| `mouseenter` | `(value: MouseEvent)` | The pointer entered the element. |
| `mouseleave` | `(value: MouseEvent)` | The pointer left the element. |
| `mousedown` | `(value: MouseEvent)` | A mouse button was pressed on the element. |

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Content that clicks count as inside of, such as a dropdown's content. |

---

---
url: https://rsmple.github.io/eco-vue-js/utilities/composables.md
description: >-
  Composables from eco-vue-js — useCopy for the clipboard, useComponentStates
  for inherited readonly, disabled and skeleton states, useIsMobile,
  useTabActiveListener and useOptionalRouter.
---

# Composables

Composables the kit's components are built on, for building your own components the same way. Each is imported from its own file under `eco-vue-js/dist/utils/` or `eco-vue-js/dist/composables/`.

## Clipboard

```ts
import {doCopy, useCopy} from 'eco-vue-js/dist/utils/useCopy'
```

`useCopy(value)` copies a ref or getter to the clipboard and reports it with a notification: "Copied", "Nothing to copy" for an empty value, or "Copy failed" with a hint to allow clipboard access for the site. It returns `doCopy`, `copied` — `true` for a second after a copy — and `iconCopy`, the copy icon that turns into a check while `copied`. `doCopy(text)` is the same without the state, and resolves to whether the copy succeeded.

The notifications need [`WNotify`](/components/notify) mounted at the app root.

```vue
<template>
  <div class="flex max-w-md items-end gap-2">
    <WInput
      v-model="code"
      title="Invite code"
      no-margin
      class="flex-1"
    />

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      :aria-label="copied ? 'Copied' : 'Copy'"
      @click="doCopy"
    >
      <component
        :is="iconCopy"
        class="square-5"
      />
    </WButton>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {useCopy} from 'eco-vue-js/dist/utils/useCopy'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'

const code = ref<string | undefined>('GREEN-THUMB-2026')

const {copied, iconCopy, doCopy} = useCopy(code)
</script>
```

## Component states

```ts
import {useComponentStates, useComponentStatesButton, useComponentStatesSkeleton} from 'eco-vue-js/dist/utils/useComponentStates'
import {useProvideDisabled, useProvideReadonly, useProvideSkeleton} from 'eco-vue-js/dist/utils/provide'
```

The kit's controls take `readonly`, `disabled` and `skeleton` from the nearest parent that provides them, unless the prop is set — see [Conventions](/guide/conventions#disabled-readonly-and-skeleton-are-inherited). Your own components can do the same:

* **`useComponentStates(props)`** returns `isReadonly`, `isDisabled` and `isSkeleton`: the prop when it is set, the provided state otherwise. Declare the props as optional booleans, so that unset stays `undefined` rather than `false`.
* **`useComponentStatesButton(props)`** is the version for buttons, which have no readonly state: `isDisabled` is also `true` inside a readonly parent.
* **`useComponentStatesSkeleton(props)`** returns only `isSkeleton`, for display components.
* **`useProvideReadonly(value)`**, **`useProvideDisabled(value)`** and **`useProvideSkeleton(value)`** provide a state — a boolean or a ref — to everything inside the calling component, and return the state provided above it. Called without a value they only read it.

```vue
<template>
  <div class="grid max-w-md gap-4">
    <div class="flex flex-wrap gap-x-6">
      <WToggle
        v-model="readonly"
        title="Readonly"
      />

      <WToggle
        v-model="skeleton"
        title="Skeleton"
      />
    </div>

    <PlantShelf
      :readonly="readonly"
      :skeleton="skeleton"
    >
      <PlantBadge
        v-for="name in plants"
        :key="name"
        :name="name"
        @water="watered = name"
      />

      <PlantBadge
        name="Cactus"
        :readonly="false"
        @water="watered = 'Cactus'"
      />
    </PlantShelf>

    <span
      v-if="watered"
      class="text-description text-sm"
    >
      Watered {{ watered }}
    </span>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

import PlantBadge from './parts/PlantBadge.vue'
import PlantShelf from './parts/PlantShelf.vue'

const plants = ['Basil', 'Fern']

const readonly = ref(false)
const skeleton = ref(false)
const watered = ref<string>()
</script>
```

## Screen size

```ts
import {getIsMobile, getIsTablet, getIsTouchDevice, setIsTouchDeviceInit, useIsMobile} from 'eco-vue-js/dist/utils/mobile'
```

`useIsMobile()` returns `isMobile` (below `sm`, 640px) and `isTablet` (below `xl`, 1280px) as computed refs, kept up to date on resize. Both are `false` until the component mounts, so the server render and the first client render match. `getIsMobile()` and `getIsTablet()` read the same once, without reactivity.

`getIsTouchDevice()` tells whether the device has a touch screen; tooltips with `noTouch` use it to stay closed. `setIsTouchDeviceInit(value)` overrides it, e.g. in tests.

## Tab activation

```ts
import {useTabActiveListener} from 'eco-vue-js/dist/utils/useTabActiveListener'
```

`useTabActiveListener(listener)` calls `listener` whenever the [tab](/components/tabs) the component is in becomes active — for something to do once it is in view, such as focusing a field: inputs with `autofocus` use it to take focus when their tab opens. Outside tabs it does nothing.

## Optional router

```ts
import {useOptionalRoute, useOptionalRouter} from 'eco-vue-js/dist/composables/useOptionalRouter'
```

The kit works with or without vue-router. `useOptionalRouter()` returns the app's router when it has one, and otherwise a fallback with the same `push`, `replace` and `resolve`, which navigates by changing `location`. `useOptionalRoute()` likewise returns the current route, or one read from `location` — `name` is then the path. Both have `noRouter: true` when they are the fallback. Use them in components that should work in apps without vue-router, as [`WNavItem`](/components/nav-bar) does.

---

---
url: https://rsmple.github.io/eco-vue-js/components/empty-component.md
description: >-
  WEmptyComponent — renders its slot without an element, as the "off" branch of
  an optional wrapper.
---

# Empty component

`WEmptyComponent` renders its default slot and nothing else — no element, no attributes. It is the "off" branch of an optional wrapper, so the content is written once:

```vue
<component :is="scroll ? WTextOverflow : WEmptyComponent">
  <span>{{ name }}</span>
</component>
```

The kit uses it this way for tab titles that scroll on overflow, and for `WNumberFormatter` without a `tag`.

```vue
<template>
  <div class="grid max-w-60 gap-4">
    <WToggle
      v-model="scroll"
      title="Scroll long names on hover"
    />

    <div class="grid gap-2">
      <div
        v-for="name in names"
        :key="name"
        class="group/overflow grid rounded-lg bg-surface-muted px-3 py-2"
      >
        <component :is="scroll ? WTextOverflow : WEmptyComponent">
          <span
            class="whitespace-nowrap"
            :class="{truncate: !scroll}"
          >{{ name }}</span>
        </component>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {ref} from 'vue'

import WEmptyComponent from 'eco-vue-js/dist/components/EmptyComponent/WEmptyComponent.vue'
import WTextOverflow from 'eco-vue-js/dist/components/TextOverflow/WTextOverflow.vue'
import WToggle from 'eco-vue-js/dist/components/Toggle/WToggle.vue'

const names = [
  'Basil',
  'Monstera deliciosa \'Thai Constellation\'',
  'Ficus lyrata, fiddle-leaf fig from the north greenhouse',
]

const scroll = ref(true)
</script>
```

## API

### WEmptyComponent

```ts
import WEmptyComponent from 'eco-vue-js/dist/components/EmptyComponent/WEmptyComponent.vue'
```

#### Props

*No props.*

#### Slots

| Slot | Props | Description |
| --- | --- | --- |
| `default` | `{ [key: string]: never; }` | Content rendered without a wrapping element. It gets no slot props. |

---

---
url: https://rsmple.github.io/eco-vue-js/utilities/formatting.md
description: >-
  Date, duration and number formatting from eco-vue-js — dateFormat,
  durationFormat and date math in dateTime, the number and percent formatters,
  and buildCsvContent for CSV exports.
---

# Formatting

The functions the kit's components format values with, for the same output elsewhere in the app.

```vue
<template>
  <div class="grid gap-6">
    <div class="grid max-w-xl grid-cols-[auto_1fr] gap-x-6 gap-y-1 text-sm">
      <template
        v-for="row in rows"
        :key="row.code"
      >
        <code class="text-description">{{ row.code }}</code>
        <span class="font-semibold">{{ row.value }}</span>
      </template>
    </div>

    <div>
      <WButton
        :semantic-type="SemanticType.SECONDARY"
        @click="download"
      >
        Download plants.csv
      </WButton>
    </div>
  </div>
</template>

<script lang="ts" setup>
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {addDay, dateFormat, dateToQueryString, datetimeFormat, durationFormat} from 'eco-vue-js/dist/utils/dateTime'
import {buildCsvContent} from 'eco-vue-js/dist/utils/exportToCsv'
import {numberCompactFormatter, numberFormatter, percentFormatter} from 'eco-vue-js/dist/utils/utils'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'

const now = new Date()

const rows = [
  {code: 'dateFormat(now)', value: dateFormat(now)},
  {code: 'dateFormat(addDay(now, -3), {year: \'auto\'})', value: dateFormat(addDay(now, -3), {year: 'auto'})},
  {code: 'datetimeFormat(now, {year: \'auto\', seconds: false})', value: datetimeFormat(now, {year: 'auto', seconds: false})},
  {code: 'dateToQueryString(now)', value: dateToQueryString(now)},
  {code: 'durationFormat(5400)', value: durationFormat(5400)},
  {code: 'durationFormat(5400, {style: \'long\'})', value: durationFormat(5400, {style: 'long'})},
  {code: 'durationFormat(200000, {style: \'long\', round: true})', value: durationFormat(200000, {style: 'long', round: true})},
  {code: 'numberFormatter.format(1234567.5)', value: numberFormatter.format(1234567.5)},
  {code: 'numberCompactFormatter.format(12840)', value: numberCompactFormatter.format(12840)},
  {code: 'percentFormatter.format(0.4375)', value: percentFormatter.format(0.4375)},
]

const plants = [
  {name: 'Monstera', watered: addDay(now, -2), note: 'Likes "bright, indirect" light'},
  {name: 'Fern', watered: addDay(now, -5), note: '=keep moist'},
]

// Values that start a formula are escaped, so the file is safe to open in a spreadsheet.
const download = () => {
  const content = buildCsvContent(
    plants.map(plant => [plant.name, dateToQueryString(plant.watered), plant.note]),
    ['Name', 'Watered', 'Note'],
  )

  const link = document.createElement('a')
  link.href = URL.createObjectURL(new Blob([content], {type: 'text/csv'}))
  link.download = 'plants.csv'
  link.click()
  URL.revokeObjectURL(link.href)
}
</script>
```

## Dates

```ts
import {addDay, dateFormat, durationFormat, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'
```

All of them work in local time, and format in the locale set with `setLocale` — `en-GB` by default. The examples are in `en-GB`.

```ts
import {setLocale} from 'eco-vue-js/dist/utils/locale'

setLocale(() => i18n.global.locale.value)
```

A getter is read as the value renders, so the text follows a change of locale.

| Function | Result |
| --- | --- |
| `dateFormat(date, {year?})` | `05 Oct 2026` — with the month name, so the date reads the same way in any locale. `year: 'auto'` drops the year when it is the current one: `05 Oct`. |
| `timeFormat(date, {seconds?})` | `14:30:05`, or `2:30:05 PM` in a locale with a 12-hour clock. `seconds: false` drops the seconds: `14:30`. |
| `datetimeFormat(date, {year?, seconds?})` | The date and the time, in the order and with the separator of the locale: `05 Oct 2026, 14:30:05`. Takes the options of both: `05 Oct, 14:30` with `{year: 'auto', seconds: false}`. |
| `todayFormat()` | `Today`, as a label. |
| `dateInputFormat(date)` | `05/10/2026` — the numeric date of the locale (`10/05/2026` in `en-US`), as [WInputDate](/components/input#date) shows it. `parseDateInput(text)` reads it back with any separators, or returns `undefined`. |
| `parseDateQuery(text)` | Reads `05.10.2026` in every locale, such as from a query param, or returns `undefined`. |
| `dateToQueryString(date)` | `2026-10-05`, the local date in ISO format, for a query param. |
| `durationFormat(seconds, {style?, round?})` | `1 hr 30 mins`, or `1 hour 30 minutes` with `style: 'long'`. Shows the largest part and the one right below it, so `10 mths` and `10 mins` can't be mixed up; `round: true` keeps only the largest part, rounded: `2 hrs`. |
| `getDurationRound(seconds)` | Rounds a duration up to a step that reads well — 10 seconds, a minute, 10 minutes, an hour, a day and so on. |

Date math returns a new `Date` and leaves the one passed in as it was:

* `getStartOfDay`, `getStartOfNextDay`, `getStartOfWeek` (Monday by default, or a `WeekDay`) and `getStartOfMonth` — each defaults to now.
* `addDay`, `addMonth` and `addYear` — the count can be negative.
* `isSameDate`, `isSameWeek`, `isSameMonth` and `isSameYear` compare two dates.

`weekdayShortFormatter`, `weekdayNarrowFormatter`, `monthShortFormatter` and `dateFormatter` format in the current locale, as the [date picker](/components/date-picker) and the heatmap do, and `WeekDay` and `Month` are enums of the JavaScript day and month numbers.

## Numbers

```ts
import {numberCompactFormatter, numberFormatter, percentFormatter} from 'eco-vue-js/dist/utils/utils'
```

These are what [`WNumberFormatter`](/components/number-formatter) shows. Each has a `format(value)`:

They format in the locale set with `setLocale`, and group thousands with a space in every locale, since a comma or a dot there reads as a decimal separator in other locales.

* `numberFormatter` — up to three decimals: `1 234 567.5`, or `1 234 567,5` in `ru`.
* `numberCompactFormatter` — compact notation: `13K`.
* `percentFormatter` and `percentCompactFormatter` — a fraction as a percentage: `43.75%`.

## CSV

```ts
import {buildCsvContent, escapeCsvValue} from 'eco-vue-js/dist/utils/exportToCsv'
```

`buildCsvContent(rows, header?)` joins rows of strings into CSV text, escaping each value with `escapeCsvValue`: values with a quote, comma or line break are quoted, and values that start like a formula (`=`, `+`, `-`, `@`) get a leading space, so that a spreadsheet doesn't run them. `dateFormatterCsv` and `numberFormatCsv` from `utils` format dates and decimal numbers the way spreadsheets in most locales read them.

For a list export with a progress bar, use [`WModalExport`](/components/modal#export-and-import).

---

---
url: https://rsmple.github.io/eco-vue-js/utilities/helpers.md
description: >-
  Plain helpers from eco-vue-js — validators for inputs and forms, URL param
  parsers, debounce and throttle, deep equality, scrolling, and browser setup
  such as preventDragFile and the scrollbar width.
---

# Helpers

Plain functions with no component state, imported from their own file under `eco-vue-js/dist/utils/`. For the data layer's helpers — queries, cache updates and pagination — see [Data layer](/guide/data-layer#lower-level-helpers).

## Validation

```ts
import {validateForbiddenRegexp, validateRequired, validateRequiredSymbols} from 'eco-vue-js/dist/utils/validate'
```

Validators return an error message, or `undefined` when the value is valid — the shape the `validate` prop of [inputs](/components/input#validation), toggles and [form](/components/form) fields takes.

* `validateRequired(value)` — "A value is required" for `undefined`, `null`, an empty string or an empty array.
* `validateForbiddenRegexp(regexp, value)` — names each forbidden character found, e.g. "whitespace". The regexp needs the `g` flag to find more than the first one.
* `validateRequiredSymbols(required, value)` — names each character of `required` missing from the value.

Bind the extra argument for a field: `:validate="value => validateForbiddenRegexp(/\s/g, value)"`.

## URL params

```ts
import {parseBoolean, parseIdList, parseInteger, parseString} from 'eco-vue-js/dist/utils/utils'
```

Parsers turn a value read from the URL back into its type, or `undefined` when it doesn't fit — `createUseQueryParams` takes one per param, see [Filters in the URL](/guide/data-layer#filters-in-the-url).

| Parser | Reads |
| --- | --- |
| `parseString`, `parseBoolean`, `parseInteger` | One value; a boolean is `true` or `false`. |
| `parseStringList`, `parseIntegerList`, `parseIdList` | A comma-separated list. `parseIdList` keeps positive integers only. |
| `parseSliceIndexes` | Two integers, `from,to`. |
| `parseJson(isValid)` | JSON, checked by the type guard passed in. |

`parseId` and `parseIndex` read an id (a positive integer) or an index (zero or more) from a route param, and return `NaN` otherwise; `isId`, `isIdArray` and `isIndex` are the matching type guards.

Sort orders are kept as `ordering=name,-created`: `parseOrdering` from `eco-vue-js/dist/utils/order` reads one into `{field, order}` items with `Order.ASC` or `Order.DESC`, and `encodeOrdering` writes them back.

## Functions

```ts
import {debounce, get, isEqualObj, set, throttle} from 'eco-vue-js/dist/utils/utils'
```

* `debounce(fn, delay = 200)` calls `fn` once calls stop for `delay` ms, with the last arguments. `throttle(fn, delay = 200)` calls it at once, then ignores calls for `delay` ms.
* `isEqualObj(a, b, exclude?, include?)` compares two objects deeply, e.g. a form's model with the saved one. Keys in `exclude` are skipped, and with `include` only those keys are compared. Arrays are equal when they have the same items in any order, and an empty array equals `null` or `undefined`; a key present in only one of them makes them differ.
* `isEqualArr(a, b)` compares two arrays of plain values, in any order.
* `get(data, path)` reads a nested value by a dotted path such as `'address.city'`, and `set(data, path, value)` writes one, creating the objects on the way that are missing.
* `genId()` returns a number unique within the page, e.g. for an element `id`.

## Scrolling

```ts
import {getScrollParent, scrollInParent} from 'eco-vue-js/dist/utils/utils'
```

* `scrollInParent(element, {block, behavior, ifNeeded})` scrolls only the nearest scrolling ancestor — or the page — to bring the element into view, where `scrollIntoView` would scroll every ancestor. `block` is `nearest` by default, or `start` or `center`; `ifNeeded` leaves an element that is already fully in view alone.
* `getScrollParent(node)` returns the nearest ancestor that scrolls, and `getAllScrollParents(node)` all of them.

## Browser

```ts
import {preventDragFile} from 'eco-vue-js/dist/utils/preventDragFile'
import {appendScrollbarStyles} from 'eco-vue-js/dist/utils/scrollbarStyles'
```

Call these once when the app starts:

* `preventDragFile()` stops the browser from opening a file dropped outside a drop zone, and keeps `isDragging` from the same file `true` while a file is dragged over the page — the [file picker](/components/file-picker)'s drop zone lights up with it.
* `appendScrollbarStyles()` sets `--scroll-bar-width` on `<html>` to the width of the page's scrollbar — 0 with overlay scrollbars. The kit subtracts it from the content box in modals, and layouts that must line up with the scrolled content can use it too.

`getIsClientSide()` is `false` during a server render, for code that touches `window` or `document`.

---

---
url: https://rsmple.github.io/eco-vue-js/components/shine.md
description: >-
  WShine and WShineEffect — the light that sweeps across action buttons every
  few seconds, driven by one effect mounted at the app root.
---

# Shine

`WShine` is the light that sweeps across the kit's action buttons every few seconds. Put it inside a positioned element; it takes its corners. Buttons add it on their own while they are enabled and not loading.

The sweep comes from one `WShineEffect` mounted at the app root, next to the [global containers](/guide/getting-started#global-containers) — without it, there is no shine. It is hidden on phones and in print.

```vue
<template>
  <div class="flex flex-wrap items-center gap-6">
    <WButton :semantic-type="SemanticType.PRIMARY">
      Water the plants
    </WButton>

    <div class="tone-positive surface-fill relative rounded-xl px-6 py-4 font-semibold">
      Harvest ready

      <WShine />
    </div>

    <!-- Mounted once at the app root; this site doesn't, so the demo mounts it for this page. -->
    <WShineEffect />
  </div>
</template>

<script lang="ts" setup>
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WShine from 'eco-vue-js/dist/components/Shine/WShine.vue'
import WShineEffect from 'eco-vue-js/dist/components/Shine/WShineEffect.vue'
</script>
```

## API

### WShine

```ts
import WShine from 'eco-vue-js/dist/components/Shine/WShine.vue'
```

#### Props

*No props.*

### WShineEffect

```ts
import WShineEffect from 'eco-vue-js/dist/components/Shine/WShineEffect.vue'
```

#### Props

*No props.*

---

---
url: https://rsmple.github.io/eco-vue-js/icons.md
description: >-
  Every icon shipped with eco-vue-js, with a searchable gallery and the import
  path for each.
---

# Icons

Icons are Vue functional components compiled from SVG. They inherit `currentColor` and are sized with classes:

```vue
<template>
  <IconAdd class="square-5 text-primary" />
</template>

<script setup lang="ts">
import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'
</script>
```

When passing an icon to a prop, wrap it in `markRaw` — `:icon="markRaw(IconAdd)"`.

## All icons

All 122 icons, importable as `import Name from 'eco-vue-js/dist/assets/icons/Name'`:

`IconAdd`, `IconAddCircle`, `IconAddSquare`, `IconAlarm`, `IconArchiveBook`, `IconArrow`, `IconBack`, `IconBold`, `IconBroom`, `IconCactus`, `IconCancel`, `IconCandle`, `IconCelery`, `IconChart`, `IconCheck`, `IconCheckCircle`, `IconCheckSecret`, `IconClose`, `IconCloseCircle`, `IconCloud`, `IconCloudSun`, `IconCloudSunPartial`, `IconCodeBlock`, `IconCodeInline`, `IconCopy`, `IconCopySuccess`, `IconCopyright`, `IconDanger`, `IconDangerSolid`, `IconDojo`, `IconDrag`, `IconDrop`, `IconEdit`, `IconEditCircle`, `IconEditSquare`, `IconElement`, `IconExport`, `IconEye`, `IconEyeSlash`, `IconFern`, `IconFilter`, `IconFilterRemove`, `IconFinding`, `IconFolder`, `IconFolderAdd`, `IconFolderCross`, `IconGrid`, `IconHeading`, `IconHealth`, `IconHealthcare`, `IconInfo`, `IconItalic`, `IconJira`, `IconKey`, `IconKeySquare`, `IconLayer`, `IconLink`, `IconLinkBold`, `IconLinkOutline`, `IconLinkedIn`, `IconList`, `IconListBullet`, `IconListCheckbox`, `IconListDecrease`, `IconListIncrease`, `IconListNumbered`, `IconListSettings`, `IconLock`, `IconLockOff`, `IconLogout`, `IconMarkdown`, `IconMenu`, `IconMinusCircle`, `IconMonstera`, `IconMoon`, `IconMore`, `IconNegate`, `IconNegativeInfo`, `IconNote`, `IconNotification`, `IconPalette`, `IconPaste`, `IconPlant`, `IconProfile`, `IconQuote`, `IconRadar`, `IconRange`, `IconRedo`, `IconRefresh`, `IconRuler`, `IconSave`, `IconSearch`, `IconSettings`, `IconShift`, `IconSlash`, `IconSnowflake`, `IconSort`, `IconSpinner`, `IconSprig`, `IconStar`, `IconStrikethrough`, `IconSuccess`, `IconSuccessSolid`, `IconSummary`, `IconSun`, `IconTable`, `IconTableCollapsed`, `IconTag`, `IconTask`, `IconThermometer`, `IconTime`, `IconTo`, `IconTrash`, `IconUnderline`, `IconUndo`, `IconUpload`, `IconUser`, `IconVersionControl`, `IconWarn`, `IconWarnSolid`, `IconWeight`, `IconWind`

---

---
url: https://rsmple.github.io/eco-vue-js/recipes/form-in-three-modes.md
description: >-
  One WUniform form component split into WTabs, used as a step-by-step wizard to
  create an item, as tabs in a modal to edit it, and on a page where every field
  saves on its own — with its title and buttons in WModalWrapper, which the
  frame it opens in places.
---

# Form in three modes

**Problem:** an item is created in a wizard, edited in a modal, and edited again on its own page, where each change saves at once. Three forms drift apart: a field added to one is missing from the others, and the validation differs.

**Pattern:** one form component holds the fields, split into tabs, and two props pick the mode:

| Mode | Props | What changes |
| --- | --- | --- |
| Create, in a modal | no `plantId` | The tabs become steps without tab buttons (`stepper`, `no-header`), bringing their own title, progress line and Back, Next and Add plant (`stepper-controls`). Next checks the step's fields. The whole model is sent once, at the end (`full-payload`). |
| Edit, in a modal | `plantId` | The tabs get their buttons. Only the changed fields are sent, on Save. |
| Edit, on a page | `plantId`, `async` | Every tab is shown under its title (`flat`). Each field saves when it changes. |

The pieces:

| Piece | What it is |
| --- | --- |
| A model | `createRestModelApi` with an item query that loads the plant, an `update` action on it, and a `create` action on the list. |
| The form | A `WUniform` that loads the model with `useQueryFn`, around a `WTabs`, inside a `WModalWrapper` that holds the title and the buttons when editing. |
| The modal | The form itself, opened with `Modal.add`. The modal's frame places the title and the buttons. |
| The page | The form with `async`. Outside an overlay, `WModalWrapper` lays it out in the flow of the page, without a title or buttons. |

```vue
<template>
  <div class="mb-8 flex flex-wrap items-end gap-4">
    <WSelectSingle
      v-model="plantId"
      :options="queryPlants.data.value ?? []"
      :value-getter="item => item.id"
      :search-fn="(item, search) => item.name.toLowerCase().includes(search)"
      :loading="queryPlants.isLoading.value"
      title="Plant on the page"
      class="min-w-60 grow"
      no-margin
    >
      <template #option="{option}">
        {{ option?.name }}
      </template>
    </WSelectSingle>

    <WButton
      :semantic-type="SemanticType.SECONDARY"
      :disabled="!isId(plantId)"
      @click="openModal(plantId)"
    >
      Edit in a modal
    </WButton>

    <WButton @click="openModal()">
      <IconAdd class="square-4" /> Add plant
    </WButton>
  </div>

  <!-- The same form on the page: each field saves as it changes. -->
  <PlantForm
    v-if="isId(plantId)"
    :plant-id="plantId"
    async
  />
</template>

<script lang="ts" setup>
import type {Plant} from '../plant-list/models/Plant'

import {markRaw, ref} from 'vue'

import {Modal} from 'eco-vue-js/dist/utils/Modal'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {isId} from 'eco-vue-js/dist/utils/utils'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'

import PlantForm from './PlantForm.vue'

import {plantModelApi} from '../plant-list/api/Plant'

const queryPlants = plantModelApi.list.use()

const plantId = ref<number | undefined>(1)

/** Opens the same form as a modal: it edits the plant, or walks through adding one when there is no id. A new plant opens on the page. */
const openModal = (id?: number) => {
  Modal.add(markRaw(PlantForm), {
    plantId: id,
    onSaved: (plant: Plant) => plantId.value = plant.id,
  })
}
</script>
```

Pick a plant, change a field and leave it: it saves on its own. Open the same plant in the modal, change it there and save, and the page shows the change. In the tasks, add a row: the list is saved as a whole, with its own Save. Then try Add plant with the fields left empty. The data is in memory here, behind the same model API a real endpoint would use.

## The code

### Model

The form uses the plant model from [List with fields](/recipes/list-with-fields), with two more pieces:

* A `list` query with a `create` action. The action calls `set` to cache the new plant for its item query, and `invalidate` to refetch the lists it may now appear in.
* A payload type. The API takes the caretaker by id, as most APIs take a related item, so `update` and `create` accept `PlantPayload` rather than `Partial<Plant>`.

```ts
list: {
  scope: 'list',
  dataType: [] as Plant[],
  queryFn: () => apiClient.get<Plant[]>(PLANT_PATH).then(response => response.data),
  actions: {
    create: ({set, invalidate}, payload: PlantPayload) => apiClient
      .post<Plant>(PLANT_PATH, payload)
      .then(response => {
        set(response.data)
        invalidate()

        return response.data
      }),
  },
},
```

### The form

One `WUniform` holds the model in every mode:

* `useQueryFn` and `queryParams` load the plant. Without a `plantId` the params are `0`, which the item query's `isId` guard holds back, so nothing loads and the form starts blank.
* `initData` turns the loaded plant into the model the fields edit. It gets `{}` until the plant loads, and when creating, so read every key with a default. This is also where the API's shape and the form's differ: the plant has a caretaker object, the form edits its id.
* `apiMethod` creates the plant or updates it. `full-payload` is set only when creating, so a create sends every field and an update only the changed ones.
* `async` comes straight from the prop. Each field then saves on its own when it changes.

Inside it, one `WTabs` takes the layout from the mode: `stepper` and `no-header` when creating, `flat` on a page, plain tabs when editing in a modal. Every field is written once and shows up in all three.

A stepper checks the fields of a step before it moves on. Invalid ones show their errors, a warning lists them, and the step stays open, so required fields need nothing beyond `required`. A submit checks every step and opens the first one with an error.

The tasks are an array, edited as a nested form with one row per item: `modelValueList` gives each row a stable key, and `select` and `unselect` add and remove rows. On a page, saving each keystroke of a half-typed row would be wrong, so the task list is a form of its own there:

* `v-bind="{...scope, async: false}"` turns off saving on change, for this form only.
* `init-data` makes it keep its own copy of the tasks. Its `api-method` only returns the value, and `@success` writes it into the plant's model, which then saves the field as any other.
* In a modal or a wizard, both are left unset, and the tasks are a part of the plant's form.

What the form shows outside its fields comes from two places:

* Creating, the stepper brings it with `stepper-controls`: the step's title, a progress line under it, and Close or Back with Next or Add plant (`submit-text`). Add plant checks the last step and submits the `WUniform` around it.
* Editing, `WModalWrapper` holds the plant's name as the title, and Cancel and Save, built from the `WUniform`'s template ref.
* With `async`, on a page, there are neither: each field saves on its own.

The form does not know where it is shown. The frame it opens in — a modal, or a dropdown and a bottom sheet for a small form — takes the title and the buttons from `WModalWrapper` and places them, pads the fields, and scrolls them between. On a page there is no frame, and `WModalWrapper` lays everything out in place. The `WUniform` tells the frame it is saving, which keeps it open, and that it has unsaved changes, so a modal asks before closing.

```vue [PlantForm.vue]
<template>
  <!--
    The form brings its own title and buttons: the frame it opens in — a modal, a dropdown, a bottom sheet — places them. On a page, there are none.
    Creating, the stepper brings its own instead: the step's title, the progress, and Back, Next and Add plant.
  -->
  <WModalWrapper
    maximized
    class="sm:w-modal-wrapper-w-160"
  >
    <template
      v-if="!async && !isCreate"
      #title
    >
      {{ formRef?.modelValue.name || 'Plant' }}
    </template>

    <WUniform
      ref="form"
      :use-query-fn="plantModelApi.item.use"
      :query-params="plantId ?? 0"
      :init-data="getModel"
      :api-method="save"
      :full-payload="!isId(plantId)"
      :async="async"
      :readonly="readonly"
      @success="$emit('saved', $event); async || $emit('close:modal')"
    >
      <template #default="scope">
        <!-- One set of tabs, three layouts: steps when creating, tabs when editing, every tab under its title on a page. -->
        <WTabs
          :stepper="isCreate"
          :no-header="isCreate"
          :flat="async"
          submit-text="Add plant"
          stepper-controls
        >
          <WTabsItem
            title="Plant"
            name="plant"
          >
            <div class="py-2">
              <WUniform
                v-bind="scope"
                field="name"
                title="Name"
                required
              >
                <template #field="scopeField">
                  <WInput
                    v-bind="scopeField"
                    :max-length="100"
                    :autofocus="isCreate"
                    required
                  />
                </template>
              </WUniform>

              <WUniform
                v-bind="scope"
                field="species"
                title="Species"
                required
              >
                <template #field="scopeField">
                  <WInput
                    v-bind="scopeField"
                    :max-length="100"
                    placeholder="Monstera deliciosa"
                    required
                  />
                </template>
              </WUniform>

              <WUniform
                v-bind="scope"
                field="kind"
                title="Kind"
                required
              >
                <template #field="scopeField">
                  <WButtonGroup
                    v-bind="scopeField"
                    :list="Object.values(Kind)"
                    wrap
                  >
                    <template #option="{option}">
                      <component
                        :is="kindDisplay[option].icon"
                        class="square-[1.25em]"
                      />
                      {{ kindDisplay[option].name }}
                    </template>
                  </WButtonGroup>
                </template>
              </WUniform>

              <WUniform
                v-bind="scope"
                field="height"
                title="Height, cm"
                :validate="validatePositive"
              >
                <template #field="scopeField">
                  <WInput
                    v-bind="scopeField"
                    type="number"
                  />
                </template>
              </WUniform>
            </div>
          </WTabsItem>

          <WTabsItem
            title="Care"
            name="care"
          >
            <div class="py-2">
              <WInfoCard class="mb-6">
                Light and watering are for a typical room — set them for where the plant stands.
              </WInfoCard>

              <WUniform
                v-bind="scope"
                field="light"
                title="Light"
              >
                <template #field="scopeField">
                  <WButtonGroup
                    v-bind="scopeField"
                    :list="Object.values(Light)"
                    wrap
                  >
                    <template #option="{option}">
                      <component
                        :is="lightDisplay[option].icon"
                        class="square-[1.25em]"
                      />
                      {{ lightDisplay[option].name }}
                    </template>
                  </WButtonGroup>
                </template>
              </WUniform>

              <div class="grid grid-cols-2 gap-4">
                <WUniform
                  v-bind="scope"
                  field="water"
                  title="Water per watering, ml"
                  :validate="validatePositive"
                >
                  <template #field="scopeField">
                    <WInput
                      v-bind="scopeField"
                      type="number"
                    />
                  </template>
                </WUniform>

                <WUniform
                  v-bind="scope"
                  field="humidity"
                  title="Humidity, %"
                  :validate="validatePercent"
                >
                  <template #field="scopeField">
                    <WInput
                      v-bind="scopeField"
                      type="number"
                    />
                  </template>
                </WUniform>
              </div>

              <WUniform
                v-bind="scope"
                field="caretaker"
                title="Caretaker"
                required
              >
                <template #field="scopeField">
                  <WSelectSingle
                    v-bind="scopeField"
                    :options="gardeners"
                    :value-getter="item => item.id"
                    :search-fn="(item, search) => item.name.toLowerCase().includes(search)"
                    :option-component="markRaw(OptionGardener)"
                    placeholder="Search caretakers"
                    required
                  />
                </template>
              </WUniform>
            </div>
          </WTabsItem>

          <WTabsItem
            title="Tasks"
            name="tasks"
          >
            <div class="py-2">
              <!--
                The task list is saved as a whole. On the page it is a form of its own, with Save and Cancel,
                so a half-typed task is not sent; elsewhere it is a part of the form it is in.
              -->
              <WUniform
                v-bind="{...scope, async: false}"
                field="tasks"
                :init-data="async ? copyTasks : undefined"
                :api-method="async ? (value => value as Task[]) : undefined"
                full-payload
                @success="scope.updateModelValueInner($event, ['tasks'] as const)"
              >
                <template #default="scopeTasks">
                  <WUniform
                    v-for="(item, key, index) in scopeTasks.modelValueList"
                    :key="key"
                    v-bind="scopeTasks"
                    :field="index"
                  >
                    <template #default="scopeTask">
                      <div class="grid grid-cols-[1fr_10rem_auto] items-end gap-2">
                        <WUniform
                          v-bind="scopeTask"
                          field="title"
                          title="Task"
                          required
                        >
                          <template #field="scopeField">
                            <WInput
                              v-bind="scopeField"
                              :hide-title="index !== 0"
                              required
                            />
                          </template>
                        </WUniform>

                        <WUniform
                          v-bind="scopeTask"
                          field="due"
                          title="Due"
                          required
                        >
                          <template #field="scopeField">
                            <WInputDate
                              v-bind="scopeField"
                              :hide-title="index !== 0"
                              required
                            />
                          </template>
                        </WUniform>

                        <WButton
                          :semantic-type="SemanticType.SECONDARY"
                          :disabled="scopeTasks.readonly || scopeTasks.submitting || scopeTasks.skeleton"
                          class="mb-4 w-(--w-input-height)"
                          @click="scopeTasks.unselect(item)"
                        >
                          <IconClose class="square-4" />
                        </WButton>
                      </div>
                    </template>
                  </WUniform>

                  <div class="flex flex-wrap gap-4">
                    <WButton
                      v-if="!scopeTasks.readonly"
                      :semantic-type="SemanticType.SECONDARY"
                      :disabled="scopeTasks.skeleton || scopeTasks.submitting"
                      @click="scopeTasks.select({title: '', due: getStartOfDay()})"
                    >
                      <IconAdd class="square-4" /> Add task
                    </WButton>

                    <template v-if="async && scopeTasks.hasChanges">
                      <WButton
                        :semantic-type="SemanticType.SECONDARY"
                        :disabled="scopeTasks.submitting"
                        class="ml-auto"
                        @click="scopeTasks.initModel()"
                      >
                        Cancel
                      </WButton>

                      <WButton
                        :loading="scopeTasks.submitting"
                        @click="scopeTasks.submit?.()"
                      >
                        Save tasks
                      </WButton>
                    </template>
                  </div>
                </template>
              </WUniform>
            </div>
          </WTabsItem>
        </WTabs>
      </template>
    </WUniform>

    <!-- Editing gets Cancel and Save on every tab. -->
    <template
      v-if="!async && !isCreate"
      #actions
    >
      <WButton
        :disabled="formRef?.submitting"
        :semantic-type="SemanticType.SECONDARY"
        class="w-full"
        @click="$emit('close:modal')"
      >
        {{ formRef?.hasChanges ? 'Cancel' : 'Close' }}
      </WButton>

      <WButton
        :disabled="!formRef?.hasChanges"
        :loading="formRef?.submitting"
        class="w-full"
        @click="formRef?.submit?.()"
      >
        Save
      </WButton>
    </template>
  </WModalWrapper>
</template>

<script lang="ts" setup>
import {computed, markRaw, useTemplateRef} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'
import {isId} from 'eco-vue-js/dist/utils/utils'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WButtonGroup from 'eco-vue-js/dist/components/Button/WButtonGroup.vue'
import WInfoCard from 'eco-vue-js/dist/components/InfoCard/WInfoCard.vue'
import WInput from 'eco-vue-js/dist/components/Input/WInput.vue'
import WInputDate from 'eco-vue-js/dist/components/Input/WInputDate.vue'
import WModalWrapper from 'eco-vue-js/dist/components/Modal/WModalWrapper.vue'
import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'
import WTabs from 'eco-vue-js/dist/components/Tabs/WTabs.vue'
import WTabsItem from 'eco-vue-js/dist/components/Tabs/WTabsItem.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

import IconAdd from 'eco-vue-js/dist/assets/icons/IconAdd'
import IconClose from 'eco-vue-js/dist/assets/icons/IconClose'

import {gardeners} from '../../shared/Gardener'
import OptionGardener from '../../shared/OptionGardener.vue'
import {type PlantPayload, plantModelApi} from '../plant-list/api/Plant'
import {Kind, Light, type Plant, type Task} from '../plant-list/models/Plant'
import {kindDisplay, lightDisplay} from '../plant-list/models/PlantDisplay'

/** What the form edits: the plant's own fields, with the caretaker by id, as the API takes it. */
type PlantFormData = Pick<Plant, 'name' | 'species' | 'kind' | 'height' | 'light' | 'water' | 'humidity' | 'tasks'> & {
  caretaker: number | undefined
}

const props = defineProps<{
  /** The plant to edit. Without it, the form creates a plant. */
  plantId?: number
  /** Saves each field as it changes, for editing on a page. */
  async?: boolean
  readonly?: boolean
}>()

defineEmits<{
  (e: 'saved', value: Plant): void
  (e: 'close:modal'): void
}>()

const formRef = useTemplateRef<ComponentInstance<typeof WUniform<PlantFormData, number, undefined, Plant, PlantFormData>>>('form')

const isCreate = computed(() => !props.async && !isId(props.plantId))

/** Builds the editable model from the loaded plant. It gets `{}` until the plant loads, and when creating. */
const getModel = (plant: Partial<Plant>): PlantFormData => ({
  name: plant.name ?? '',
  species: plant.species ?? '',
  kind: plant.kind ?? Kind.TROPICAL,
  height: plant.height ?? 10,
  light: plant.light ?? Light.BRIGHT,
  water: plant.water ?? 200,
  humidity: plant.humidity ?? 50,
  caretaker: plant.caretaker?.id,
  tasks: copyTasks(plant.tasks),
})

const copyTasks = (tasks: Task[] | undefined): Task[] => tasks?.map(task => ({...task})) ?? []

/** Creates the plant with the whole model, or updates it with the changed fields only. */
const save = (payload: Partial<PlantFormData>) => {
  return isId(props.plantId)
    ? plantModelApi.item.actions.update(props.plantId, payload as PlantPayload)
    : plantModelApi.list.actions.create(payload as PlantPayload)
}

const validatePositive = (value: unknown) => typeof value === 'number' && value < 0 ? 'Must not be negative' : undefined

const validatePercent = (value: unknown) => typeof value === 'number' && (value < 0 || value > 100) ? 'Must be from 0 to 100' : undefined
</script>
```

### Opening it

The form is the modal: `Modal.add(markRaw(PlantForm), {plantId, onSaved})`. `saved` passes the saved plant back to whoever opened it — here it opens the new plant on the page — and after a save in an overlay the form emits `close:modal`. Load it with `defineAsyncComponent` where it is only opened, so its code is fetched on first open.

The steps belong to the form, which also renders them as tabs and on a page, so the form keeps them in its own `WTabs` rather than in a modal's. With `stepper-controls` the stepper hands its title, progress and buttons to the frame only while it is one; as tabs and on a page it has none.

### The page

On a page, the form is all there is: `<PlantForm :plant-id="id" async />`. Everything shown on the page and in the modal comes from the same item query, so a save in one updates the other through the cache. A field changed but not yet saved keeps its value when another one is saved.

## Why it is built this way

* **One set of fields.** A field, its validation and its control are written once. The modes differ only in layout and in when the model is sent, and both come from props on `WTabs` and `WUniform`.
* **The frame places the form's parts.** The form renders its title and buttons once, in `WModalWrapper`, and does not know where it is shown. A modal, a dropdown, a bottom sheet and a page each put them where their layout needs, with their own padding.
* **The cache is the shared state.** The form loads the plant with the item query, and the model's actions write to it. Every open view of the plant stays current without passing data around.
* **The form edits its own shape.** `initData` turns the API's plant into what the controls need, and the payload is shaped back the way the API takes it.

## Variations

* **Pick a template first**: a first step with cards for common setups calls `scope.initModel(preset)` and then `next()`, so the next steps start from the preset.
* **Save in the middle of the wizard**: `requireSave` on a step submits the form before moving past it, e.g. when a later step needs the saved id. After that save, the form updates the item it created: build the id from `plantId` or the saved model's id, and pass `full-payload` only while neither exists.
* **Side tabs**: `side` on `WTabs` puts the tab buttons in a column, for a form with many tabs in a wide modal.
* **Read-only users**: pass `readonly` to the form, or provide it for the whole page with `useProvideReadonly`.
* **From the list**: a row menu item that opens `PlantForm` with the row's id edits the plant from [the list](/recipes/list-with-fields), and the list's row updates from the cache.

---

---
url: https://rsmple.github.io/eco-vue-js/recipes/list-with-fields.md
description: >-
  Build a paginated, sortable, searchable WList on a createRestModelApi model,
  with one component per column, filters kept in the URL, an expansion row, a
  row menu and bulk actions that call the model's actions — the pattern used for
  every data table in eco-vue-js apps.
---

# List with fields

**Problem:** a paginated collection needs a table on desktop and cards on mobile, sortable and resizable columns the user can show, hide and reorder, filters, per-row and bulk actions, and an expandable detail row — without each list re-implementing any of that.

**Pattern:** `WList` owns layout, pagination, selection, column settings and ordering. You supply:

| Piece | What it is |
| --- | --- |
| A model | `createRestModelApi` with a paginated query, whose `use` is the list's `useQueryFn`, and the actions that change an item. |
| Query params | `createUseQueryParams`, which keeps the user's search, filters and ordering in the URL. |
| Filter components | One `.vue` per filter for `WListFilter`. The component renders the control; its exported `meta` declares the title, icon and the params it sets. |
| Field components | One `.vue` per column. The component renders the cell; its exported `meta` declares the label, width, title and sort field. |
| A fields index | The ordered tuple of field modules plus the default column config. |
| Menu components | Row actions, typed with `MenuProps<T>` / `MenuEmits<T>`. |
| Bulk components | Actions on the selected rows, typed with `BulkProps<QueryParams>`. |
| An expansion component | Optional detail row, opened from the field marked `allow-open`. |

```vue
<template>
  <WList
    :use-query-fn="plantModelApi.paginated.use"
    :query-params="queryParams"
    :fields="listFieldsPlant"
    :default-config-map="defaultFieldConfigMapPlant"
    config-key="w-list-docs-plant"
    :expansion="markRaw(PlantContent)"
    :bulk="bulk"
    :menu="menu"
    selection-title="plant"
    :select-all-text-getter="selectAllTextGetter"
    :card-columns="cardColumns"
    :card-areas="cardAreas"
    card-class="list:h-11 card:gap-1 sm:card:p-4 sm-not:card:py-3 sm:card:w-list-rounded-xl sm:card:border sm:card:shadow-sm border-line-subtle"
    card-wrapper-class="card:self-start"
    min-height
    class="card:w-list-gap-3"
    @update:query-params="updateQueryParams"
  >
    <!-- The filters edit the same query params the list reads, in the selection bar above the rows. -->
    <template #filter>
      <WUniform
        :model-value="queryParams"
        @update:model-value="updateQueryParams"
      >
        <template #default="scope">
          <WListFilter
            :scope="scope"
            :filter="listFilterPlant"
            :pinned="listFilterPlantPinned"
            search
          />
        </template>
      </WUniform>
    </template>
  </WList>
</template>

<script lang="ts" setup>
import type {Plant} from './models/Plant'

import {markRaw} from 'vue'

import type {BulkComponent, CardAreas, GridCol, MenuComponent} from 'eco-vue-js/dist/components/List/types'

import WList from 'eco-vue-js/dist/components/List/WList.vue'
import WListFilter from 'eco-vue-js/dist/components/List/WListFilter.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

import PlantContent from './PlantContent.vue'
import {type QueryParamsPlants, plantModelApi, useQueryParamsPlants} from './api/Plant'
import WBulkPlantCaretaker from './bulk/WBulkPlantCaretaker.vue'
import WBulkPlantDry from './bulk/WBulkPlantDry.vue'
import WBulkPlantRemove from './bulk/WBulkPlantRemove.vue'
import WBulkPlantWatered from './bulk/WBulkPlantWatered.vue'
import {defaultFieldConfigMapPlant, listFieldsPlant} from './fields'
import {listFilterPlant, listFilterPlantPinned} from './filter'
import WMenuPlantCaretaker from './menu/WMenuPlantCaretaker.vue'
import WMenuPlantDelete from './menu/WMenuPlantDelete.vue'
import WMenuPlantToggle from './menu/WMenuPlantToggle.vue'

// The docs have no router, so the filters stay in the page. In an app, keep them in the URL: `useQueryParamsPlants(useRoute())`.
const {queryParams, updateQueryParams} = useQueryParamsPlants.useQueryParamsLocal()

const selectAllTextGetter = (isUnselect: boolean, count: number) => `${ isUnselect ? 'Unselect' : 'Select' } all ${ count } plants`
</script>

<script lang="ts">
const bulk: BulkComponent<QueryParamsPlants>[] = [
  markRaw(WBulkPlantWatered),
  markRaw(WBulkPlantDry),
  markRaw(WBulkPlantCaretaker),
  markRaw(WBulkPlantRemove),
]

const menu: MenuComponent<Plant>[] = [
  markRaw(WMenuPlantToggle),
  markRaw(WMenuPlantCaretaker),
  markRaw(WMenuPlantDelete),
]

const cardColumns = ['2fr', '1fr', 'auto'] as const satisfies GridCol[]

const cardAreas: CardAreas<typeof listFieldsPlant, typeof cardColumns['length']> = [
  ['name', 'name', 'area_select'],
  ['species', 'species', 'area_more'],
  ['kind', 'light', 'light'],
  ['health', 'growth', 'growth'],
  ['watered', 'due', 'due'],
  ['height', 'humidity', 'humidity'],
  ['water', 'seeds', 'seeds'],
  ['caretaker', 'caretaker', 'caretaker'],
]
</script>
```

Try picking a kind from the pinned chip, adding a filter, sorting by a few columns from the sort menu, resizing Name, hiding columns from the header settings, switching to cards, expanding a row, using the `⋯` menu, and selecting a few rows for the bulk actions above the list. The data is in memory here, behind the same model API a real endpoint would use.

## The code

### Model and filters

The model is the only piece that knows where data comes from — see [Data layer](/guide/data-layer) for the whole API. `WList` calls `plantModelApi.paginated.use` with `{...queryParams, page}` for each page and expects a `PaginatedResponse<T>`. Here each request is answered from an array in memory; in an app it goes through your `apiClient`.

The item query holds the actions the menu calls. `update` puts the saved plant into every cached page that holds it, and `delete` returns `() => null` to drop the plant from them. The paginated query holds the bulk actions, `updateMany` and `deleteMany`. They take the list's query params narrowed to the selection — `id__in`, `id__not_in` or `slice_indexes` — and invalidate the model, since a bulk change can move plants in and out of the filters.

`useQueryParamsPlants` declares the params the user sets: `search`, `ordering` and one per filter — `kind__in`, `light__in`, `watered` and `caretaker`. Each gets a parse function that reads it back from the URL and drops what does not parse, so a hand-edited link cannot put an unknown kind into the query. Leave `page` out — the list adds it to each page's query. The docs have no router, so the demo keeps the filters in the page with `useQueryParamsLocal()`. In an app, pass the route, and the filters live in the URL:

```ts
const {queryParams, updateQueryParams} = useQueryParamsPlants(useRoute())
```

::: code-group

```ts [models/Plant.ts]
import {addDay, addMonth, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import {type Gardener, gardeners} from '../../../shared/Gardener'

export enum Kind {
  TROPICAL = 'tropical',
  SUCCULENT = 'succulent',
  FERN = 'fern',
  HERB = 'herb',
}

export enum Light {
  FULL_SUN = 'full_sun',
  BRIGHT = 'bright',
  PARTIAL = 'partial',
  SHADE = 'shade',
}

export type Task = {
  title: string
  due: Date
}

/** A task with the key a list row of it needs. */
export type TaskItem = Task & {id: number}

export type Plant = {
  id: number
  name: string
  species: string
  kind: Kind
  /** Grown height, in centimetres. */
  height: number
  watered: boolean
  /** Air humidity the plant prefers, in percent. */
  humidity: number
  /** How many seeds are in stock. */
  seeds: number
  /** Water per watering, in millilitres. */
  water: number
  /** When a thirsty plant needs water by; `null` while it is watered. */
  waterBy: Date | null
  light: Light
  /** Health score, from 0 to 100. */
  health: number
  /** Height a month apart over the last six months, oldest first; the last is today's. */
  growth: {date: number, height: number}[]
  /** Days it was watered over the last four weeks, newest first. */
  waterings: Date[]
  /** Temperature range it is happy in, in °C. */
  temperature: [number, number]
  caretaker: Gardener
  tasks: Task[]
  description: string
}

const LIGHTS = [Light.BRIGHT, Light.FULL_SUN, Light.PARTIAL, Light.SHADE] as const

/** Days between waterings. */
const INTERVAL: Record<Kind, number> = {
  [Kind.TROPICAL]: 5,
  [Kind.SUCCULENT]: 10,
  [Kind.FERN]: 3,
  [Kind.HERB]: 2,
}

const TEMPERATURE: Record<Kind, [number, number]> = {
  [Kind.TROPICAL]: [18, 29],
  [Kind.SUCCULENT]: [10, 32],
  [Kind.FERN]: [16, 24],
  [Kind.HERB]: [12, 26],
}

const SOURCE: [string, string, Kind, number][] = [
  ['Monstera', 'Monstera deliciosa', Kind.TROPICAL, 300],
  ['Aloe vera', 'Aloe barbadensis', Kind.SUCCULENT, 60],
  ['Boston fern', 'Nephrolepis exaltata', Kind.FERN, 90],
  ['Basil', 'Ocimum basilicum', Kind.HERB, 60],
  ['Fiddle-leaf fig', 'Ficus lyrata', Kind.TROPICAL, 300],
  ['Jade plant', 'Crassula ovata', Kind.SUCCULENT, 90],
  ['Maidenhair fern', 'Adiantum raddianum', Kind.FERN, 45],
  ['Rosemary', 'Salvia rosmarinus', Kind.HERB, 150],
  ['Rubber plant', 'Ficus elastica', Kind.TROPICAL, 250],
  ['Snake plant', 'Dracaena trifasciata', Kind.SUCCULENT, 90],
  ['Bird\'s nest fern', 'Asplenium nidus', Kind.FERN, 90],
  ['Thyme', 'Thymus vulgaris', Kind.HERB, 30],
  ['Golden pothos', 'Epipremnum aureum', Kind.TROPICAL, 200],
  ['Zebra haworthia', 'Haworthiopsis attenuata', Kind.SUCCULENT, 15],
  ['Staghorn fern', 'Platycerium bifurcatum', Kind.FERN, 90],
  ['Mint', 'Mentha spicata', Kind.HERB, 60],
  ['Heartleaf philodendron', 'Philodendron hederaceum', Kind.TROPICAL, 120],
  ['Echeveria', 'Echeveria elegans', Kind.SUCCULENT, 15],
  ['Rabbit\'s foot fern', 'Davallia fejeensis', Kind.FERN, 45],
  ['Lavender', 'Lavandula angustifolia', Kind.HERB, 60],
  ['Peace lily', 'Spathiphyllum wallisii', Kind.TROPICAL, 60],
  ['String of pearls', 'Curio rowleyanus', Kind.SUCCULENT, 90],
  ['Blue star fern', 'Phlebodium aureum', Kind.FERN, 60],
  ['Sage', 'Salvia officinalis', Kind.HERB, 60],
  ['Calathea', 'Goeppertia orbifolia', Kind.TROPICAL, 90],
  ['Panda plant', 'Kalanchoe tomentosa', Kind.SUCCULENT, 45],
  ['Kangaroo fern', 'Microsorum diversifolium', Kind.FERN, 45],
  ['Oregano', 'Origanum vulgare', Kind.HERB, 45],
  ['Prayer plant', 'Maranta leuconeura', Kind.TROPICAL, 30],
  ['Burro\'s tail', 'Sedum morganianum', Kind.SUCCULENT, 60],
  ['Holly fern', 'Cyrtomium falcatum', Kind.FERN, 60],
  ['Parsley', 'Petroselinum crispum', Kind.HERB, 30],
  ['Bird of paradise', 'Strelitzia reginae', Kind.TROPICAL, 180],
  ['Golden barrel cactus', 'Echinocactus grusonii', Kind.SUCCULENT, 60],
  ['Button fern', 'Pellaea rotundifolia', Kind.FERN, 30],
  ['Chives', 'Allium schoenoprasum', Kind.HERB, 30],
  ['Areca palm', 'Dypsis lutescens', Kind.TROPICAL, 250],
  ['Christmas cactus', 'Schlumbergera bridgesii', Kind.SUCCULENT, 30],
  ['Lemon button fern', 'Nephrolepis cordifolia', Kind.FERN, 30],
  ['Coriander', 'Coriandrum sativum', Kind.HERB, 50],
  ['Parlour palm', 'Chamaedorea elegans', Kind.TROPICAL, 120],
  ['Bunny ear cactus', 'Opuntia microdasys', Kind.SUCCULENT, 60],
  ['Silver lace fern', 'Pteris ensiformis', Kind.FERN, 45],
  ['Dill', 'Anethum graveolens', Kind.HERB, 90],
  ['Chinese evergreen', 'Aglaonema commutatum', Kind.TROPICAL, 90],
  ['Ponytail palm', 'Beaucarnea recurvata', Kind.SUCCULENT, 180],
  ['Asparagus fern', 'Asparagus setaceus', Kind.FERN, 90],
  ['Lemon balm', 'Melissa officinalis', Kind.HERB, 60],
  ['Anthurium', 'Anthurium andraeanum', Kind.TROPICAL, 60],
  ['ZZ plant', 'Zamioculcas zamiifolia', Kind.SUCCULENT, 90],
  ['Japanese painted fern', 'Athyrium niponicum', Kind.FERN, 45],
  ['Tarragon', 'Artemisia dracunculus', Kind.HERB, 90],
  ['Elephant ear', 'Alocasia amazonica', Kind.TROPICAL, 120],
  ['Living stones', 'Lithops lesliei', Kind.SUCCULENT, 5],
  ['Ostrich fern', 'Matteuccia struthiopteris', Kind.FERN, 150],
  ['Chamomile', 'Matricaria chamomilla', Kind.HERB, 60],
  ['Croton', 'Codiaeum variegatum', Kind.TROPICAL, 150],
  ['Hens and chicks', 'Sempervivum tectorum', Kind.SUCCULENT, 15],
  ['Tree fern', 'Dicksonia antarctica', Kind.FERN, 450],
  ['Lemongrass', 'Cymbopogon citratus', Kind.HERB, 150],
  ['Moth orchid', 'Phalaenopsis amabilis', Kind.TROPICAL, 60],
  ['Century plant', 'Agave americana', Kind.SUCCULENT, 180],
  ['Hart\'s tongue fern', 'Asplenium scolopendrium', Kind.FERN, 60],
  ['Bay laurel', 'Laurus nobilis', Kind.HERB, 300],
  ['Swiss cheese vine', 'Monstera adansonii', Kind.TROPICAL, 90],
  ['Paddle plant', 'Kalanchoe luciae', Kind.SUCCULENT, 45],
  ['Cinnamon fern', 'Osmundastrum cinnamomeum', Kind.FERN, 120],
  ['Fennel', 'Foeniculum vulgare', Kind.HERB, 150],
  ['Dragon tree', 'Dracaena marginata', Kind.TROPICAL, 200],
  ['Ghost plant', 'Graptopetalum paraguayense', Kind.SUCCULENT, 20],
  ['Lady fern', 'Athyrium filix-femina', Kind.FERN, 90],
  ['Marjoram', 'Origanum majorana', Kind.HERB, 45],
  ['Cast iron plant', 'Aspidistra elatior', Kind.TROPICAL, 60],
  ['String of hearts', 'Ceropegia woodii', Kind.SUCCULENT, 120],
  ['Royal fern', 'Osmunda regalis', Kind.FERN, 150],
  ['Catnip', 'Nepeta cataria', Kind.HERB, 90],
  ['Banana plant', 'Musa acuminata', Kind.TROPICAL, 300],
  ['Moon cactus', 'Gymnocalycium mihanovichii', Kind.SUCCULENT, 10],
  ['Bracken', 'Pteridium aquilinum', Kind.FERN, 120],
  ['Sorrel', 'Rumex acetosa', Kind.HERB, 60],
]

/** Each plant of `SOURCE` grows in several pots, numbered after the first, so the list runs over many pages. */
const POTS = 4

/** In-memory stand-in for a REST collection. */
export const plants: Plant[] = Array.from({length: SOURCE.length * POTS}, (_, index) => {
  const [title, species, kind, height] = SOURCE[index % SOURCE.length]!
  const pot = Math.floor(index / SOURCE.length) + 1
  const name = pot === 1 ? title : `${ title } ${ pot }`
  const today = getStartOfDay()
  // The kinds repeat every four rows, so `round` steps each kind through every light level and caretaker in turn.
  const round = index + Math.floor(index / 4)
  const watered = index % 3 !== 0
  // Some thirsty plants are overdue.
  const waterBy = watered ? null : addDay(today, index * 5 % 10 - 4)
  // Plants that grow fast gained up to a third of their height in six months.
  const gain = 0.08 + index * 7 % 25 / 100
  // The last watering was a while ago for thirsty plants.
  const lastWatered = (watered ? index % INTERVAL[kind] : INTERVAL[kind] + 1 + index % 3)

  return {
    id: index + 1,
    name,
    species,
    kind,
    height,
    watered,
    humidity: 40 + index * 13 % 41,
    seeds: 40 + index * 7919 % 4800,
    water: 50 * (1 + index * 7 % 16),
    waterBy,
    light: LIGHTS[round % LIGHTS.length]!,
    health: Math.max(12, 60 + index * 17 % 41 - (waterBy && waterBy < today ? 35 : 0)),
    growth: Array.from({length: 6}, (_, month) => ({
      date: +addMonth(today, month - 5),
      height: month === 5 ? height : Math.round(height * (1 - gain * (5 - month) / 5) * (1 + (month * index % 3 - 1) / 100)),
    })),
    waterings: Array.from({length: 28}, (_, day) => addDay(today, -day))
      .filter((_, day) => day >= lastWatered && (day - lastWatered) % INTERVAL[kind] === 0),
    temperature: TEMPERATURE[kind],
    caretaker: gardeners[round % gardeners.length]!,
    tasks: [
      {title: 'Fertilize', due: addDay(today, index * 3 % 14 - 2)},
      {title: 'Prune', due: addDay(today, 7 + index * 5 % 30)},
      {title: 'Repot', due: addDay(today, 20 + index * 11 % 90)},
    ],
    description: `${ name } (${ species }), a ${ kind } plant that grows to about ${ height } cm.`,
  }
})
```

```ts [api/Plant.ts]
import {createUseQueryParams} from 'eco-vue-js/dist/utils/api'
import {Order, parseOrdering} from 'eco-vue-js/dist/utils/order'
import {createRestModelApi} from 'eco-vue-js/dist/utils/restModelApi'
import {paginateList} from 'eco-vue-js/dist/utils/useDefaultQuery'
import type {QueryParamsSelection} from 'eco-vue-js/dist/utils/useSelected'
import {isId, parseBoolean, parseId, parseString, parseStringList} from 'eco-vue-js/dist/utils/utils'

import {gardeners} from '../../../shared/Gardener'
import {Kind, Light, type Plant, plants} from '../models/Plant'

/** What the API takes to create or change a plant: the caretaker goes by id. */
export type PlantPayload = Partial<Omit<Plant, 'caretaker'> & {caretaker: number}>

/** Parses a comma-separated list, dropping values that are not in `values`, such as ones edited into the URL by hand. */
const parseEnumList = <Value extends string>(values: Value[]): ParseFn<Value[]> => value => {
  return parseStringList(value)?.filter((item): item is Value => (values as string[]).includes(item))
}

/** The filters a user sets on the list. In an app they are kept in the URL. */
export const useQueryParamsPlants = createUseQueryParams({
  search: parseString,
  ordering: parseString,
  kind__in: parseEnumList(Object.values(Kind)),
  light__in: parseEnumList(Object.values(Light)),
  watered: parseBoolean,
  caretaker: parseId,
})

/** The filters, plus the selection a bulk action narrows them to. */
export type QueryParamsPlants = typeof useQueryParamsPlants['QueryParams'] & Omit<QueryParamsSelection, 'id__in'> & {
  page?: number
  /** Ids — comma-separated when async selects look up the items behind their model value, an array for the rows picked in the list. */
  id__in?: string | number[]
}

let source = plants

/** Stands in for a request to the API: answers after a moment with a copy of the data. */
const respond = <Data>(handler: () => Data) => new Promise<Data>(resolve => {
  setTimeout(() => resolve(structuredClone(handler())), 300)
})

/** Copies a value the way sending it would: a form's payload holds its reactive objects, which cannot be stored or cloned. */
const toPlain = <Value>(value: Value): Value => {
  if (Array.isArray(value)) return value.map(toPlain) as Value
  if (value instanceof Date) return new Date(value) as Value
  if (value instanceof Object) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toPlain(item)])) as Value

  return value
}

/** Applies a payload the way the backend would, looking up the caretaker by id. */
const applyPayload = (plant: Plant, {caretaker, ...payload}: PlantPayload): Plant => ({
  ...plant,
  ...toPlain(payload),
  caretaker: gardeners.find(item => item.id === caretaker) ?? plant.caretaker,
})

/** The defaults the backend fills in for a new plant. */
const createPlant = (payload: PlantPayload): Plant => {
  const today = new Date()
  const height = payload.height ?? 0

  return applyPayload({
    id: Math.max(0, ...source.map(plant => plant.id)) + 1,
    name: '',
    species: '',
    kind: Kind.TROPICAL,
    height,
    watered: true,
    humidity: 50,
    seeds: 0,
    water: 200,
    waterBy: null,
    light: Light.BRIGHT,
    health: 100,
    growth: [{date: +today, height}],
    waterings: [today],
    temperature: [16, 26],
    caretaker: gardeners[0]!,
    tasks: [],
    description: '',
  }, payload)
}

const toSortable =(value: Plant[keyof Plant]) => value instanceof Date ? value.getTime() : value

/** Sorts in `direction`, with empty values last either way. */
const compare = (a: Plant, b: Plant, field: keyof Plant, direction: 1 | -1) => {
  const left = toSortable(a[field])
  const right = toSortable(b[field])

  if (left === null || right === null) return left === right ? 0 : left === null ? 1 : -1

  return direction * (typeof left === 'number' && typeof right === 'number' ? left - right : String(left).localeCompare(String(right)))
}

/** Filters and sorts by the same query params a backend would receive, then narrows to the selection. */
const filterPlants = (queryParams: QueryParamsPlants | undefined) => {
  const {kind__in, light__in, watered, caretaker, id__not_in, slice_indexes} = queryParams ?? {}
  const search = queryParams?.search?.trim().toLowerCase()
  const ids = typeof queryParams?.id__in === 'string' ? queryParams.id__in.split(',').map(Number) : queryParams?.id__in
  let result = search
    ? source.filter(plant => plant.name.toLowerCase().includes(search) || plant.species.toLowerCase().includes(search))
    : source

  if (ids) result = result.filter(plant => ids.includes(plant.id))
  if (id__not_in) result = result.filter(plant => !id__not_in.includes(plant.id))
  if (kind__in) result = result.filter(plant => kind__in.includes(plant.kind))
  if (light__in) result = result.filter(plant => light__in.includes(plant.light))
  if (watered !== undefined) result = result.filter(plant => plant.watered === watered)
  if (caretaker) result = result.filter(plant => plant.caretaker.id === caretaker)

  if (queryParams?.ordering) {
    const ordering = parseOrdering<keyof Plant>(queryParams.ordering)

    // Each next field breaks the ties of the ones before it.
    result = result.toSorted((a, b) => {
      for (const {field, order} of ordering) {
        const difference = compare(a, b, field, order === Order.DESC ? -1 : 1)

        if (difference !== 0) return difference
      }

      return 0
    })
  }

  // A range picked with Shift is the positions in the sorted list, both ends included.
  if (slice_indexes) result = result.slice(slice_indexes[0], slice_indexes[1] + 1)

  return result
}

export const plantModelApi = createRestModelApi({
  modelKey: 'Plant',
  model: {} as Plant,
  queries: {
    item: {
      scope: 'item',
      dataType: {} as Plant,
      isQueryParams: isId,
      queryFn: ({queryKey}) => respond(() => source.find(plant => plant.id === queryKey[2])!),
      actions: {
        // In an app, a PATCH to `/plants/<id>/`.
        update: ({set}, id, payload: PlantPayload) => respond(() => {
          source = source.map(plant => plant.id === id ? applyPayload(plant, payload) : plant)

          return source.find(plant => plant.id === id)!
        })
          .then(plant => {
            // Puts the saved plant into every cached page that holds it.
            set(plant)

            return plant
          }),

        // In an app, a DELETE to `/plants/<id>/`.
        delete: (context, id) => respond(() => {
          source = source.filter(plant => plant.id !== id)
        })
          // Drops the plant from every cached page.
          .then(() => () => null),
      },
    },

    list: {
      scope: 'list',
      dataType: [] as Plant[],
      // In an app, a GET to `/plants/` without pagination — for selects.
      queryFn: () => respond(() => source.toSorted((a, b) => a.name.localeCompare(b.name))),
      actions: {
        // In an app, a POST to `/plants/`.
        create: ({set, invalidate}, payload: PlantPayload) => respond(() => {
          const plant = createPlant(payload)

          source = [...source, plant]

          return plant
        })
          .then(plant => {
            // Caches the new plant for its item query, and refetches the lists it may now appear in.
            set(plant)
            invalidate()

            return plant
          }),
      },
    },

    paginated: {
      scope: 'paginated',
      dataType: {} as PaginatedResponse<Plant>,
      isQueryParams: (value: unknown): value is QueryParamsPlants | undefined => value === undefined || value instanceof Object,
      // In an app, a GET to `/plants/` with the query params.
      queryFn: ({queryKey}) => respond(() => paginateList(filterPlants(queryKey[2]), queryKey[2]?.page, 10)),
      actions: {
        // In an app, a PATCH to `/plants/bulk/` with the filters and the selection as query params.
        updateMany: ({invalidate}, queryParams, payload: PlantPayload) => respond(() => {
          const ids = new Set(filterPlants(queryParams).map(plant => plant.id))

          source = source.map(plant => ids.has(plant.id) ? applyPayload(plant, payload) : plant)
        })
          // Refetches every cached page, since the change can move plants in and out of the filters.
          .then(() => invalidate()),

        // In an app, a DELETE to `/plants/bulk/` with the filters and the selection as query params.
        deleteMany: ({invalidate}, queryParams) => respond(() => {
          const ids = new Set(filterPlants(queryParams).map(plant => plant.id))

          source = source.filter(plant => !ids.has(plant.id))
        })
          .then(() => invalidate()),
      },
    },
  },
})
```

:::

### Fields

Each field is a module with two exports: the component (default) renders the cell, and `meta` describes the column. Keep both in one file — the column cannot drift from what it renders.

* `label` is the column's stable id: it keys the saved column config and names the area in `cardAreas`.
* `width` is the column's width until the user resizes it: a length such as `'8rem'`, or `'minmax(12rem, 1fr)'` for a column that takes the space the others leave and shrinks to its minimum when the list scrolls sideways. The header and every row share these widths, so nothing is measured.
* `field` makes the column sortable — its value is sent as `ordering` (`height`, `-height`).
* `textFormat` gives a plain-text value for CSV export and "copy as Markdown", for cells that render components or format the value for display — like the water-by date, which is shown short and exported in full.
* `allow-open` on `WListCardField` makes that cell toggle the expansion row.
* A cell can render anything inside `WListCardField` — a tag in the kind's tone, a sparkline, a meter. Keep it one line high so the row height stays the same, and give it a `textFormat` for export.

::: code-group

```vue [WFieldPlantName.vue]
<template>
  <WListCardField
    :model-value="item.name"
    :skeleton="skeleton"
    allow-open
    class="font-semibold"
  />
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import type {FieldProps, ListField} from 'eco-vue-js/dist/components/List/types'

import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'

defineProps<FieldProps<Plant>>()

defineEmits<{
  (e: 'update:item', value: Plant): void
  (e: 'delete:item'): void
}>()
</script>

<script lang="ts">
export const meta = {
  label: 'name',
  width: 'minmax(12rem, 1fr)',
  title: 'Name',
  field: 'name',
  allowResize: true,
} as const satisfies ListField<Plant>
</script>
```

```vue [WFieldPlantGrowth.vue]
<template>
  <WListCardField
    :skeleton="skeleton"
    allow-open
  >
    <span class="tone-data-green flex items-center gap-2">
      <!-- A sparkline of the last six months, scaled to the plant's own range. -->
      <svg
        viewBox="0 0 50 16"
        class="text-tone h-4 w-12 shrink-0 overflow-visible"
        fill="none"
      >
        <polyline
          :points="points"
          stroke="currentColor"
          stroke-width="1.5"
          stroke-linecap="round"
          stroke-linejoin="round"
        />
        <circle
          v-bind="last"
          r="2"
          fill="currentColor"
        />
      </svg>

      <span class="text-tone text-xs font-semibold tabular-nums">+{{ gain }} cm</span>
    </span>
  </WListCardField>
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import {computed} from 'vue'

import type {FieldProps, ListField} from 'eco-vue-js/dist/components/List/types'

import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'

const props = defineProps<FieldProps<Plant>>()

defineEmits<{
  (e: 'update:item', value: Plant): void
  (e: 'delete:item'): void
}>()

const coordinates = computed(() => {
  const heights = props.item.growth.map(point => point.height)
  const min = Math.min(...heights)
  const range = Math.max(...heights) - min || 1

  return heights.map((height, index) => ({cx: index * 10, cy: 15 - (height - min) / range * 14}))
})

const points = computed(() => coordinates.value.map(({cx, cy}) => `${ cx },${ cy }`).join(' '))
const last = computed(() => coordinates.value[coordinates.value.length - 1])
const gain = computed(() => getGain(props.item))
</script>

<script lang="ts">
const getGain = (item: Plant) => item.height - item.growth[0]!.height

export const meta = {
  label: 'growth',
  width: '8rem',
  title: 'Growth',
  textFormat: item => `+${ getGain(item) } cm`,
} as const satisfies ListField<Plant>
</script>
```

```vue [WFieldPlantStatus.vue]
<template>
  <WListCardField
    :skeleton="skeleton"
    allow-open
  >
    <WChip
      :text="item.watered ? 'Watered' : 'Thirsty'"
      :semantic-type="item.watered ? SemanticType.POSITIVE : SemanticType.WARNING"
      :skeleton="skeleton"
    />
  </WListCardField>
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import type {FieldProps, ListField} from 'eco-vue-js/dist/components/List/types'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'

defineProps<FieldProps<Plant>>()

defineEmits<{
  (e: 'update:item', value: Plant): void
  (e: 'delete:item'): void
}>()
</script>

<script lang="ts">
export const meta = {
  label: 'watered',
  width: '7rem',
  cssClass: 'w-skeleton-h-5',
  title: 'Status',
  field: 'watered',
  textFormat: item => item.watered ? 'Watered' : 'Thirsty',
} as const satisfies ListField<Plant>
</script>
```

```vue [WFieldPlantWaterBy.vue]
<template>
  <WListCardField
    :skeleton="skeleton"
    allow-open
    :class="{
      'text-description': !item.waterBy,
      'tone-negative text-tone': item.waterBy && item.waterBy < today,
    }"
  >
    <template #inner>
      <span class="list:hidden">{{ meta.title }}: </span>
      {{ item.waterBy ? dateFormat(item.waterBy, {year: 'auto'}) : '-' }}
    </template>
  </WListCardField>
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import type {FieldProps, ListField} from 'eco-vue-js/dist/components/List/types'
import {dateFormat, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'

defineProps<FieldProps<Plant>>()

defineEmits<{
  (e: 'update:item', value: Plant): void
  (e: 'delete:item'): void
}>()

// Overdue plants are shown in red.
const today = getStartOfDay()
</script>

<script lang="ts">
export const meta = {
  label: 'due',
  width: '8rem',
  cssClass: 'card:text-xs',
  title: 'Water by',
  field: 'waterBy',
  textFormat: item => item.waterBy ? dateFormat(item.waterBy) : undefined,
} as const satisfies ListField<Plant>
</script>
```

```ts [fields/index.ts]
import type {QueryParamsPlants} from '../api/Plant'
import type {Plant} from '../models/Plant'

import type {ListFields} from 'eco-vue-js/dist/components/List/types'
import {getDefaultFieldConfigMap} from 'eco-vue-js/dist/utils/utils'

import * as FieldPlantCaretaker from './WFieldPlantCaretaker.vue'
import * as FieldPlantGrowth from './WFieldPlantGrowth.vue'
import * as FieldPlantHealth from './WFieldPlantHealth.vue'
import * as FieldPlantHeight from './WFieldPlantHeight.vue'
import * as FieldPlantHumidity from './WFieldPlantHumidity.vue'
import * as FieldPlantKind from './WFieldPlantKind.vue'
import * as FieldPlantLight from './WFieldPlantLight.vue'
import * as FieldPlantName from './WFieldPlantName.vue'
import * as FieldPlantSeeds from './WFieldPlantSeeds.vue'
import * as FieldPlantSpecies from './WFieldPlantSpecies.vue'
import * as FieldPlantStatus from './WFieldPlantStatus.vue'
import * as FieldPlantWater from './WFieldPlantWater.vue'
import * as FieldPlantWaterBy from './WFieldPlantWaterBy.vue'

export const listFieldsPlant = [
  FieldPlantName,
  FieldPlantSpecies,
  FieldPlantKind,
  FieldPlantLight,
  FieldPlantHeight,
  FieldPlantGrowth,
  FieldPlantHealth,
  FieldPlantWater,
  FieldPlantHumidity,
  FieldPlantSeeds,
  FieldPlantCaretaker,
  FieldPlantStatus,
  FieldPlantWaterBy,
] as const satisfies ListFields<Plant, QueryParamsPlants>

// Columns shown until the user changes them in the header settings. `species`, `height`, `water` and `seeds` start hidden.
export const defaultFieldConfigMapPlant = getDefaultFieldConfigMap(listFieldsPlant, [
  'name',
  'kind',
  'light',
  'growth',
  'health',
  'humidity',
  'caretaker',
  'watered',
  'due',
])
```

:::

`as const satisfies ListFields<…>` keeps the tuple literal, which is what lets TypeScript check the labels in `getDefaultFieldConfigMap` and `cardAreas` — a typo in either is a type error.

### Filters

`WListFilter` edits the same query params the list reads. Wrap it in a `WUniform` over `queryParams` and pass the `scope` down; `search` adds the search field. Put it in WList's `filter` slot and the filters sit in the selection bar, on one line with the list settings: each chip opens its control in a dropdown, the add button offers the rest, and chips that do not fit go into a "more" chip. While rows are selected, the bulk actions take the bar's place.

`pinned` filters are always shown, first — here kind and watered, the ones most often reached for. Their remove button only clears them, so they stay in the bar.

Each filter is a module like a field: the component renders the control inside a `WUniform` bound to its param, and `meta` gives the chip's `title`, `icon` and the `fields` it sets — removing the chip clears them. `meta.summary` returns the picked values for the chip from the query params — the kind and light names, "Watered" or "Thirsty", the caretaker's name. Without it, the chip shows how many values are picked. The control is the same one a form would use: a `WSelect` for kinds, a `WCheckboxGroupMultiple` for light, a radio `WCheckboxGroup` for watered, where `undefined` means "Any", and a `WSelectSingle` for the caretaker. The two selects reuse option components from the [Select](/components/select) examples — the tone tag and the gardener with their week of watering — so a kind looks the same in the filter as in its column.

The dropdown is titled with the filter's name and pads the control like a small form. `:embedded="!global"` drops the control's own title and margin, and lets a select's options and a checkbox list reach the dropdown's edges, as in a menu. With `global` the filters go into the app shell's filter panel instead, where each control keeps its title. A filter applies as it changes, so picking a caretaker closes the dropdown, as a single select's menu would — a multiple select stays open to pick more.

::: code-group

```vue [WFilterPlantKind.vue]
<template>
  <WUniform
    v-bind="scope"
    field="kind__in"
    title="Kind"
  >
    <template #field="scopeField">
      <WSelect
        v-bind="scopeField"
        :options="options"
        :value-getter="item => item.id"
        :search-fn="(item, search) => item.name.toLowerCase().includes(search)"
        :option-component="markRaw(OptionToneTag)"
        :readonly="readonly"
        placeholder="Search kinds"
        :embedded="!global"
        class="min-w-60"
      />
    </template>
  </WUniform>
</template>

<script lang="ts" setup>
import type {QueryParamsPlants} from '../api/Plant'

import {markRaw} from 'vue'

import type {FilterEmits, FilterMeta, FilterProps} from 'eco-vue-js/dist/components/List/types'

import WSelect from 'eco-vue-js/dist/components/Select/WSelect.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

import IconPlant from 'eco-vue-js/dist/assets/icons/IconPlant'

import OptionToneTag, {type ToneTag} from '../../../shared/OptionToneTag.vue'
import {Kind} from '../models/Plant'
import {kindDisplay} from '../models/PlantDisplay'

defineProps<FilterProps<QueryParamsPlants>>()
defineEmits<FilterEmits>()

// The same tags as the kind column, in the shape the shared tag option takes.
const options: ToneTag<Kind>[] = Object.values(Kind).map(id => ({id, ...kindDisplay[id]}))
</script>

<script lang="ts">
export const meta = {
  title: 'Kind',
  icon: markRaw(IconPlant),
  fields: ['kind__in'],
  // The chip names the picked kinds instead of counting them.
  summary: queryParams => queryParams.kind__in?.map(item => kindDisplay[item].name),
} as const satisfies FilterMeta<QueryParamsPlants>
</script>
```

```vue [WFilterPlantWatered.vue]
<template>
  <WUniform
    v-bind="scope"
    field="watered"
  >
    <template #field="scopeField">
      <!-- `undefined` is "Any": it drops the param, so the filter shows every plant. -->
      <WCheckboxGroup
        v-bind="scopeField"
        :list="[undefined, true, false]"
        radio
        :readonly="readonly"
        :embedded="!global"
        class="w-full"
        option-class="w-full"
      >
        <template #option="{option}">
          <div class="flex h-8 items-center">
            {{ option === true ? 'Watered' : option === false ? 'Thirsty' : 'Any' }}
          </div>
        </template>
      </WCheckboxGroup>
    </template>
  </WUniform>
</template>

<script lang="ts" setup>
import type {QueryParamsPlants} from '../api/Plant'

import {markRaw} from 'vue'

import type {FilterEmits, FilterMeta, FilterProps} from 'eco-vue-js/dist/components/List/types'

import WCheckboxGroup from 'eco-vue-js/dist/components/Checkbox/WCheckboxGroup.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

import IconDrop from 'eco-vue-js/dist/assets/icons/IconDrop'

defineProps<FilterProps<QueryParamsPlants>>()
defineEmits<FilterEmits>()
</script>

<script lang="ts">
export const meta = {
  title: 'Watered',
  icon: markRaw(IconDrop),
  fields: ['watered'],
  summary: queryParams => queryParams.watered === undefined ? undefined : queryParams.watered ? 'Watered' : 'Thirsty',
} as const satisfies FilterMeta<QueryParamsPlants>
</script>
```

```ts [filter/index.ts]
import type {QueryParamsPlants} from '../api/Plant'

import type {FilterComponent} from 'eco-vue-js/dist/components/List/types'

import * as FilterPlantCaretaker from './WFilterPlantCaretaker.vue'
import * as FilterPlantKind from './WFilterPlantKind.vue'
import * as FilterPlantLight from './WFilterPlantLight.vue'
import * as FilterPlantWatered from './WFilterPlantWatered.vue'

// In the order they are offered by the add-filter button.
export const listFilterPlant = [
  FilterPlantKind,
  FilterPlantLight,
  FilterPlantWatered,
  FilterPlantCaretaker,
] satisfies FilterComponent<QueryParamsPlants>[]

// Always shown as chips, first; the rest are behind the add-filter button.
export const listFilterPlantPinned = [
  FilterPlantKind,
] satisfies FilterComponent<QueryParamsPlants>[]
```

:::

### Row menu

Menu items receive the row and call the model's actions. The actions update the cached pages themselves, so the list changes without a refetch. The menu also gets `updateItem` and `deleteItem`, which write the row to the cache or remove it without a request — e.g. to drop a row that was never saved.

Always type menu components with `MenuProps<T>` and `MenuEmits<T>` from the kit — a hand-written props shape breaks when the kit adds a prop.

::: code-group

```vue [WMenuPlantToggle.vue]
<template>
  <WButtonMoreItem
    :text="item.watered ? 'Mark as dry' : 'Mark as watered'"
    :icon="markRaw(item.watered ? IconSun : IconDrop)"
    :disabled="readonly"
    @click="toggle"
  />
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import {markRaw} from 'vue'

import type {MenuEmits, MenuProps} from 'eco-vue-js/dist/components/List/types'
import {Notify} from 'eco-vue-js/dist/utils/Notify'
import {handleApiError} from 'eco-vue-js/dist/utils/api'
import {addDay, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import WButtonMoreItem from 'eco-vue-js/dist/components/Button/WButtonMoreItem.vue'

import IconDrop from 'eco-vue-js/dist/assets/icons/IconDrop'
import IconSun from 'eco-vue-js/dist/assets/icons/IconSun'

import {plantModelApi} from '../api/Plant'

const props = defineProps<MenuProps<Plant>>()

defineEmits<MenuEmits<Plant>>()

const toggle = () => plantModelApi.item.actions
  // The action puts the saved plant into every cached page that holds it, so the row updates without a refetch.
  .update(props.item.id, {
    watered: !props.item.watered,
    // Dry soil needs water within three days.
    waterBy: props.item.watered ? addDay(getStartOfDay(), 3) : null,
  })
  .then(plant => Notify.success({title: plant.watered ? 'Marked as watered' : 'Marked as dry'}))
  .catch(handleApiError)
</script>
```

```vue [WMenuPlantDelete.vue]
<template>
  <WButtonMoreItem
    text="Remove"
    :icon="markRaw(IconTrash)"
    :disabled="readonly"
    @click="remove"
  />
</template>

<script lang="ts" setup>
import type {Plant} from '../models/Plant'

import {markRaw} from 'vue'

import type {MenuEmits, MenuProps} from 'eco-vue-js/dist/components/List/types'
import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {handleApiError} from 'eco-vue-js/dist/utils/api'

import WButtonMoreItem from 'eco-vue-js/dist/components/Button/WButtonMoreItem.vue'

import IconTrash from 'eco-vue-js/dist/assets/icons/IconTrash'

import {Notify} from '@/utils/Notify'

import {plantModelApi} from '../api/Plant'

const props = defineProps<MenuProps<Plant>>()

defineEmits<MenuEmits<Plant>>()

// Opened from the row menu, the confirm takes its place — under the `⋯` button, or where the row was right-clicked — and keeps the row highlighted.
const overlay = useOverlay()

const remove = () => {
  const name = props.item.name
  overlay.addConfirm({
    title: 'Remove plant',
    description: `"${ name }" will be removed from the collection.`,
    acceptText: 'Remove',
    acceptSemanticType: SemanticType.NEGATIVE,
    // The confirm shows a loading state until the action resolves, which also drops the plant from every cached page.
    onAccept: () => plantModelApi.item.actions.delete(props.item.id)
      .then(() => {
        Notify.success({title: `"${ name }" removed`})
      })
      .catch(handleApiError),
  })
}
</script>
```

:::

`Modal.addConfirm` keeps the confirm open with a spinner while `onAccept`'s promise is pending, closes it when the promise resolves, and leaves it open if it rejects — so return the action's promise.

Opened with `useOverlay()` from the menu, the confirm takes the menu's place as a dropdown — a bottom sheet on phones — instead of a modal, so the list stays in view. It opens under the row's `⋯` button, or where the row was right-clicked, and the row stays highlighted until it closes.

### Bulk actions

Bulk components sit in the bar above the list and act on the selected rows. They get the `selectionCount` and a `queryParamsGetter` that returns the list's query params narrowed to the selection, which the model's bulk actions send as they are. Call `clearSelection()` to reset the selection once the action is done.

Each confirm opens under its button, like a filter's dropdown, so the selected rows stay in view. Actions that do not fit the bar — on phones, all but the first two buttons — move into a More menu, and there the confirm opens under the More button instead. A click outside closes the confirm, so changing the selection cancels it. Once accepted, the page is held still until the request settles, so the selection and filters cannot change under it.

::: code-group

```vue [WBulkPlantRemove.vue]
<template>
  <WButtonSelectionAction
    title="Remove"
    :icon="markRaw(IconTrash)"
    :disable-message="disableMessage"
    :disabled="readonly"
    :active="isOpen"
    @click="remove"
  />
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import type {BulkProps} from 'eco-vue-js/dist/components/List/types'
import {Notify} from 'eco-vue-js/dist/utils/Notify'
import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {handleApiError} from 'eco-vue-js/dist/utils/api'

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

import IconTrash from 'eco-vue-js/dist/assets/icons/IconTrash'

import {numberFormatter} from '@/utils/utils'

import {type QueryParamsPlants, plantModelApi} from '../api/Plant'

const props = defineProps<BulkProps<QueryParamsPlants>>()

const overlay = useOverlay()

const isOpen = ref(false)

const remove = (event: MouseEvent) => {
  isOpen.value = true

  const countText = `${ numberFormatter.format(props.selectionCount) } plant${ props.selectionCount === 1 ? '' : 's' } `

  overlay.addConfirm({
    title: `Remove ${ countText }?`,
    description: 'They will be removed from the collection.',
    acceptText: 'Remove',
    acceptSemanticType: SemanticType.NEGATIVE,
    // Opens under the button, or under More when the action sits in that menu, so the selected rows stay in view.
    anchor: event.currentTarget as Element,
    // The page is held still until the request settles, so the selection cannot change under it.
    onAccept: () => plantModelApi.paginated.actions.deleteMany(props.queryParamsGetter())
      .then(() => {
        Notify.success({title: `${ countText } removed`})
        // A function, not an emit: in the More menu this component is gone by now, as the confirm took the menu's place.
        props.clearSelection()
      })
      .catch(handleApiError),
  }, () => isOpen.value = false)
}
</script>
```

```vue [WBulkPlantDry.vue]
<template>
  <WButtonSelectionAction
    title="Mark as dry"
    :icon="markRaw(IconSun)"
    :disable-message="disableMessage"
    :disabled="readonly"
    :active="isOpen"
    @click="markDry"
  />
</template>

<script lang="ts" setup>
import {markRaw, ref} from 'vue'

import type {BulkProps} from 'eco-vue-js/dist/components/List/types'
import {Notify} from 'eco-vue-js/dist/utils/Notify'
import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'
import {handleApiError} from 'eco-vue-js/dist/utils/api'
import {addDay, getStartOfDay} from 'eco-vue-js/dist/utils/dateTime'

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

import IconSun from 'eco-vue-js/dist/assets/icons/IconSun'

import {numberFormatter} from '@/utils/utils'

import {type QueryParamsPlants, plantModelApi} from '../api/Plant'

const props = defineProps<BulkProps<QueryParamsPlants>>()

const overlay = useOverlay()

const isOpen = ref(false)

const markDry = (event: MouseEvent) => {
  isOpen.value = true

  const countText = `${ numberFormatter.format(props.selectionCount) } plant${ props.selectionCount === 1 ? '' : 's' } `

  overlay.addConfirm({
    title: `Mark ${ countText } as dry?`,
    description: 'They will need water within three days.',
    acceptText: 'Mark as dry',
    anchor: event.currentTarget as Element,
    // Dry soil needs water within three days.
    onAccept: () => plantModelApi.paginated.actions.updateMany(props.queryParamsGetter(), {watered: false, waterBy: addDay(getStartOfDay(), 3)})
      .then(() => {
        Notify.success({title: `${ countText } marked as dry`})
      })
      .catch(handleApiError),
  }, () => isOpen.value = false)
}
</script>
```

:::

#### Actions with a form

An action that needs input, such as a new caretaker, opens a small form instead of a confirm: `useOverlay().open` with `present: 'dropdown'` puts it under the button — a bottom sheet on phones — and the same form serves the bulk action and the row menu. From the More menu or a row's `⋯` menu, it takes the menu's place, as a confirm does.

The form is a `WModalWrapper` with a `WUniform` inside, the way it would be in a modal. The frame takes its title and buttons and pads the field, so the form brings no padding or layout for being in a dropdown, and it would open as a modal unchanged. The select is `embedded`, as in a filter: its search is pinned under the title and the caretakers are listed in place of a menu, with Save and Cancel pinned under them — unlike the filter, a pick waits for Save, so the list stays open. A click outside, Escape or a swipe dismisses it like a menu, and while the form saves, the dropdown stays open.

```vue [PlantCaretakerForm.vue]
<template>
  <!--
    A small form, opened as a dropdown at the button — a bottom sheet on phones — or as a modal: the frame places its title and buttons.
    The select is embedded, as in a filter: its search field is pinned under the title, and the caretakers are listed in place of a menu.
  -->
  <WModalWrapper>
    <template #title>
      Change caretaker of {{ countText }}
    </template>

    <WUniform
      ref="form"
      :init-data="() => ({caretaker})"
      :api-method="save"
      full-payload
      @success="$emit('close:modal')"
    >
      <template #default="scope">
        <WUniform
          v-bind="scope"
          field="caretaker"
          title="Caretaker"
          required
        >
          <template #field="scopeField">
            <WSelectSingle
              v-bind="scopeField"
              :options="gardeners"
              :value-getter="item => item.id"
              :search-fn="(item, search) => item.name.toLowerCase().includes(search)"
              :option-component="markRaw(OptionGardener)"
              placeholder="Search caretakers"
              required
              embedded
            />
          </template>
        </WUniform>
      </template>
    </WUniform>

    <template #actions>
      <WButton
        :disabled="formRef?.submitting"
        :semantic-type="SemanticType.SECONDARY"
        class="w-full"
        @click="$emit('close:modal')"
      >
        Cancel
      </WButton>

      <WButton
        :disabled="!formRef?.hasChanges"
        :loading="formRef?.submitting"
        class="w-full"
        @click="formRef?.submit?.()"
      >
        Save
      </WButton>
    </template>
  </WModalWrapper>
</template>

<script lang="ts" setup>
import {markRaw, useTemplateRef} from 'vue'

import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'

import WButton from 'eco-vue-js/dist/components/Button/WButton.vue'
import WModalWrapper from 'eco-vue-js/dist/components/Modal/WModalWrapper.vue'
import WSelectSingle from 'eco-vue-js/dist/components/Select/WSelectSingle.vue'
import WUniform from 'eco-vue-js/dist/components/Uniform/WUniform.vue'

import {Notify} from '@/utils/Notify'
import {numberFormatter} from '@/utils/utils'

import {type QueryParamsPlants, plantModelApi} from './api/Plant'

import {gardeners} from '../../shared/Gardener'
import OptionGardener from '../../shared/OptionGardener.vue'

type CaretakerFormData = {
  caretaker: number | undefined
}

const props = defineProps<{
  /** The plants to change: the list's filters and selection, or one plant by id. */
  queryParams: QueryParamsPlants
  count: number
  /** Current caretaker, known for one plant, which the form starts with. */
  caretaker?: number
  /** Called once saved, such as to clear the selection. */
  onSaved?: () => void
}>()

defineEmits<{
  (e: 'close:modal'): void
}>()

const formRef = useTemplateRef('form')

const countText = `${ numberFormatter.format(props.count) } plant${ props.count === 1 ? '' : 's' }`

const save = (payload: Partial<CaretakerFormData>) => {
  return plantModelApi.paginated.actions.updateMany(props.queryParams, {caretaker: payload.caretaker})
    .then(() => {
      Notify.success({title: `Caretaker changed for ${ countText }`})
      props.onSaved?.()
    })
}
</script>
```

```vue [WBulkPlantCaretaker.vue]
<template>
  <WButtonSelectionAction
    title="Change caretaker"
    :icon="markRaw(IconUser)"
    :disable-message="disableMessage"
    :disabled="readonly"
    :active="isOpen"
    @click="openForm"
  />
</template>

<script lang="ts" setup>
import {defineAsyncComponent, markRaw, ref} from 'vue'

import type {BulkProps} from 'eco-vue-js/dist/components/List/types'
import {useOverlay} from 'eco-vue-js/dist/utils/Overlay'

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

import IconUser from 'eco-vue-js/dist/assets/icons/IconUser'

import {type QueryParamsPlants} from '../api/Plant'

const PlantCaretakerForm = defineAsyncComponent(() => import('../PlantCaretakerForm.vue'))

const props = defineProps<BulkProps<QueryParamsPlants>>()

const overlay = useOverlay()

const isOpen = ref(false)

// The form opens at the button, so the selected rows stay in view.
const openForm = (event: MouseEvent) => {
  isOpen.value = true

  overlay.open({
    present: 'dropdown',
    anchor: event.currentTarget as Element,
    content: markRaw(PlantCaretakerForm),
    props: {
      queryParams: props.queryParamsGetter(),
      count: props.selectionCount,
      // A function, not an emit: in the More menu this component is gone by now, as the form took the menu's place.
      onSaved: props.clearSelection,
    },
    onClose: () => isOpen.value = false,
  })
}
</script>
```

### Expansion

The expansion gets the row's `item` and has the full width of the list, so it can hold what does not fit in a cell: here the care facts, a growth chart with a tooltip per month, a four-week watering calendar and the next tasks. While the row loads, `skeleton` is set and `item` may be `undefined` — each section shows its own placeholder.

```vue [PlantContent.vue]
<template>
  <div class="grid gap-4 py-2 md:grid-cols-3">
    <!-- Care: what the plant needs, each fact in its own tone. -->
    <section class="grid content-start gap-3 p-4 rounded-2xl bg-surface-subtle">
      <WSkeleton
        v-if="skeleton || !item"
        class="w-skeleton-h-20"
      />

      <template v-else>
        <p class="text-description text-sm">
          {{ item.description }}
        </p>

        <div class="grid grid-cols-2 gap-2">
          <div
            v-for="fact in getFacts(item)"
            :key="fact.title"
            class="flex items-center gap-2"
            :class="fact.tone"
          >
            <span class="surface-soft text-tone flex size-8 shrink-0 items-center justify-center rounded-full">
              <component
                :is="fact.icon"
                class="square-4"
              />
            </span>

            <span class="grid min-w-0">
              <span class="text-description truncate text-xs">{{ fact.title }}</span>
              <span class="truncate text-sm font-semibold tabular-nums">{{ fact.value }}</span>
            </span>
          </div>
        </div>
      </template>
    </section>

    <!-- Growth: the six-month height as a chart, with a tooltip per month. -->
    <section class="grid content-start gap-1 p-4 rounded-2xl bg-surface-subtle">
      <h4 class="flex items-baseline justify-between text-sm font-semibold">
        Growth
        <span
          v-if="item && !skeleton"
          class="tone-data-green text-tone text-xs tabular-nums"
        >+{{ item.height - item.growth[0]!.height }} cm in 6 months</span>
      </h4>

      <WChartLinear
        :x-domain="xDomain"
        :height="176"
        :skeleton="skeleton || !item"
        y-hidden
      >
        <template #default="scope">
          <WChartLine
            v-if="item"
            v-bind="scope"
            :data="item.growth.toReversed()"
            x-key="date"
            y-key="height"
            has-area
            calc-min
            class="tone-data-green text-tone"
          >
            <template #tooltip="{d, prev}">
              <div class="grid text-sm text-start">
                <span class="text-description">{{ dateFormat(new Date(d.date), {year: 'auto'}) }}</span>
                <span>
                  <span class="font-semibold">{{ d.height }} cm</span> <span
                    v-if="prev"
                    class="text-description"
                  >+{{ d.height - prev.height }} cm that month</span>
                </span>
              </div>
            </template>
          </WChartLine>
        </template>
      </WChartLinear>
    </section>

    <!-- Schedule: a four-week watering calendar and the next tasks. -->
    <section class="grid content-start gap-4 p-4 rounded-2xl bg-surface-subtle">
      <div class="grid gap-2">
        <h4 class="flex items-baseline justify-between gap-4 text-sm font-semibold">
          Watering
          <span
            v-if="item && !skeleton"
            class="text-description text-xs font-normal"
          >{{ item.waterings.length }} times in 4 weeks</span>
        </h4>

        <WSkeleton
          v-if="skeleton || !item"
          class="w-skeleton-h-16"
        />

        <!-- One square a day, oldest first, filled on the days it was watered. -->
        <div
          v-else
          class="tone-data-blue grid grid-cols-7 gap-1"
        >
          <span
            v-for="day in days"
            :key="+day"
            class="h-3.5 rounded-sm"
            :class="item.waterings.some(watering => isSameDate(watering, day)) ? 'bg-tone-fill' : 'bg-tone-soft'"
            :title="dateFormat(day)"
          />
        </div>
      </div>

      <div class="grid gap-1.5">
        <h4 class="text-sm font-semibold">
          Next up
        </h4>

        <WSkeleton
          v-if="skeleton || !item"
          class="w-skeleton-h-16"
        />

        <ul
          v-else
          class="grid gap-1"
        >
          <li
            v-for="task in item.tasks"
            :key="task.title"
            class="flex items-center justify-between gap-2 text-sm"
          >
            {{ task.title }}

            <WChip
              :text="getDueText(task.due)"
              :semantic-type="task.due < today ? SemanticType.NEGATIVE : task.due <= soon ? SemanticType.WARNING : SemanticType.SECONDARY"
            />
          </li>
        </ul>
      </div>
    </section>
  </div>
</template>

<script lang="ts" setup>
import type {QueryParamsPlants} from './api/Plant'
import type {Plant} from './models/Plant'

import {markRaw} from 'vue'

import type {FieldProps} from 'eco-vue-js/dist/components/List/types'
import {SemanticType} from 'eco-vue-js/dist/utils/SemanticType'
import {addDay, addMonth, dateFormat, getStartOfDay, isSameDate} from 'eco-vue-js/dist/utils/dateTime'

import WChartLine from 'eco-vue-js/dist/components/Chart/WChartLine.vue'
import WChartLinear from 'eco-vue-js/dist/components/Chart/WChartLinear.vue'
import WChip from 'eco-vue-js/dist/components/Chip/WChip.vue'
import WSkeleton from 'eco-vue-js/dist/components/Skeleton/WSkeleton.vue'

import IconDrop from 'eco-vue-js/dist/assets/icons/IconDrop'
import IconThermometer from 'eco-vue-js/dist/assets/icons/IconThermometer'
import IconWind from 'eco-vue-js/dist/assets/icons/IconWind'

import {lightDisplay} from './models/PlantDisplay'

defineProps<Omit<FieldProps<Plant | undefined, QueryParamsPlants>, 'config'>>()

const today = getStartOfDay()
const soon = addDay(today, 3)
const xDomain: [number, number] = [+addMonth(today, -5), +today]

// The last four weeks, oldest first.
const days = Array.from({length: 28}, (_, index) => addDay(today, index - 27))

const getFacts = (item: Plant) => [
  {title: 'Light', value: lightDisplay[item.light].name, tone: lightDisplay[item.light].tone, icon: lightDisplay[item.light].icon},
  {title: 'Water', value: `${ item.water } ml`, tone: 'tone-data-blue', icon: markRaw(IconDrop)},
  {title: 'Humidity', value: `${ item.humidity }%`, tone: 'tone-data-cyan', icon: markRaw(IconWind)},
  {title: 'Temperature', value: `${ item.temperature[0] }–${ item.temperature[1] } °C`, tone: 'tone-data-red', icon: markRaw(IconThermometer)},
]

const getDueText = (due: Date) => {
  const left = Math.round((+due - +today) / 86_400_000)

  if (left < 0) return `${ -left } d overdue`
  if (left === 0) return 'Today'
  return `In ${ left } d`
}
</script>
```

## Why it is built this way

* **One component per column** makes columns reusable across lists of the same model, lets each cell own its formatting and loading state, and keeps the column list declarative, so `WList` can reorder, hide and resize columns without knowing what they render.
* **Query params are the whole state.** Search, filters and ordering go into `queryParams`; `WList` adds `page` and emits `update:query-params` when the user sorts. With `createUseQueryParams` they live in the route query, so the list is linkable and survives reloads.
* **Card layout is data, not markup.** `cardColumns` and `cardAreas` place the same field components into a CSS grid for the mobile card view, using the field labels as area names. `area_select` and `area_more` place the checkbox and the menu. Name every field, including ones hidden by default: a field left out still renders in card mode, in an extra column the grid adds for it. A row whose fields are all hidden drops out, so the `water`/`seeds` and `kind` rows cost nothing until the user shows those columns.
* **Cache updates instead of refetching.** The model's actions update the item in every cached page, so the user keeps their scroll position and loaded pages.

## Variations

* **Filters above the list**: render the `WUniform` with `WListFilter` before `WList` instead of in its `filter` slot, and the chips wrap onto as many lines as they need.
* **Filters in the app shell**: pass `global` to `WListFilter` to put the filters into the actions bar's panel and the search into the header bar, with a button that resets them. `disabledFilterFields` leaves out filters for params the page fixes, e.g. `caretaker` on a caretaker's own page.
* **Toolbar actions** (e.g. "Create"): pass `action` with components typed by `ActionProps<QueryParams>`.
* **Nested columns**: a field's `meta` can be `{keyEntity, fields}` or `{keyArray, fields}` to render columns of a related object or of every item in an array — see [Nested fields](/components/list#nested-fields).
* **Embedded lists**: a list is sized as a page by default — it reserves the viewport height. Inside a card, tab or docs page like this one, pass `min-height` to drop that.
* **Read-only rows**: `readonlyGetter` marks individual rows read-only; menu items receive `readonly` and should disable themselves.