@svelte-put/avatar GitHub

component & utilities for building avatars

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

Migrating to Svelte 5? See the new docs site here.

Installation

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

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 (last resort) just in case UI Avatar is out of service all of the sudden.
<script lang="ts">
  import Avatar from '@svelte-put/avatar/Avatar.svelte';

  export let id: string;
  export let email = '';
  export let firstName = '';
  export let lastName = '';
</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="[email protected]" size={50} />
<script>
  import Avatar from '@svelte-put/avatar/Avatar.svelte';
</script>

<Avatar
  gravatar={{
    email: '[email protected]',
    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: '[email protected]',
    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="[email protected]" uiAvatar="Nancy+Wheeler" size={50} />

Customization

Markup

The Avatar component provides a default slot with all necessary values available with the let directive. See Resolution Strategies for details on how each value is resolved.

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

<Avatar
  size={50}
  gravatar="[email protected]"
  uiAvatar="Billy+Hargrove"
  let:alt
  let:src
  let:size
  let:sources
>
  <img {src} {alt} width={size} height={size} data-sources={sources} />
</Avatar>

Styling

The Avatar component provides minimal global styles with 0 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>
  import Avatar from '@svelte-put/avatar/Avatar.svelte';
  /** passed from parent */
  export let color = 'blue';
</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>
Guess who is the Avatar?

Happy bending!

Edit this page on Github