@querry-kit/nuxt-ui

@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/querry-kit/docs/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 @iconify-json/tabler

Register Nuxt UI before this module. The table controls use Tabler icons by default, so the host application must install @iconify-json/tabler. 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 nested texts or icons props for explicit overrides, or replace display regions with the documented slots.

When overriding icons, install the matching Iconify collection in the host application. For example, install Lucide with pnpm add @iconify-json/lucide before passing i-lucide-* values. See types, text, and icon customization for Lucide and Tabler examples.

Configure table-wide icon defaults in the host application's app.config.ts. A component's icons prop overrides this configuration, while the existing flat icon prop remains authoritative for an individual trigger:

export default defineAppConfig({
  querryKit: {
    table: {
      icons: {
        sorting: { trigger: 'i-lucide-arrow-up-down' },
        filtering: { trigger: 'i-lucide-list-filter' },
      },
    },
  },
});

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 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, text, and icon customization for the complete key list, examples, and slot customization.

🧱 Components

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, text, and icon customization

🛠 Development

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm 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.

Verify visual component changes through the corresponding live demo in the central documentation.

Dependency maintenance updates manifests and the pnpm lockfile within supported version ranges.

TanStack Table is not a direct peer dependency of this package. Table controls use Query Kit types; a consuming table renderer owns its TanStack version.