1 +
# Avatar
2 + 3 +
> Avatars are a BootstrapVue custom component, and are typically used to display a user profile as a
4 +
> picture, an icon, or short text. `<b-avatar>` provides several props for customizing its
5 +
> appearance such as color variant and roundness, and optionally supports acting as a button, link
6 +
> or [router link](/docs/reference/router-links).
7 + 8 +
## Overview
9 + 10 +
Avatars are lightweight functional components, which render inline by default, so that they are
11 +
vertically centered beside any adjoining plain text. They also can be used as children of other
12 +
components.
13 + 14 +
The `<b-avatar>` component was added in BootstrapVue version `v2.8.0`.
15 + 16 +
```html
17 +
<template>
18 +
<div>
19 +
<p>Using stand-alone:<p/>
20 +
<div class="mb-4">
21 +
<b-avatar></b-avatar>
22 +
<b-avatar variant="primary" text="BV"></b-avatar>
23 +
<b-avatar variant="info" src="https://placekitten.com/300/300"></b-avatar>
24 +
<b-avatar variant="success" icon="people-fill"></b-avatar>
25 +
</div>
26 +
<p>Using in components (list group) example:<p/>
27 +
<b-list-group style="max-width: 300px;">
28 +
<b-list-group-item class="d-flex align-items-center">
29 +
<b-avatar class="mr-3"></b-avatar>
30 +
<span class="mr-auto">J. Circlehead</span>
31 +
<b-badge>5</b-badge>
32 +
</b-list-group-item>
33 +
<b-list-group-item class="d-flex align-items-center">
34 +
<b-avatar variant="primary" text="BV" class="mr-3"></b-avatar>
35 +
<span class="mr-auto">BootstrapVue</span>
36 +
<b-badge>12</b-badge>
37 +
</b-list-group-item>
38 +
<b-list-group-item class="d-flex align-items-center">
39 +
<b-avatar variant="info" src="https://placekitten.com/300/300" class="mr-3"></b-avatar>
40 +
<span class="mr-auto">Super Kitty</span>
41 +
<b-badge>9</b-badge>
42 +
</b-list-group-item>
43 +
<b-list-group-item class="d-flex align-items-center">
44 +
<b-avatar variant="success" icon="people-fill" class="mr-3"></b-avatar>
45 +
<span class="mr-auto">ACME group</span>
46 +
<b-badge>7</b-badge>
47 +
</b-list-group-item>
48 +
</b-list-group>
49 +
</div>
50 +
</template>
51 + 52 +
<!-- b-avatar.vue -->
53 +
```
54 + 55 +
## Avatar types
56 + 57 +
The avatar content can be either a short text string, an image, or an icon. Avatar content defaults
58 +
to the [`'person-fill'` icon](/docs/icons) when no other content is specified.
59 + 60 +
### Text content
61 + 62 +
You can specify a short string as the content of an avatar via the `text` prop. The string should be
63 +
short (1 to 3 characters), and will be transformed via CSS to be all uppercase. The font size will
64 +
be scaled relative to the [`size` prop setting](#sizing).
65 + 66 +
```html
67 +
<template>
68 +
<div class="mb-2">
69 +
<b-avatar text="BV"></b-avatar>
70 +
<b-avatar text="a"></b-avatar>
71 +
<b-avatar text="Foo"></b-avatar>
72 +
<b-avatar text="BV" size="4rem"></b-avatar>
73 +
</div>
74 +
</template>
75 + 76 +
<!-- b-avatar-text.vue -->
77 +
```
78 + 79 +
### Image content
80 + 81 +
Use the `src` prop to specify a URL of an image to use as the avatar content. The image should have
82 +
an aspect ratio of `1:1` (meaning the width and height should be equal), otherwise image aspect
83 +
distortion will occur. The image will be scaled up or down to fit withing the avatar's bounding box,
84 +
and will be sized to show the avatar's [variant background](#variants) around the edge.
85 + 86 +
```html
87 +
<template>
88 +
<div class="mb-2">
89 +
<b-avatar src="https://placekitten.com/300/300"></b-avatar>
90 +
<b-avatar src="https://placekitten.com/300/300" size="6rem"></b-avatar>
91 +
</div>
92 +
</template>
93 + 94 +
<!-- b-avatar-src.vue -->
95 +
```
96 + 97 +
**Notes:**
98 + 99 +
- When using a module bundler and project relative image URLs, please refer to the
100 +
[Component img src resolving](/docs/reference/images) reference section for additional details.
101 +
- The `src` prop takes precedence over the `text` prop.
102 + 103 +
### Icon content
104 + 105 +
Easily use one of [BootstrapVue's icons](/docs/icons) as the avatar content via the `icon` prop. The
106 +
prop should be set to a valid icon name. Icons will scale respective to the [`size` prop](#sizing).
107 + 108 +
```html
109 +
<template>
110 +
<div class="mb-2">
111 +
<b-avatar icon="people-fill"></b-avatar>
112 +
<b-avatar icon="star-fill"></b-avatar>
113 +
<b-avatar icon="music-note"></b-avatar>
114 +
<b-avatar icon="star-fill" size="4em"></b-avatar>
115 +
</div>
116 +
</template>
117 + 118 +
<!-- b-avatar-icon.vue -->
119 +
```
120 + 121 +
**Notes:**
122 + 123 +
- When providing a BootstrapVue icon name, you _must_ ensure that you have registered the
124 +
corresponding icon component (either locally to your component/page, or globally), if not using
125 +
the full [`BootstrapVueIcons` plugin](/docs/icons).
126 +
- The `icon` prop takes precedence over the `text` and `src` props.
127 +
- If the `text`, `src`, or `icon` props are not provided _and_ the [default slot](#custom-content)
128 +
has no content, then the `person-fill` icon will be used.
129 + 130 +
### Custom content
131 + 132 +
Use the `default` slot to render custom content in the avatar, for finer grained control of its
133 +
appearance, or if using custom icons or SVGs e.g.:
134 + 135 +
```html
136 +
<b-avatar><custom-icon></custom-icon></b-avatar>
137 +
```
138 + 139 +
**Notes:**
140 + 141 +
- The default slot takes precedence over the `text`, `src` and `icon` props.
142 +
- The default slot content will be wrapped in a `<span>` element to ensure proper centering.
143 +
- You may need additional styling applied to the custom content to compensate for the
144 +
[shape of avatar component](#rounding).
145 + 146 +
## Styling
147 + 148 +
### Variants
149 + 150 +
Use the `variant` prop to specify one of Bootstrap theme variant colors. The default variant is
151 +
`secondary`.
152 + 153 +
```html
154 +
<template>
155 +
<div>
156 +
<b-avatar variant="secondary"></b-avatar>
157 +
<b-avatar variant="primary"></b-avatar>
158 +
<b-avatar variant="dark"></b-avatar>
159 +
<b-avatar variant="light"></b-avatar>
160 +
<b-avatar variant="success"></b-avatar>
161 +
<b-avatar variant="danger"></b-avatar>
162 +
<b-avatar variant="warning"></b-avatar>
163 +
<b-avatar variant="info"></b-avatar>
164 +
</div>
165 +
</template>
166 + 167 +
<!-- b-avatar-variant.vue -->
168 +
```
169 + 170 +
If you have defined additional custom variants via
171 +
[SASS theming variables](/docs/reference/theming), the custom variants will also be available to
172 +
use.
173 + 174 +
### Sizing
175 + 176 +
By default, avatars are sized to `2.5em` (which is relative to the current font size). You can
177 +
change the size of the avatar by changing the current font size, or use the prop `size` to specify
178 +
an explicit size. The sizes `sm`, `md` and `lg` default to `1.5em`, `2.5em` and `3.5em`. Numbers get
179 +
converted to pixel values. Any other value _must_ include the units (such as `px`, `em`, or `rem`).
180 + 181 +
```html
182 +
<template>
183 +
<div>
184 +
<b-avatar></b-avatar>
185 +
<b-avatar size="sm"></b-avatar>
186 +
<b-avatar size="lg"></b-avatar>
187 +
<b-avatar :size="24"></b-avatar>
188 +
<b-avatar size="3em"></b-avatar>
189 +
<b-avatar size="72px"></b-avatar>
190 +
</div>
191 +
</template>
192 + 193 +
<!-- b-avatar-size.vue -->
194 +
```
195 + 196 +
**Note:** Avatars are _always_ rendered with an aspect ratio of `1:1`.
197 + 198 +
### Square
199 + 200 +
Prefer a square avatar? simply set the `square` prop to `true`.
201 + 202 +
```html
203 +
<template>
204 +
<div>
205 +
<b-avatar square></b-avatar>
206 +
</div>
207 +
</template>
208 + 209 +
<!-- b-avatar-square.vue -->
210 +
```
211 + 212 +
### Rounding
213 + 214 +
`<b-avatar>` renders with a circular border radius. You can change the rounding by setting the prop
215 +
`rounded` to one of the values `true`, `'sm'`, `'lg'`, `'top'`, `'left'`, `'right'`, or `'bottom'`.
216 +
When set to `true` (or the empty string `''`), it uses the Bootstrap default of medium rounding.
217 + 218 +
```html
219 +
<template>
220 +
<div style="font-size: 2rem;">
221 +
<b-avatar rounded="sm"></b-avatar>
222 +
<b-avatar rounded></b-avatar>
223 +
<b-avatar rounded="lg"></b-avatar>
224 +
<b-avatar rounded="top"></b-avatar>
225 +
<b-avatar rounded="left"></b-avatar>
226 +
<b-avatar rounded="right"></b-avatar>
227 +
<b-avatar rounded="bottom"></b-avatar>
228 +
</div>
229 +
</template>
230 + 231 +
<!-- b-avatar-rounding.vue -->
232 +
```
233 + 234 +
**Notes:**
235 + 236 +
- The `square` prop takes precedence over the `rounded` prop.
237 +
- Alternatively to to the `square` prop, you can set the `rounded` prop to the string `'0'` to
238 +
achieve a square avatar.
239 + 240 +
### Alignment
241 + 242 +
By default `<b-avatar>` will be vertically centered with its adjoining content. In some cases you
243 +
may want to alter the alignment, such as ensuring that a text-only avatar aligns its text with the
244 +
adjoining text. Simply set a [vertical alignment utility](/docs/reference/utility-classes) class on
245 +
the component, such as `<b-avatar class="align-baseline" ...>` or
246 +
`<b-avatar class="align-top" ...>`, etc.
247 + 248 +
## Actionable avatars
249 + 250 +
Easily create avatars that respond to clicks, or avatars that change the URL/route when clicked.
251 +
Actionable avatars will appear in the document tab sequence, and are accessible for both screen
252 +
reader and keyboard-only users.
253 + 254 +
### Button
255 + 256 +
Want to trigger the opening of a modal or trigger an action? Set the `button` prop to instruct
257 +
`<b-avatar>` to render as a `<button>` element. When rendered as a button, the component will emit
258 +
the `click` event whenever clicked.
259 + 260 +
```html
261 +
<template>
262 +
<div>
263 +
<b-avatar button @click="onClick" variant="primary" text="FF" class="align-baseline"></b-avatar>
264 +
Button Avatar
265 +
</div>
266 +
</template>
267 + 268 +
<script>
269 +
export default {
270 +
methods: {
271 +
onClick() {
272 +
this.$bvModal.msgBoxOk('User name: Fred Flintstone', {
273 +
title: 'User Info',
274 +
size: 'sm',
275 +
buttonSize: 'sm',
276 +
okVariant: 'success',
277 +
headerClass: 'p-2 border-bottom-0',
278 +
footerClass: 'p-2 border-top-0'
279 +
})
280 +
}
281 +
}
282 +
}
283 +
</script>
284 + 285 +
<!-- b-avatar-button.vue -->
286 +
```
287 + 288 +
The prop `button-type` can be used to control the type of button to render. Supported values are
289 +
`'button'` (the default), `'submit'`, or `'reset'`.
290 + 291 +
### Link
292 + 293 +
Fancy an avatar as a link or router link? Simply set either the `href` or `to` props (respectively).
294 +
The `to` prop can either be a string path, or a `Location` object. The `to` prop requires that
295 +
`Vue router` (or equivalent) be installed.
296 + 297 +
```html
298 +
<template>
299 +
<div>
300 +
<b-avatar href="#foobar"variant="info" src="https://placekitten.com/300/300"></b-avatar>
301 +
Link Avatar
302 +
</div>
303 +
</template>
304 + 305 +
<!-- b-avatar-href.vue -->
306 +
```
307 + 308 +
**Note:**
309 + 310 +
- The `button` prop takes precedence over the `href` and `to` props.
311 +
- For additional details on the `<router-link>` compatible props, please refer to the
312 +
[Router support reference section](/docs/reference/router-links).
313 + 314 +
## Accessibility
315 + 316 +
Use the `aria-label` prop to provide an accessible, screen reader friendly, label for your avatar.
317 + 318 +
While the `click` event is emitted regardless if the `button`, `href`, or `to` props are set, it is
319 +
highly recommended to use the `button` prop when the click event should trigger an action (or use
320 +
the `to` or `href` props when changing routes or changing URLs) for accessibility reasons.
321 + 322 +
## Implementation notes
323 + 324 +
Avatars are based upon `<b-badge>` and `<b-button>` components, and as such, rely upon Bootstrap's
325 +
`badge-*` and `btn-*` variant classes, as well as the `rounded-*`
326 +
[utility classes](/docs/reference/utility-classes).
327 + 328 +
`<b-avatar>` also requires BootstrapVue's custom CSS for proper styling.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4