1---
2name: components-auto-imports
3description: Auto-imported components, lazy loading, and hydration strategies
4---
5 
6# Components Auto-imports
7 
8Nuxt automatically imports Vue components from `app/components/` directory.
9 
10## Basic Auto-imports
11 
12```
13components/
14├── Button.vue         → <Button />
15├── Card.vue           → <Card />
16└── AppHeader.vue      → <AppHeader />
17```
18 
19```vue
20<template>
21  <!-- No imports needed -->
22  <AppHeader />
23  <Card>
24    <Button>Click me</Button>
25  </Card>
26</template>
27```
28 
29## Naming Conventions
30 
31### Nested Directory Names
32 
33Component names include directory path:
34 
35```
36components/
37├── base/
38│   └── Button.vue       → <BaseButton />
39├── form/
40│   ├── Input.vue        → <FormInput />
41│   └── Select.vue       → <FormSelect />
42└── ui/
43    └── modal/
44        └── Dialog.vue   → <UiModalDialog />
45```
46 
47### Disable Path Prefix
48 
49```ts
50// nuxt.config.ts
51export default defineNuxtConfig({
52  components: [
53    {
54      path: '~/components',
55      pathPrefix: false, // Use filename only
56    },
57  ],
58})
59```
60 
61With `pathPrefix: false`:
62```
63components/base/Button.vue → <Button />
64```
65 
66## Lazy Loading
67 
68Prefix with `Lazy` for dynamic imports:
69 
70```vue
71<script setup lang="ts">
72const showChart = ref(false)
73</script>
74 
75<template>
76  <!-- Component code loaded only when rendered -->
77  <LazyHeavyChart v-if="showChart" />
78  <button @click="showChart = true">Show Chart</button>
79</template>
80```
81 
82Benefits:
83- Reduces initial bundle size
84- Code-splits component into separate chunk
85- Loads on-demand
86 
87## Lazy Hydration Strategies
88 
89Control when lazy components become interactive:
90 
91### `hydrate-on-visible`
92 
93Hydrate when component enters viewport:
94 
95```vue
96<template>
97  <LazyComments hydrate-on-visible />
98</template>
99```
100 
101### `hydrate-on-idle`
102 
103Hydrate when browser is idle:
104 
105```vue
106<template>
107  <LazyAnalytics hydrate-on-idle />
108</template>
109```
110 
111### `hydrate-on-interaction`
112 
113Hydrate on user interaction:
114 
115```vue
116<template>
117  <!-- Hydrates on click, focus, or pointerenter -->
118  <LazyDropdown hydrate-on-interaction />
119 
120  <!-- Specific event -->
121  <LazyTooltip hydrate-on-interaction="mouseover" />
122</template>
123```
124 
125### `hydrate-on-media-query`
126 
127Hydrate when media query matches:
128 
129```vue
130<template>
131  <LazyMobileMenu hydrate-on-media-query="(max-width: 768px)" />
132</template>
133```
134 
135### `hydrate-after`
136 
137Hydrate after delay (milliseconds):
138 
139```vue
140<template>
141  <LazyAds :hydrate-after="3000" />
142</template>
143```
144 
145### `hydrate-when`
146 
147Hydrate on condition:
148 
149```vue
150<script setup lang="ts">
151const isReady = ref(false)
152</script>
153 
154<template>
155  <LazyEditor :hydrate-when="isReady" />
156</template>
157```
158 
159### `hydrate-never`
160 
161Never hydrate (static only):
162 
163```vue
164<template>
165  <LazyStaticFooter hydrate-never />
166</template>
167```
168 
169### Hydration Event
170 
171```vue
172<template>
173  <LazyChart hydrate-on-visible @hydrated="onChartReady" />
174</template>
175 
176<script setup>
177function onChartReady() {
178  console.log('Chart is now interactive')
179}
180</script>
181```
182 
183## Client/Server Components
184 
185### Client-only (`.client.vue`)
186 
187```
188components/
189└── BrowserChart.client.vue
190```
191 
192```vue
193<template>
194  <!-- Only rendered in browser -->
195  <BrowserChart />
196</template>
197```
198 
199### Server-only (`.server.vue`)
200 
201```
202components/
203└── ServerMarkdown.server.vue
204```
205 
206```vue
207<template>
208  <!-- Rendered on server, not hydrated -->
209  <ServerMarkdown :content="markdown" />
210</template>
211```
212 
213Requires experimental flag:
214 
215```ts
216// nuxt.config.ts
217export default defineNuxtConfig({
218  experimental: {
219    componentIslands: true,
220  },
221})
222```
223 
224### Paired Components
225 
226```
227components/
228├── Comments.client.vue  # Browser version
229└── Comments.server.vue  # SSR version
230```
231 
232Server version renders during SSR, client version takes over after hydration.
233 
234## Dynamic Components
235 
236```vue
237<script setup lang="ts">
238import { SomeComponent } from '#components'
239 
240const dynamicComponent = resolveComponent('MyButton')
241</script>
242 
243<template>
244  <component :is="dynamicComponent" />
245  <component :is="SomeComponent" />
246</template>
247```
248 
249## Direct Imports
250 
251Bypass auto-imports when needed:
252 
253```vue
254<script setup lang="ts">
255import { LazyMountainsList, NuxtLink } from '#components'
256</script>
257```
258 
259## Custom Directories
260 
261```ts
262// nuxt.config.ts
263export default defineNuxtConfig({
264  components: [
265    { path: '~/components/ui', prefix: 'Ui' },
266    { path: '~/components/forms', prefix: 'Form' },
267    '~/components', // Default, should come last
268  ],
269})
270```
271 
272## Global Components
273 
274Register globally (creates async chunks):
275 
276```ts
277// nuxt.config.ts
278export default defineNuxtConfig({
279  components: {
280    global: true,
281    dirs: ['~/components'],
282  },
283})
284```
285 
286Or use `.global.vue` suffix:
287 
288```
289components/
290└── Icon.global.vue  → Available globally
291```
292 
293## Disabling Component Auto-imports
294 
295```ts
296// nuxt.config.ts
297export default defineNuxtConfig({
298  components: {
299    dirs: [], // Disable auto-imports
300  },
301})
302```
303 
304## Library Authors
305 
306Register components from npm package:
307 
308```ts
309// my-ui-lib/nuxt.ts
310import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit'
311 
312export default defineNuxtModule({
313  setup() {
314    const resolver = createResolver(import.meta.url)
315 
316    addComponentsDir({
317      path: resolver.resolve('./components'),
318      prefix: 'MyUi',
319    })
320  },
321})
322```
323 
324<!-- 
325Source references:
326- https://nuxt.com/docs/directory-structure/app/components
327- https://nuxt.com/docs/guide/concepts/auto-imports#auto-imported-components
328-->
329