# EcoVue UI Library

> One Vue 3 UI kit for your entire ecosystem — lists, forms and a data layer for complex data, live theming, icons and a ready project setup on Tailwind v4.

## Table of Contents

### Guide

- [Getting started](https://rsmple.github.io/eco-vue-js/guide/getting-started.md): Install eco-vue-js, wire Tailwind v4, vue-query and the global containers (modals, notifications, tooltips), and import components.
- [App shell](https://rsmple.github.io/eco-vue-js/guide/app-shell.md): 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.
- [Conventions](https://rsmple.github.io/eco-vue-js/guide/conventions.md): 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.
- [Data layer](https://rsmple.github.io/eco-vue-js/guide/data-layer.md): 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.
- [Theming](https://rsmple.github.io/eco-vue-js/guide/theming.md): 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.
- [Releases](https://rsmple.github.io/eco-vue-js/releases.md): Release notes for every eco-vue-js version, newest first — what changed in each component and what breaks on upgrade.

### Layout

- [Actions bar](https://rsmple.github.io/eco-vue-js/components/actions-bar.md): WActionsBar, WActionsBarFilter and WButtonAction — the app's bar of icon buttons on the right, with a filter panel that pages slide out of it.
- [Header bar](https://rsmple.github.io/eco-vue-js/components/header-bar.md): WHeaderBar and WHeaderBarSearch — the app's fixed header with the page title and buttons, and a search that a page puts into it.
- [Nav bar](https://rsmple.github.io/eco-vue-js/components/nav-bar.md): 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.

### Actions

- [Button](https://rsmple.github.io/eco-vue-js/components/button.md): WButton — the base action element with semantic colors, loading and disabled states, links and tooltips — plus WButtonCopy and WButtonInput.
- [Links](https://rsmple.github.io/eco-vue-js/components/links.md): WLink and WLinkArrow text links, and WRouterLink that works with or without vue-router.

### Controls

- [Input](https://rsmple.github.io/eco-vue-js/components/input.md): WInput — text, number, password and multiline inputs with titles, clear button, states and validation, plus WInputAsync and WInputDate.
- [Select](https://rsmple.github.io/eco-vue-js/components/select.md): WSelectSingle, WSelect and their async variants — searchable selects over a static list or a paginated query, with a custom option template.
- [Toggle](https://rsmple.github.io/eco-vue-js/components/toggle.md): 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.
- [Checkbox](https://rsmple.github.io/eco-vue-js/components/checkbox.md): 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.
- [Form](https://rsmple.github.io/eco-vue-js/components/form.md): 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.
- [Button group](https://rsmple.github.io/eco-vue-js/components/button-group.md): WButtonGroup — a segmented control that picks one value out of a short list, bound with v-model.
- [Date picker](https://rsmple.github.io/eco-vue-js/components/date-picker.md): WDatePicker and WDatePickerSingle — calendars for picking a date range or a single day, limited by minDate and maxDate.
- [Field wrapper](https://rsmple.github.io/eco-vue-js/components/field-wrapper.md): 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.
- [File picker](https://rsmple.github.io/eco-vue-js/components/file-picker.md): WFilePicker — a drop zone with a browse button for one or several files, with a placeholder for a file that is already saved.
- [Slider](https://rsmple.github.io/eco-vue-js/components/slider.md): WSlider and WSliderRange — pick a number or a range by dragging, with an eager value while dragging and colors set by utilities.
- [Tabs](https://rsmple.github.io/eco-vue-js/components/tabs.md): WTabs and WTabsItem — tabbed content with icons, counters and disabled tabs, closable and added tabs, a side layout, and status marks for forms.

### Display

- [Chip](https://rsmple.github.io/eco-vue-js/components/chip.md): WChip — a short label in a colored box, such as a tag or a status flag, with a skeleton state.
- [Counter](https://rsmple.github.io/eco-vue-js/components/counter.md): WCounter — a round badge with a number in compact notation, which shakes when the count changes.
- [Expansion](https://rsmple.github.io/eco-vue-js/components/expansion.md): WExpansion and WExpansionItem — content that expands and collapses with an animated height, and a toggle row with a title for accordions.
- [Image viewer](https://rsmple.github.io/eco-vue-js/components/image-viewer.md): WImageViewer — an image URL as a thumbnail with its file name that opens the full image in a modal.
- [Info card](https://rsmple.github.io/eco-vue-js/components/info-card.md): WInfoCard and WInfoCardNegative — notes with an icon in the color of their semantic type, and a card for an error or an empty state.
- [Number formatter](https://rsmple.github.io/eco-vue-js/components/number-formatter.md): WNumberFormatter — a number with thousands separators, a fraction as a percentage, or a compact number with the full value in a tooltip.
- [Page error](https://rsmple.github.io/eco-vue-js/components/page-error.md): WPageError — replaces a page whose query failed with the status, the server's message, Back and, when asking again may help, Retry.
- [Progress](https://rsmple.github.io/eco-vue-js/components/progress.md): WProgress, WProgressStriped and WProgressBar — a thin line, a slim striped bar and a large bar with the percentage, for the progress of a task.
- [Query boundary](https://rsmple.github.io/eco-vue-js/components/query-boundary.md): WQueryBoundary — stops the skeletons of a card whose query failed and shows why, with Retry when asking again may help.
- [Query status](https://rsmple.github.io/eco-vue-js/components/query-status.md): WQueryStatus — one message for the whole app when queries on screen fail to load, with Retry, and frozen skeletons while the server is down.
- [Skeleton](https://rsmple.github.io/eco-vue-js/components/skeleton.md): WSkeleton — a shimmering placeholder for content that is still loading, shaped with the w-skeleton-* utilities.
- [Spinner](https://rsmple.github.io/eco-vue-js/components/spinner.md): WSpinner — an indeterminate spinner in the current text color, sized with square-*.
- [Status icon](https://rsmple.github.io/eco-vue-js/components/status-icon.md): WStatusIcon — a check, an exclamation mark or a dimmed slash for whether something is filled in or has errors.
- [Text overflow](https://rsmple.github.io/eco-vue-js/components/text-overflow.md): WTextOverflow — one line cut at its width that scrolls the rest into view on hover, of itself or of a group/overflow parent.

### Data

- [Charts](https://rsmple.github.io/eco-vue-js/components/charts.md): WChartLinear and WChartLine for values over time, with bands, areas, gradients and tooltips, and WChartHeatmap for a year of daily values.
- [Drag container](https://rsmple.github.io/eco-vue-js/components/drag-container.md): WDragContainer — lets the user reorder a list by dragging its items by a handle, emitting the new order once an item is dropped.
- [Infinite list](https://rsmple.github.io/eco-vue-js/components/infinite-list.md): 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.
- [List](https://rsmple.github.io/eco-vue-js/components/list.md): WList — paginated, sortable collections shown as a table on desktop and cards on mobile, with one field component per column.
- [Report pages](https://rsmple.github.io/eco-vue-js/components/report-pages.md): 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.

### Overlays

- [Bottom sheet](https://rsmple.github.io/eco-vue-js/components/bottom-sheet.md): WBottomSheet and WDismissable — the phone version of a dropdown, a sheet that slides up from the bottom and closes when swiped down.
- [Dropdown](https://rsmple.github.io/eco-vue-js/components/dropdown.md): 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 menu](https://rsmple.github.io/eco-vue-js/components/dropdown-menu.md): 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.
- [Modal](https://rsmple.github.io/eco-vue-js/components/modal.md): 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.
- [Notify](https://rsmple.github.io/eco-vue-js/components/notify.md): 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.
- [Tooltip](https://rsmple.github.io/eco-vue-js/components/tooltip.md): WTooltip — a hover tooltip placed inside the element it describes, with text or rich content, placement, delay and overflow-only mode.

### Utilities

- [Border SVG](https://rsmple.github.io/eco-vue-js/components/border-svg.md): WBorderSvg — a border drawn as SVG over a positioned element, for dashes a CSS border can't do or a border that moves.
- [Click outside](https://rsmple.github.io/eco-vue-js/components/click-outside.md): WClickOutside — emits click on a click or right-click anywhere outside it, to close or finish what's inside.
- [Composables](https://rsmple.github.io/eco-vue-js/utilities/composables.md): Composables from eco-vue-js — useCopy for the clipboard, useComponentStates for inherited readonly, disabled and skeleton states, useIsMobile, useTabActiveListener and useOptionalRouter.
- [Empty component](https://rsmple.github.io/eco-vue-js/components/empty-component.md): WEmptyComponent — renders its slot without an element, as the "off" branch of an optional wrapper.
- [Formatting](https://rsmple.github.io/eco-vue-js/utilities/formatting.md): 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.
- [Helpers](https://rsmple.github.io/eco-vue-js/utilities/helpers.md): 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.
- [Shine](https://rsmple.github.io/eco-vue-js/components/shine.md): WShine and WShineEffect — the light that sweeps across action buttons every few seconds, driven by one effect mounted at the app root.

### Assets

- [Icons](https://rsmple.github.io/eco-vue-js/icons.md): Every icon shipped with eco-vue-js, with a searchable gallery and the import path for each.

### Recipes

- [Form in three modes](https://rsmple.github.io/eco-vue-js/recipes/form-in-three-modes.md): 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.
- [List with fields](https://rsmple.github.io/eco-vue-js/recipes/list-with-fields.md): 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.