ExToolkit.UiAvatars (ExToolkit v0.12.2)

View Source

A utility module to generate URLs for https://ui-avatars.com/ with customizable options.

Summary

Functions

Generates a Gravatar-compatible avatar URL that falls back to a UI Avatars image if the user has no Gravatar. For all supported options, see url/1.

Generates a UI Avatars image URL with the given options.

Types

options()

@type options() :: %{
  optional(:size) => pos_integer(),
  optional(:font_size) => float(),
  optional(:length) => pos_integer(),
  optional(:name) => String.t(),
  optional(:rounded) => boolean(),
  optional(:bold) => boolean(),
  optional(:background) => String.t(),
  optional(:color) => String.t(),
  optional(:uppercase) => boolean(),
  optional(:format) => String.t()
}

Functions

gravatar_safe_url(email, opts \\ %{})

@spec gravatar_safe_url(String.t(), options()) :: String.t()

Generates a Gravatar-compatible avatar URL that falls back to a UI Avatars image if the user has no Gravatar. For all supported options, see url/1.

Examples

iex> UiAvatars.gravatar_safe_url("john@example.com", name: "Jane Doe", background: "000000", color: "ffffff")
"https://www.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?size=256&d=https%3A%2F%2Fui-avatars.com%2Fapi%2FJane+Doe/256/000000/ffffff/2/0.5"

url(opts \\ %{})

@spec url(options()) :: String.t()

Generates a UI Avatars image URL with the given options.

Supported Options

  • :name – The name used to generate initials for the avatar.
  • :length – Number of characters in the initials (default: 2).
  • :rounded – Whether the avatar should be circular (default: false).
  • :bold – Whether the initials should be bold (default: false).
  • :background – Hex color for the background (default: "f0e9e9").
  • :color – Hex color for the font (default: "8b5d5d").
  • :uppercase – Whether the initials should be uppercased (default: true).
  • :size – Size of the image in pixels (default: 256).
  • :font_size – Font size as a float percentage (default: 0.5).
  • :format – The image format, "svg" or "png" (default: "svg").

Examples

iex> UiAvatars.url(%{name: "Jane Doe", size: 128, rounded: true, format: "png", font_size: 1})
"https://ui-avatars.com/api/?name=Jane+Doe&size=128&format=png&font-size=1&rounded=true"

iex> UiAvatars.url(%{name: "Elixir", color: "ffffff", background: "000000", uppercase: false, bold: true})
"https://ui-avatars.com/api/?name=Elixir&size=256&format=svg&uppercase=false&color=ffffff&font-size=0.5&background=000000&bold=true"