nuxt-ui-tools-dashboard
Use this skill when building analytics dashboards with nuxt-ui-tools as a package consumer. Covers schema and view functions (defineDashboardSchema, defineDashboardView) that take their context as typ
SKILL.mdskills/consumer/dashboard/SKILL.md
GitHubnuxt-ui-tools Dashboard
Use this skill for package-consumer tasks involving:
defineDashboardSchema(...),defineDashboardView(...), and the functions that wrap themuseDashboard(schema)anduseDashboard(() => accountSchema({ accountId }))- typed injection:
useDashboardView(consumptionView),injectDashboard(accountSchema),InferDashboard,InferDashboardView - filters: declared inline with
f, where they live (sync: URL, memory, a store), headless filters, one value per key across views UiDashboardPage: the whole page (header, refresh, pinned tabs and filters, the current view)- controls (
dashboard.controls.x) and the shipped UIUiDashboardFilters,UiDashboardFilter,UiDashboardViewTabs, a chart's series picked by a filter, a block's drill-down filter chips - staged queries,
select, dependent queries (requires), andderive - lazy
enabledconditions on views, queries, and filters - remote pickers and
remoteTableOptions - number formats (
format="integer",Intl.NumberFormatoptions,useDashboardFormat()) UiDashboardGrid,UiDashboardStat,UiDashboardWidget, chart and list blocks, and the rest of the block library
Focused references:
skills/consumer/dashboard/references/schema.md— schema and view functions, stages,select, conditions, views, derive, the facade, rebuildsskills/consumer/dashboard/references/filters.md— filter kinds and options, sync, URL keys, controls, remote pickersskills/consumer/dashboard/references/controls.md— the filter bar, pills, view tabs, slots, binding a control to your own componentskills/consumer/dashboard/references/blocks.md— the page, every block, formats, grid sizing, theming
Setup
The dashboard ships with the module. Queries run through TanStack Query, so the app must install
VueQueryPlugin (same requirement as the table). Chart blocks render with unovis, an optional peer
dependency:
bun add @unovis/vue @unovis/ts
Stats, lists, bars, paired bars, funnels, stacked bars, and custom widgets work without unovis.
The Shape In One Example
A single file is enough for a small dashboard:
<script setup lang="ts">
const schema = defineDashboardSchema({
key: 'sales',
filters: (f) => ({
period: f.enum([7, 30, 90], {
defaultValue: 30,
label: 'Period',
format: (days) => `${days} days`,
}),
}),
queries: ({ essential, background, filters }) => ({
summary: essential.query(() => ({
queryKey: ['sales', 'summary', filters.period],
queryFn: () => api.sales.summary({ days: filters.period }),
})),
daily: background.query({
defaultValue: [],
query: () => ({
queryKey: ['sales', 'daily', filters.period],
queryFn: () => api.sales.daily({ days: filters.period }),
}),
}),
}),
})
const dashboard = useDashboard(schema)
</script>
<template>
<UiDashboardPage :dashboard title="Sales">
<UiDashboardGrid>
<UiDashboardStat
size="12 md:4"
:source="dashboard.summary"
label="Revenue"
:value="(summary) => summary.revenue"
:compare="(summary) => summary.previousRevenue"
:format="{ currency: 'EUR' }"
/>
<UiDashboardBarChart
size="12 lg:8"
:source="dashboard.daily"
title="Orders per day"
:x="(day) => day.date"
:series="[{ key: 'orders', label: 'Orders', value: (day) => day.orders }]"
format="integer"
totals
/>
</UiDashboardGrid>
</UiDashboardPage>
</template>
What you get without writing it:
- the page: title, today's date and when the data was fetched, the refresh control, and the filter bar pinned while the page scrolls
- a "Period 30 days ⌄" pill that picks the period, turns accent when changed, and resets
?period=7in the URL (defaults never reach the URL)summaryfetches first;dailyfetches oncesummarysettles- each block shows a skeleton while its source loads, a retryable error scoped to that block, an empty state, and a thin progress bar whenever a request is in flight (refetch or retry)
- the stat's delta and "vs €12,400 previous period" caption, in the current locale
- every accessor (
summary.revenue,day.date) typed from the query result
Compose A Dashboard From Functions
A dashboard is about something: an account, the workspace a user works in. That context is the params of a function wrapping the schema, passed by the page and handed on to the views. Filters are the state the user controls; each view declares its own, inline. Each view is a self-contained schema in its own file:
// entities/account/dashboard/activity.ts — one tab
export function accountActivityView(params: { accountId: string; workspace: Workspace }) {
const { $api, $i18n } = useNuxtApp()
const year = new Date().getFullYear()
return defineDashboardView({
label: () => $i18n.t('account.tabs.activity'),
enabled: () => params.workspace !== 'client',
filters: (f) => ({
year: f.enum(years(), { defaultValue: year, label: () => $i18n.t('filters.year') }),
product: f.remote(
remoteTableOptions(
(request) =>
$api.accounts.products.queryOptions({
params: { id: params.accountId },
body: request,
}),
{ search: ['name'], option: (product) => ({ label: product.name, value: product.id }) },
),
{ label: () => $i18n.t('filters.product') },
),
}),
queries: ({ essential, filters }) => {
const usage = () =>
$api.accounts.usage.queryOptions({
params: { id: params.accountId },
query: { year: filters.year, product: filters.product },
})
return {
summary: essential.query({ query: usage, select: (data) => data.summary }),
months: essential.query({ defaultValue: [], query: usage, select: (data) => data.months }),
}
},
})
}
// entities/account/dashboard/schema.ts
export function accountSchema(params: { accountId: string; workspace: Workspace }) {
return defineDashboardSchema({
key: 'account',
views: {
activity: accountActivityView(params),
invoices: accountInvoicesView(params),
},
})
}
<!-- pages/accounts/[id].vue: instantiate, then bind -->
<script setup lang="ts">
const route = useRoute()
const { workspace } = useApiContext()
const account = useDashboard(() =>
accountSchema({ accountId: String(route.params.id), workspace: workspace.value }),
)
</script>
<template>
<UiDashboardPage :dashboard="account" :title="t('Account')">
<template #activity><AccountActivity /></template>
<template #invoices><AccountInvoices /></template>
</UiDashboardPage>
</template>
<!-- AccountActivity.vue: no props, fully typed, blocks only -->
<script setup lang="ts">
const activity = useDashboardView(accountActivityView)
</script>
<template>
<UiDashboardGrid variant="panels" columns="2 md:4">
<UiDashboardStat
size="1"
:source="activity.summary"
label="Units"
:value="(s) => s.units"
format="integer"
/>
</UiDashboardGrid>
</template>
The getter runs in setup, and again when what it reads changes (another account, another workspace): the dashboard rebuilds for the new input behind the same objects, filters keep their values (they live in the URL), and blocks show their loading state for the new data.
Rules Of Thumb
- A page instantiates the dashboard and binds components:
useDashboard(...)in the script,UiDashboardPagein the template, one slot per view. Never wire a header, a date line, sticky tabs, a scroll shadow, or av-ifondashboard.view.currentby hand; view components contain blocks only. - Pass what the dashboard is about (an id, the audience) as params of the schema function; never as a filter synced from the route or a store. Filters are what the user changes.
- Declare filters inline in the schema or view that reads them. A key shared by two views is one
filter:
yearkeeps its value across tabs. - Schema, view, and query builders may call app-level composables (
useNuxtApp()for$i18nand$api, a store,useRoute()) anduseDashboardFormat()at the top. A schema function runs again outside setup, so it cannot calluseI18n()or lifecycle hooks. - Write conditions as lazy callbacks:
enabled: () => can('margin'). Blocks bound to a disabled query render nothing and grids close up, so templates never branch on permissions. - There is no
.valueanywhere:dashboard.filters.year,dashboard.summary.data,dashboard.refreshingare plain reads, and filters arev-modeltargets. - Bind blocks to resources, not strings:
:source="dashboard.summary". - Put shared calculations in
derive, not in pagecomputeds, so blocks get their state for free. - Declare presentation on the filter (
label,placeholder,format,columns) and let the page render the bar; slot or bind a control yourself only where a filter needs a custom look. - Split one response per block with
selectinstead of reshaping it inderive. - Use
useDashboardView(view)/injectDashboard(schema)in child components; never prop-drill the dashboard or restate its type (InferDashboard<typeof accountSchema>names it when you need to). - Format with presets,
{ currency }, oruseDashboardFormat(); do not buildIntl.NumberFormatoptions incomputeds. - Let the engine render filter controls: a chart whose series the user picks binds the control as
its
series; a block narrowed by a drill-down value lists its control infilters; a header link is an action{ label, to }; rows that open a page taketo. - Drill down by writing a filter from
@select; show it back withselected. - Compare periods with
f.comparison()andresolveDashboardComparisonRange, then passcompareaccessors to stats and chart series: deltas, captions, and legends follow. - Call
useDashboardonce in<script setup>; all queries and URL bindings are created there.