@svelte-put/avatar

GitHub Github

component & utilities for building avatars

@svelte-put/avatar @svelte-put/avatar @svelte-put/avatar @svelte-put/avatar @svelte-put/avatar

Still on Svelte 4? See the old docs site here.

Installation

npm install --save-dev @svelte-put/avatar
pnpm add -D @svelte-put/avatar
yarn add -D @svelte-put/avatar

New to Svelte 5? See Migration Guides.

Resolution Strategies

@svelte-put/avatar provides several strategies for specifying image source, used in isolation or together to form a chain that will resolve to the first available source.

  • src prop - highest priority, most helpful when used together with others

  • gravatar prop - Gravatar

  • uiAvatar prop - UI Avatar

  • fallback prop - custom fallback

  • internal fallback, last resort

For example:

  1. src - you have a dedicated api & database for avatar,
  2. gravatar - you also want to automatically fetch avatar from Gravatar with user's email if they have not uploaded their own avatar to your server,
  3. uiAvatar - you also want to fallback to an UI Avatar with user's initials if their gravatar is not available,
  4. fallback - you provide your own custom fallback just in case UI Avatar is out of service all of the sudden.
<script>
  import Avatar from '@svelte-put/avatar/Avatar.svelte';

  let { id, email, firstName, lastName } = $props();
</script>

<Avatar
  src="https://your.api/avatar/{id}"
  gravatar={email}
  uiAvatar="{firstName}+{lastName}"
  fallback="https://your.api/avatar/default"
/>

Direct URL

Direct image source can be provided to the src prop. This is not much different than using a plain img, thus more helpful when used in conjunction with one/more solutions listed in the following sections.

<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar
	src="https://media.istockphoto.com/id/697946430/photo/pitbull-dog-portrait-with-human-expression.jpg?s=612x612&w=0&k=20&c=uWT9vBoCZPPyg9xkJ0cQI-HqWd5slf7_QsdiwYvazSY="
	size={50}
/>

Gravatar

Support for Gravatar is available through either:

  1. the exported Avatar component with the gravatar prop, which takes either an email string or a verbose config object.
  2. the exported gravatar helper, which generates a Gravatar URL and can be used either with the Avatar component or vanilla img.
vnphanquang@gmail.com
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar gravatar="vnphanquang@gmail.com" size={50} />
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar
	gravatar={{
		email: 'maxmayfield@domain.com',
		rating: 'r',
		size: 50,
		default: 'monsterid',
		// forcedefault: 'y',
	}}
/>
<script>
	import { gravatar } from '@svelte-put/avatar';
	import Avatar from '@svelte-put/avatar/Avatar.svelte';

	const gravatarUrl = gravatar({
		email: 'willbyers@domain.com',
		rating: 'r',
		size: 50,
		default: 'retro',
		// forcedefault: 'y',
	});
</script>

<Avatar src={gravatarUrl} />

<!-- or simply -->
<!-- <img src={gravatarUrl} alt="a gravatar" /> -->

UI Avatar

Similar to Gravatar, Support for UI Avatar is available through either:

  1. the exported Avatar component with the uiAvatar prop, which takes either an string of user name or a verbose config object.
  2. the exported uiAvatar helper, which generates an UI Avatar URL and can be used either with the Avatar component or vanilla img.
Eddie+Munson
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar uiAvatar="Eddie+Munson" size={50} />
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar
	uiAvatar={{
		name: 'Jane+Hopper',
		background: '313131',
		color: 'FFFFFF',
		'font-size': 0.3,
		uppercase: true,
		rounded: true,
		length: 3,
		bold: true,
		size: 50,
		format: 'svg',
	}}
/>
<script>
	import { uiAvatar } from '@svelte-put/avatar';
	import Avatar from '@svelte-put/avatar/Avatar.svelte';

	const uiAvatarUrl = uiAvatar({
		name: 'Steve+Harrington',
		background: '313131',
		color: 'FFFFFF',
		'font-size': 0.3,
		uppercase: true,
		rounded: true,
		length: 3,
		bold: true,
		size: 50,
		format: 'svg',
	});
</script>

<Avatar src={uiAvatarUrl} />

<!-- or simply -->
<!-- <img src={gravatarUrl} alt="a ui avatar" /> -->

Combining Multiple Sources

Using only one of the strategy in previous sections is not that interesting. As mentioned in Resolution Strategies, multiple sources can be provided to form a chain that resolves to the first available source.

nancy.wheeler@domain.com
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar gravatar="nancy.wheeler@domain.com" uiAvatar="Nancy+Wheeler" size={50} />

Customization

Markup

The Avatar component provides the img snippet with all necessary values as parameters, allowing you to complete custom how the image is rendered.

billy.hargrove@domain.com
<script>
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar size={50} gravatar="billy.hargrove@domain.com" uiAvatar="Billy+Hargrove">
	{#snippet img({ src, size, alt, sources })}
		<img {src} {alt} width={size} height={size} data-sources={sources} />
	{/snippet}
</Avatar>

Styling

The Avatar component provides minimal global styles with zero css specificity. See its source code for all the default styles applied to the component.

Since Svelte style are component-scoped by default, customization generally requires global overrides and/or CSS custom properties. The code example below shows a couple of ways to achieve this.

  • The rounded-full class might come from a global styling system like Tailwind CSS.
  • The custom-avatar class is used with the :global modifier. See Svelte docs for more information.
  • The --border-color CSS variable is set up to be used for color attribute, made possible with Svelte --style-props sugar.
Jim+Hopper
<script lang="ts">
	import Avatar from '@svelte-put/avatar/Avatar.svelte';
	/** passed from parent */
	let { color = 'blue' }: { color?: string } = $props();
</script>

<Avatar
	src="https://img.freepik.com/free-photo/adorable-jack-russell-retriever-puppy-portrait_53876-64825.jpg?w=2000"
	uiAvatar="Jim+Hopper"
	size={50}
	class="custom-avatar rounded-full"
	--border-color={color}
/>

<style lang="postcss">
	:global(.custom-avatar) {
		border: 2px var(--border-color) solid;
		box-shadow:
			0 0 0 10px hsl(0deg 0% 50%),
			0 0 0 15px hsl(0deg 0% 60%),
			0 0 0 20px hsl(0deg 0% 70%),
			0 0 0 25px hsl(0deg 0% 80%),
			0 0 0 30px hsl(0deg 0% 90%);
	}
</style>

Migration Guides

V3 -> V4 (Svelte 5 in Runes mode)

When migrating to V4, everything stays the same with the exception that the Avatar component no longer support a default Svelte slot. Instead, use the img snippet for markup customization.

<Avatar
  size={50} gravatar="billy.hargrove@domain.com" uiAvatar="Billy+Hargrove"
  let:alt let:src let:size let:sources
>
	{#snippet img({ src, size, alt, sources })}
  <img {src} {alt} width={size} height={size} data-sources={sources} />
	{/snippet}
</Avatar>
Guess who is the Avatar?

Happy bending!

Edit this page on Github