Automatic component import from ~/components directory
Nuxt automatically imports any components in the components/ directory without requiring explicit import statements.
components
48 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Component naming from nested directory structure
Component names are generated based on the component's path and filename with duplicate segments removed. For example, a component at components/base/foo/Button.vue becomes <BaseFooButton />.
Grouping directories with parentheses
To group components in a directory without affecting their generated name, use parentheses to name the grouping directory. For example, components/base/(foo)/Button.vue will generate the component name <BaseButton /> instead of <BaseFooButton />.
Disable pathPrefix for name-only imports
Set pathPrefix: false in the components configuration to auto-import components based only on filename, not path. This uses the Nuxt 2 strategy where ~/components/Some/MyComponent.vue becomes <MyComponent> instead of <SomeMyComponent>.
Dynamic components with resolveComponent
Use the resolveComponent helper from Vue or import components directly from '#components' to use Vue's <component :is="someComputedComponent"> syntax. When using resolveComponent, the component name must be a literal string and cannot be a variable, as it is statically analyzed at compilation.
Global component registration
Set global: true and dirs: ['~/components'] in the components configuration to register all components globally, creating async chunks for each. Alternatively, place components in a ~/components/global directory or use .global.vue suffix to selectively register components globally.
Lazy-loading components with Lazy prefix
Add the Lazy prefix to a component name to lazy-load it. For example, <LazyMountainsList /> delays loading the component code until needed, which helps optimize JavaScript bundle size.
Lazy hydration with hydrate-on-visible
Use the hydrate-on-visible attribute on a lazy component to hydrate it when it becomes visible in the viewport. This uses Vue's built-in hydrateOnVisible strategy and relies on IntersectionObserver.
Lazy hydration with hydrate-on-idle
Use the hydrate-on-idle attribute on a lazy component to hydrate it when the browser is idle. Optionally pass a number to set a max timeout. This uses Vue's built-in hydrateOnIdle strategy and is suitable for components that should load without blocking the critical rendering path.
Lazy hydration with hydrate-on-interaction
Use hydrate-on-interaction="eventName" on a lazy component to hydrate it after a specified interaction like click or mouseover. If no event is specified, it defaults to pointerenter, click, and focus. This uses Vue's built-in hydrateOnInteraction strategy.
Lazy hydration with hydrate-on-media-query
Use hydrate-on-media-query="mediaQuery" on a lazy component to hydrate it when the window matches a media query string. This uses Vue's built-in hydrateOnMediaQuery strategy.
Lazy hydration with hydrate-after
Use :hydrate-after="milliseconds" on a lazy component to hydrate it after a specified delay in milliseconds.
Lazy hydration with hydrate-when
Use :hydrate-when="booleanCondition" on a lazy component to hydrate it based on a boolean condition. The component will hydrate when the condition becomes true.
Lazy hydration with hydrate-never
Use hydrate-never on a lazy component to prevent it from ever hydrating. Note that any prop change on a lazily hydrated component will trigger hydration immediately, which overrides hydrate-never.
Listening to hydration events on lazy components
All delayed hydration components emit a @hydrated event when they are hydrated. This allows you to run code after a component becomes interactive.
Direct imports from #components
Components can be explicitly imported from the '#components' virtual module to bypass Nuxt's auto-importing functionality. This is useful when you need more control over when components are loaded.
Custom component directories configuration
Define custom component directories in nuxt.config.ts using the components array. Each entry can be a string path or an object with path, pathPrefix, prefix, pattern, and ignore options. Entries are scanned in order, and nested directories should be added before parent directories.
Component directory configuration options
Each component directory entry accepts: path (directory path), pathPrefix (boolean, default true), prefix (string to prepend to component names), pattern (glob pattern to match files), and ignore (glob pattern to exclude files). The pattern option affects file extension matching, making the extensions option ineffective when pattern is specified.
Registering npm package components with addComponent
Use the addComponent method from @nuxt/kit in a local module to register components from npm packages for auto-import. Specify the name, export, and filePath in the addComponent call.
Component file extensions configuration
By default, files with extensions specified in nuxt.config.ts's extensions key are treated as components. Use the extensions option in a component directory declaration to restrict which file extensions are registered as components.
Client-only components with .client suffix
Add the .client suffix to a component filename (e.g., Comments.client.vue) to render it only on the client side. This feature works with Nuxt auto-imports and #components imports, but not with explicit imports from the real file path. Client components are rendered only after being mounted; use await nextTick() in onMounted() to access the rendered template.
Example using library module for npm package components
Example showing how to use an npm package with components registered via module: <template> <div> <MyAutoImportedComponent /> </div> </template>
Server-only components with .server suffix
Add the .server suffix to a component filename (e.g., HighlightedMarkdown.server.vue) to create a standalone server component that always renders on the server. Server components use <NuxtIsland> under the hood and support the lazy prop and #fallback slot. They must have a single root element.
Paired client and server components
Create paired .server and .client components with the same name (e.g., Comments.client.vue and Comments.server.vue) for advanced use cases. When used, the .server version renders on the server and the .client version renders in the browser after mounting.
Prop changes trigger immediate hydration on lazy components
Any prop change on a lazily hydrated component will trigger hydration immediately, regardless of the hydration strategy set. For example, changing a prop on a component with hydrate-never will cause it to hydrate.
Lazy hydration limitations in Nuxt
Nuxt's built-in lazy hydration currently only works in single-file components (SFCs) and requires defining props in the template rather than spreading an object via v-bind. It also does not work with direct imports from #components.
Example lazy component with hydrate-on-idle
Example showing lazy component with idle hydration: <template> <div> <LazyMyComponent hydrate-on-idle /> </div> </template>
Example lazy component with hydrate-on-interaction
Example showing lazy component with interaction-based hydration: <template> <div> <LazyMyComponent hydrate-on-interaction="mouseover" /> </div> </template>
Example lazy component with hydrate-on-media-query
Example showing lazy component with media query hydration: <template> <div> <LazyMyComponent hydrate-on-media-query="(max-width: 768px)" /> </div> </template>
Example lazy component with hydrate-after
Example showing lazy component with delayed hydration: <template> <div> <LazyMyComponent :hydrate-after="2000" /> </div> </template>
Example lazy component with hydrate-when
Example showing lazy component with conditional hydration: <template> <div> <LazyMyComponent :hydrate-when="isReady" /> </div> </template> <script setup lang="ts"> const isReady = ref(false) function myFunction () { isReady.value = true } </script>
Example lazy component with hydrate-never
Example showing lazy component that never hydrates: <template> <div> <LazyMyComponent hydrate-never /> </div> </template>
Example listening to hydrated event
Example showing how to listen to the hydrated event: <template> <div> <LazyMyComponent hydrate-on-visible @hydrated="onHydrate" /> </div> </template> <script setup lang="ts"> function onHydrate () { console.log('Component has been hydrated!') } </script>
Example using resolveComponent for dynamic components
Example showing dynamic component usage with resolveComponent: <script setup lang="ts"> import { SomeComponent } from '#components' const MyButton = resolveComponent('MyButton') </script> <template> <component :is="clickable ? MyButton : 'div'" /> <component :is="SomeComponent" /> </template>
Example direct imports from #components
Example showing direct component imports: <script setup lang="ts"> import { LazyMountainsList, NuxtLink } from '#components' const show = ref(false) </script> <template> <div> <h1>Mountains</h1> <LazyMountainsList v-if="show" /> <button v-if="!show" @click="show = true" > Show List </button> <NuxtLink to="/">Home</NuxtLink> </div> </template>
Example custom component directories configuration
Example showing custom component directory configuration: export default defineNuxtConfig({ components: [ // ~/calendar-module/components/event/Update.vue => <EventUpdate /> { path: '~/calendar-module/components' }, // ~/user-module/components/account/UserDeleteDialog.vue => <UserDeleteDialog /> { path: '~/user-module/components', pathPrefix: false }, // ~/components/special-components/Btn.vue => <SpecialBtn /> { path: '~/components/special-components', prefix: 'Special' }, // ~/components/Btn.vue => <Btn /> // ~/components/base/Btn.vue => <BaseBtn /> '~/components', ], })
Example component directory with pattern and ignore options
Example showing component directory with glob patterns: export default defineNuxtConfig({ components: [ { path: '~/domains', pattern: '*/components/**', pathPrefix: false, }, ], })
Example registering npm package components
Example showing how to register npm package components in a module: import { addComponent, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ setup () { addComponent({ name: 'MyAutoImportedComponent', export: 'MyComponent', filePath: 'my-npm-package', }) }, })
Example limiting component file extensions
Example showing how to restrict component file extensions: export default defineNuxtConfig({ components: [ { path: '~/components', extensions: ['.vue'], }, ], })
Example disabling pathPrefix for name-only imports
Example showing how to disable pathPrefix: export default defineNuxtConfig({ components: [ { path: '~/components', pathPrefix: false, }, ], })
Example global component registration
Example showing how to register all components globally: export default defineNuxtConfig({ components: { global: true, dirs: ['~/components'] }, })
Example lazy-loading a component
Example showing lazy component usage: <script setup lang="ts"> const show = ref(false) </script> <template> <div> <h1>Mountains</h1> <LazyMountainsList v-if="show" /> <button v-if="!show" @click="show = true" > Show List </button> </div> </template>
Best practice: prioritize in-viewport content
Avoid delayed hydration for critical, above-the-fold content. It is best suited for content that is not immediately needed.
Best practice: conditional rendering vs delayed hydration
When using v-if="false" on a lazy component, you might not need delayed hydration. A normal lazy component using v-if is sufficient.
Best practice: shared state and lazy hydration
Be mindful of shared state (v-model) across multiple lazy components. Updating the model in one component can trigger hydration in all components bound to that model.
Best practice: choosing the right hydration strategy
hydrate-when is best for components that might not always need to be hydrated. hydrate-after is for components that can wait a specific amount of time. hydrate-on-idle is for components that can be hydrated when the browser is idle. Avoid hydrate-never on interactive components.
Library authors: registering component directories with addComponentsDir
Use the addComponentsDir method from @nuxt/kit in a Nuxt module to register component directories for auto-import. This is useful for Vue component library authors.
Example registering component directory for library authors
Example showing component directory registration in a library module: import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ setup () { const resolver = createResolver(import.meta.url) addComponentsDir({ path: resolver.resolve('./components'), prefix: 'awesome', }) }, })