@querry-kit/nuxt-ui

Composable Nuxt UI table controls for Query Kit applications: toolbar, sorting, filtering, column preferences, pagination and keyboard shortcuts. Every public component begins with Q, and the package does not depend on application stores, layouts or runtime configuration.

📖 Documentation: https://querry-kit.github.io/nuxt-ui/

🌐 Querry Kit Ecosystem

The Querry Kit overview connects the three main repositories:

• @querry-kit/nest for the Query Kit-compatible NestJS API and controller patterns.
• @querry-kit/nuxt for typed API clients and headless Vue/Nuxt data primitives.
• @querry-kit/nuxt-ui for Nuxt UI integrations built on these primitives.

It also contains the complete Workboard API-and-web-app example, which shows the packages working together end to end.

📚 Table of Contents

• 🌐 Querry Kit Ecosystem
• 📦 Install
• 🚀 Release Workflow
• 🧩 Usage
• 🧱 Components
• 📖 Documentation
• 🛠 Development

📦 Install

pnpm add @querry-kit/nuxt @querry-kit/nuxt-ui @nuxt/ui

Register Nuxt UI before this module. Components use the host application's querrykit.table.* i18n keys when available and otherwise fall back to English strings.

export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@querry-kit/nuxt-ui'],
  querryKitUi: { autoImports: true },
});

Set autoImports to false when the application registers the components itself. The package never installs, configures, or ships an i18n provider. Pass a texts prop for explicit component text overrides, or replace display regions with the documented slots.

The current package version is published on npm. npm is the primary distribution channel.

GitHub release tags remain available as a fallback:

pnpm add github:querry-kit/nuxt-ui#v0.0.1

🚀 Release Workflow

Releases are driven by Changesets and GitHub Actions. The main branch contains source, documentation, screenshot baselines and workflow configuration; published package files are built in CI.

Package-visible changes should include a changeset:

pnpm changeset

When changes land on main, the changesets workflow creates or updates a release PR. That PR contains the version bump and changelog updates produced by:

pnpm changeset version

The npm publish workflow uses npm Trusted Publishing through GitHub Actions OIDC. The npm package must be connected to this repository and workflow in the npm package publishing settings:

• Repository: querry-kit/nuxt-ui
• Workflow file: release.yml
• Environment: unset

After the release PR is merged, the publish workflow runs the package checks, builds the package, publishes @querry-kit/nuxt-ui to npm, tags the release as vX.Y.Z, and creates a GitHub Release.

Consumers should install from npm:

pnpm add @querry-kit/nuxt-ui

🧩 Usage

QTableToolbar composes a breadcrumb, search input, create action and table controls. It does not own table data or perform filtering itself: applications bind the models they need and receive immutable replacement values.

<QTableToolbar
  v-model:search="search"
  v-model:sorting="sorting"
  v-model:filtering="filtering"
  v-model:column-order="columnOrder"
  v-model:invisible-columns="invisibleColumns"
  v-model:column-pinning="columnPinning"
  :sortable-fields="sortableFields"
  :filter-fields="filterFields"
  :column-definitions="columns"
/>

Use :shortcuts="false" on an individual component to disable its keyboard listener. The toolbar and individual controls can also be customized through slots without duplicating their state logic.

See Types and text customization for the complete key list, texts examples, and slot customization.

🧱 Components

| Component | Purpose | Documentation | | ------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------- | | QTableToolbar | Combines breadcrumb, search, create actions and controls. | Table toolbar | | QTableSorting | Manages ordered sorting with ascending/descending directions. | Sorting | | QTableFiltering | Edits Query Kit-compatible AND/OR filtering state. | Filtering | | QTableOptions | Reorders, hides and pins columns. | Column options | | QTablePagination | Renders a standalone, page-based API footer. | Pagination |

Public component types such as FilterField, FilterFieldType, SortingState, Filtering, ColumnDefinition and ColumnPinning are exported from @querry-kit/nuxt-ui/types. Query state contracts remain compatible with @querry-kit/nuxt.

📖 Documentation

• Getting Started
• Table Toolbar
• Sorting
• Filtering
• Column Options
• Pagination
• Types and text customization

Run the VitePress documentation locally:

pnpm docs:dev

Build the documentation:

pnpm docs:build

🛠 Development

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm build
pnpm docs:build

pnpm test:coverage collects all source files, prints the coverage summary, and writes HTML and LCOV reports to coverage/. GitHub Actions runs the same command and retains the report as a workflow artifact.

When updating component documentation, regenerate visual baselines locally and review the changed PNG files before committing:

pnpm screenshots:update