A Vue admin dashboard becomes maintainable when we treat it as an application surface, not a page full of widgets. Start with an app shell, define a small data contract, build reusable view components, then add permissions, responsive behavior, and tests around real workflows.
In this guide, we will build that foundation in a Vue 3 application. The result is a dashboard route with persistent navigation, live-ready metrics, filters, a table area, and a structure that can grow without turning into a single oversized component.
Table of contents
Before you start
Use an existing Vue 3 project with a router and a working API endpoint, or create those pieces before you begin. We recommend having:
-
Vue 3 with the Composition API
-
Vue Router for the
/adminroute -
A request client, such as
fetchor Axios -
A component library or an in-house UI layer
-
A mock response for dashboard metrics, activity, and table rows
-
Permission data from your authenticated user session
For shared dashboard state, use a dedicated store rather than passing filters and loading flags through several levels of components. Vue’s current guidance recommends Pinia for new larger-scale applications, while lightweight shared state can still use Vue’s reactivity APIs.
1. Define the dashboard jobs and data contract
Action: Write down the decisions an administrator must make on this screen. A revenue dashboard, for example, usually needs a time range, summary metrics, a trend, an activity feed, and a drill-down route. Do not start by selecting charts.
Then define the smallest API response that supports those decisions:
type DashboardOverview = {
range: '7d' | '30d' | '90d'
metrics: Array<{
id: 'revenue' | 'customers' | 'conversion'
label: string
value: string
change: number
}>
activity: Array<{
id: string
title: string
detail: string
occurredAt: string
}>
}
Expected result: Product, design, frontend, and backend teams agree on one response shape before the page is styled.
Troubleshooting: If one widget requires a unique endpoint, first ask whether that data belongs in the overview response. Split it only when its refresh rate, permissions, or payload size differ materially from the rest of the dashboard.
A useful mental model is to separate your dashboard into three layers: layout, presentation, and domain data. This lets us replace a chart library or card component without rewriting the page’s business rules.
2. Build the app shell before the widgets
Action: Create the dashboard’s structural frame first: a persistent navigation area, a main region, a page heading, page actions, and a scrollable working panel. This makes responsive behavior and focus order much easier to reason about.
DOM Studio’s Dashboard block is a useful reference for a responsive dashboard with persistent navigation, compact metrics, reporting controls, and a mobile fallback. Its Application Layout block also demonstrates the key shell behavior: the left rail remains available while the main work area scrolls independently.
Use semantic landmarks from the beginning:
<template>
<div class="admin-shell">
<a class="skip-link" href="#dashboard-main">Skip to dashboard content</a>
<aside aria-label="Primary administration">
<AdminNav />
</aside>
<main id="dashboard-main" tabindex="-1">
<DashboardHeader />
<DashboardOverview />
</main>
</div>
</template>
Expected result: At desktop widths, navigation and content have stable, independent areas. At narrow widths, navigation can move behind a menu or drawer without changing the page’s information hierarchy.
Troubleshooting: If the whole page scrolls and the navigation disappears too early, give the shell a viewport-based minimum height and make only the main panel scrollable. Do not solve this with fixed pixel heights that break on a small laptop or zoomed browser.
For a visual walkthrough of an older Vue 3 dashboard build, use the optional video below for layout ideas only. Check current Vue and library documentation before copying its dependencies or configuration.
3. Create a single dashboard store
Action: Keep server state, loading status, and request errors together. Pinia is a good fit when the date range, overview response, and refresh action are shared by several dashboard components.
// stores/dashboard.ts
import { defineStore } from 'pinia'
export const useDashboardStore = defineStore('dashboard', {
state: () => ({
range: '30d' as '7d' | '30d' | '90d',
overview: null as DashboardOverview | null,
loading: false,
error: ''
}),
actions: {
async loadOverview() {
this.loading = true
this.error = ''
try {
const response = await fetch(`/api/admin/overview?range=${this.range}`)
if (!response.ok) throw new Error('Unable to load dashboard data')
this.overview = await response.json()
} catch (error) {
this.error = error instanceof Error ? error.message : 'Unexpected error'
} finally {
this.loading = false
}
}
}
})
Expected result: Changing the selected range and clicking refresh produces one predictable request and one source of truth for the visible data.
Troubleshooting: Avoid copying overview into every child component. Pass a metric or activity item down as a prop, and emit only user intent, such as change-range or open-customer, back upward.
4. Compose metrics and activity into small components
Action: Keep the page component responsible for composition. Move repeatable visual units into focused components such as MetricCard, ActivityFeed, DataTable, and DashboardEmptyState.
<script setup lang="ts">
import { computed, onMounted } from 'vue'
import { useDashboardStore } from '@/stores/dashboard'
import MetricCard from './MetricCard.vue'
import ActivityFeed from './ActivityFeed.vue'
const dashboard = useDashboardStore()
const metrics = computed(() => dashboard.overview?.metrics ?? [])
onMounted(() => dashboard.loadOverview())
</script>
<template>
<section aria-labelledby="overview-heading">
<h1 id="overview-heading">Overview</h1>
<div v-if="dashboard.loading" aria-live="polite">Loading overview…</div>
<p v-else-if="dashboard.error" role="alert">{{ dashboard.error }}</p>
<template v-else>
<div class="metric-grid">
<MetricCard v-for="metric in metrics" :key="metric.id" :metric="metric" />
</div>
<ActivityFeed :items="dashboard.overview?.activity ?? []" />
</template>
</section>
</template>
Expected result: Each component can be tested with a short fixture, and the dashboard page reads like a map of the screen.
Troubleshooting: If a card needs access to a store only to format a value, pass the value as a prop instead. Reserve store access for components that truly coordinate shared state.
When you want editable, documented building blocks rather than a locked template, DOM Studio provides Vue wrappers, headless elements, form tools, application blocks, and component metadata. Its component library and form system can help us standardize controls such as buttons, selects, dialogs, and filter fields across the dashboard.
5. Add filters, loading states, and errors
Action: Make the primary filter explicit and reversible. A date range is usually the first filter for an operational dashboard. Bind it to the store, then reload only when the user confirms a change or when a small, intentional debounce completes.
<script setup lang="ts">
import { watch } from 'vue'
import { useDashboardStore } from '@/stores/dashboard'
const dashboard = useDashboardStore()
watch(
() => dashboard.range,
() => dashboard.loadOverview()
)
</script>
<template>
<label for="range">Reporting period</label>
<select id="range" v-model="dashboard.range" :disabled="dashboard.loading">
<option value="7d">Last 7 days</option>
<option value="30d">Last 30 days</option>
<option value="90d">Last 90 days</option>
</select>
</template>
Expected result: Users always know which data they are viewing, and the UI communicates whether the requested data is loading, empty, or unavailable.
Troubleshooting: Do not replace the entire page with a spinner during a filter refresh. Keep the current values visible, disable conflicting controls, and show a compact progress indicator. Preserve a clear retry action for network failures.
Similar products and tools can speed up delivery in different ways. Full UI frameworks such as Vuetify, PrimeVue, and Quasar can be effective when their conventions match your stack. Template-first products can speed up a prototype. We prefer an editable component system when the dashboard needs to stay consistent while product requirements change.
6. Apply permissions at the route and API layers
Action: Model permission checks as capabilities, not scattered role names. For example, use reports:view, customers:edit, and billing:manage. Use those capabilities to control navigation and client-side affordances.
// router/admin.ts
{
path: '/admin/reports',
component: () => import('@/views/ReportsView.vue'),
meta: { requiresAbility: 'reports:view' }
}
Expected result: A user without reports:view neither sees the reports navigation item nor reaches a useful reports route.
Troubleshooting: A route guard is not authorization. The API must enforce the same capability on every protected request. If the server returns 403, show an explanatory access state instead of an empty chart or generic network error.
7. Make the dashboard responsive and accessible
Action: Design the compact layout as a deliberate mode. On smaller screens, prioritize the current context, primary metrics, primary action, and a way to reach navigation. Convert secondary side panels into drawers or dedicated routes.
Use these verification checks before calling the screen complete:
-
Navigate the full dashboard with a keyboard. Focus must be visible, predictable, and never trapped in a menu or dialog.
-
Add a skip link that moves to the main content, then restore useful focus after route changes.
-
Use real
button,label,select,table,nav, and heading elements before reaching for ARIA attributes. -
Give icon-only actions an accessible name.
-
Test at 320 CSS pixels, a typical laptop width, and 200% browser zoom.
-
Ensure metric color is not the only signifier of positive, negative, or warning status.
Expected result: The same dashboard remains understandable with a keyboard, screen reader, narrow viewport, and enlarged text.
Troubleshooting: If a desktop data table cannot fit on a phone, do not shrink every column. Choose a priority set of fields, allow a detail view, or transform each row into a labeled card while preserving the same actions.
8. Test the workflows that matter
Action: Test behavior, not implementation details. Start with the workflows that can affect decisions or data: changing the reporting range, loading a failed request, opening a detail route, and receiving a forbidden response.
A focused test plan includes:
-
A component test verifying that
MetricCardformats a positive and negative change correctly. -
A component test verifying that the range control triggers
loadOverview()once per user change. -
A route test verifying that users without a capability are redirected or shown an access state.
-
An end-to-end test verifying that keyboard users can reach the main content, change a filter, and open a row detail.
Expected result: Reusable pieces remain safe to refactor, while end-to-end tests catch integration issues across the router, store, and API boundary.
Troubleshooting: If tests become fragile after a CSS adjustment, query by role, label, and visible behavior instead of framework-specific classes or component internals.
Build the first useful screen, then expand
A scalable Vue admin dashboard starts with a dependable shell and a clear data contract. Once those are in place, add one decision-focused workflow at a time: metrics, filters, a table, a detail route, then deeper analysis. This keeps the product useful throughout development and prevents the dashboard from becoming a collection of unrelated cards.
If you want to move from a blank page to editable application UI quickly, explore DOM Studio’s dashboard and application-layout blocks, then replace the example data with your own API contract. We can keep the primitives consistent while retaining control of the source, interaction behavior, and product-specific design.