1# Nuxt Built-in Components
2 
3## When to Use
4 
5Working with images, links, or time display in templates. **Always prefer Nuxt components over HTML elements.**
6 
7## Component Preferences
8 
9| HTML Element | Nuxt Component | Why                                    |
10| ------------ | -------------- | -------------------------------------- |
11| `<a>`        | `<NuxtLink>`   | Client-side navigation, prefetching    |
12| `<img>`      | `<NuxtImg>`    | Optimization, lazy loading, responsive |
13| `<time>`     | `<NuxtTime>`   | SSR-safe formatting, localization      |
14 
15## NuxtLink
16 
17**ALWAYS use `<NuxtLink>` instead of `<a>` for internal links:**
18 
19```vue
20<template>
21  <!-- Internal navigation -->
22  <NuxtLink to="/about">About</NuxtLink>
23  <NuxtLink :to="{ name: '/users/[userId]', params: { userId } }">Profile</NuxtLink>
24 
25  <!-- External links (uses target="_blank" automatically with external) -->
26  <NuxtLink to="https://nuxt.com" external>Nuxt Docs</NuxtLink>
27 
28  <!-- Prefetch control -->
29  <NuxtLink to="/dashboard" :prefetch="false">Dashboard</NuxtLink>
30 
31  <!-- Active state styling -->
32  <NuxtLink to="/settings" active-class="text-primary" exact-active-class="font-bold">
33    Settings
34  </NuxtLink>
35</template>
36```
37 
38**Props:**
39 
40- `to` - Route path or route object
41- `external` - Force external link behavior
42- `target` - Link target (`_blank`, etc.)
43- `prefetch` - Enable/disable prefetching (default: true)
44- `noPrefetch` - Disable prefetching
45- `activeClass` - Class when route matches
46- `exactActiveClass` - Class when route exactly matches
47 
48**Docs:** https://nuxt.com/docs/api/components/nuxt-link
49 
50## NuxtImg
51 
52**ALWAYS use `<NuxtImg>` instead of `<img>` for images:**
53 
54Requires `@nuxt/image` module (usually pre-installed).
55 
56```vue
57<template>
58  <!-- Basic usage -->
59  <NuxtImg src="/images/hero.jpg" alt="Hero image" />
60 
61  <!-- Responsive with sizes -->
62  <NuxtImg
63    src="/images/banner.jpg"
64    alt="Banner"
65    width="1200"
66    height="600"
67    sizes="100vw sm:50vw md:400px"
68  />
69 
70  <!-- Lazy loading (default) -->
71  <NuxtImg src="/images/photo.jpg" loading="lazy" alt="Photo" />
72 
73  <!-- Eager loading for above-fold -->
74  <NuxtImg src="/images/logo.svg" loading="eager" alt="Logo" />
75 
76  <!-- With placeholder blur -->
77  <NuxtImg src="/images/product.jpg" placeholder alt="Product" />
78 
79  <!-- Provider-specific (Cloudinary, etc.) -->
80  <NuxtImg provider="cloudinary" src="/folder/image.jpg" width="500" />
81 
82  <!-- Format conversion -->
83  <NuxtImg src="/images/photo.png" format="webp" alt="Photo" />
84</template>
85```
86 
87**Props:**
88 
89- `src` - Image source path
90- `alt` - Alt text (required for accessibility)
91- `width` / `height` - Dimensions
92- `sizes` - Responsive sizes
93- `loading` - `lazy` (default) or `eager`
94- `placeholder` - Show blur placeholder while loading
95- `format` - Force output format (`webp`, `avif`, etc.)
96- `quality` - Image quality (1-100)
97- `provider` - Image provider (cloudinary, imgix, etc.)
98 
99**For art direction, use `<NuxtPicture>` (different sources per breakpoint).**
100 
101**Docs:** https://image.nuxt.com/usage/nuxt-img
102 
103## NuxtTime
104 
105**ALWAYS use `<NuxtTime>` instead of `<time>` or manual formatting:**
106 
107```vue
108<template>
109  <!-- Relative time -->
110  <NuxtTime :datetime="post.createdAt" relative />
111  <!-- Output: "2 hours ago" -->
112 
113  <!-- Absolute with locale -->
114  <NuxtTime :datetime="event.date" locale="en-US" />
115 
116  <!-- Custom format -->
117  <NuxtTime :datetime="date" year="numeric" month="long" day="numeric" />
118  <!-- Output: "December 6, 2025" -->
119 
120  <!-- Short format -->
121  <NuxtTime :datetime="date" month="short" day="numeric" />
122  <!-- Output: "Dec 6" -->
123 
124  <!-- With time -->
125  <NuxtTime :datetime="date" hour="numeric" minute="2-digit" />
126</template>
127```
128 
129**Props:**
130 
131- `datetime` - Date string, Date object, or timestamp
132- `relative` - Show relative time ("2 hours ago")
133- `locale` - Locale for formatting
134- `year`, `month`, `day`, `hour`, `minute`, `second` - Intl.DateTimeFormat options
135 
136**Docs:** https://nuxt.com/docs/api/components/nuxt-time
137 
138## Common Mistakes
139 
140| ❌ Wrong                              | ✅ Right                                 |
141| ------------------------------------- | ---------------------------------------- |
142| `<a href="/about">`                   | `<NuxtLink to="/about">`                 |
143| `<img src="/photo.jpg">`              | `<NuxtImg src="/photo.jpg" alt="...">`   |
144| `<time>{{ formatDate(date) }}</time>` | `<NuxtTime :datetime="date" />`          |
145| `formatTimeAgo(date)` in template     | `<NuxtTime :datetime="date" relative />` |
146| `new Date().toLocaleDateString()`     | `<NuxtTime :datetime="date" />`          |
147 
148## Best Practices
149 
150- **NuxtLink for all internal routes** - enables prefetching and client-side navigation
151- **NuxtImg for all images** - automatic optimization, lazy loading, responsive
152- **NuxtTime for all dates** - SSR-safe, automatic localization
153- **Always provide alt text** for images
154- **Use `loading="eager"`** for above-the-fold images
155- **Use sizes prop** for responsive images
156 
157## Resources
158 
159- NuxtLink: https://nuxt.com/docs/api/components/nuxt-link
160- NuxtImg: https://image.nuxt.com/usage/nuxt-img
161- NuxtPicture: https://image.nuxt.com/usage/nuxt-picture
162- NuxtTime: https://nuxt.com/docs/api/components/nuxt-time
163