Avatar

An image element with a fallback for representing the user.

Stimulus: shadcn--avatar

<%= render Shadcn::AvatarComponent.new(
  src: "https://github.com/shadcn.png",
  alt: "shadcn"
) %>

Installation

Add the component to your project:

rails generate shadcn:add avatar

Usage

<%= render Shadcn::AvatarComponent.new( src: "https://github.com/shadcn.png", alt: "shadcn" ) %>

Examples

With Image

<%= render Shadcn::AvatarComponent.new(
  src: "https://github.com/shadcn.png",
  alt: "Shadcn"
) %>

Fallback

When no image is provided or the image fails to load, a fallback is shown.

JD JS AB

<div class="flex items-center gap-4">
  <%= render Shadcn::AvatarComponent.new(alt: "John Doe", fallback: "JD") %>
  <%= render Shadcn::AvatarComponent.new(alt: "Jane Smith") %>
  <%= render Shadcn::AvatarComponent.new(fallback: "AB") %>
</div>

Sizes

<div class="flex items-center gap-4">
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "Small",
    size: :sm
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "Default",
    size: :default
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "Large",
    size: :lg
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "Extra Large",
    size: :xl
  ) %>
</div>

Fallback Sizes

SM DF LG XL

<div class="flex items-center gap-4">
  <%= render Shadcn::AvatarComponent.new(fallback: "SM", size: :sm) %>
  <%= render Shadcn::AvatarComponent.new(fallback: "DF", size: :default) %>
  <%= render Shadcn::AvatarComponent.new(fallback: "LG", size: :lg) %>
  <%= render Shadcn::AvatarComponent.new(fallback: "XL", size: :xl) %>
</div>

User List

Shadcn

shadcn@example.com

John Doe

john@example.com

Jane Smith

jane@example.com

<div class="space-y-4 w-full max-w-md">
  <div class="flex items-center gap-4">
    <%= render Shadcn::AvatarComponent.new(src: "https://github.com/shadcn.png", alt: "Shadcn") %>
    <div>
      <p class="text-sm font-medium leading-none">Shadcn</p>
      <p class="text-sm text-muted-foreground">shadcn@example.com</p>
    </div>
  </div>
  <%= render Shadcn::SeparatorComponent.new %>
  <div class="flex items-center gap-4">
    <%= render Shadcn::AvatarComponent.new(alt: "John Doe", fallback: "JD") %>
    <div>
      <p class="text-sm font-medium leading-none">John Doe</p>
      <p class="text-sm text-muted-foreground">john@example.com</p>
    </div>
  </div>
  <%= render Shadcn::SeparatorComponent.new %>
  <div class="flex items-center gap-4">
    <%= render Shadcn::AvatarComponent.new(alt: "Jane Smith") %>
    <div>
      <p class="text-sm font-medium leading-none">Jane Smith</p>
      <p class="text-sm text-muted-foreground">jane@example.com</p>
    </div>
  </div>
</div>

Avatar Group

JD AB +3

<div class="flex -space-x-4">
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "User 1",
    class_name: "border-2 border-background"
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    fallback: "JD",
    class_name: "border-2 border-background"
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    fallback: "AB",
    class_name: "border-2 border-background"
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    fallback: "+3",
    class_name: "border-2 border-background"
  ) %>
</div>

With Fallback

<%= render Shadcn::AvatarComponent.new(
  src: "https://invalid-url-for-demo.png",
  alt: "John Doe",
  fallback: "JD"
) %>

Fallback Only

<%= render Shadcn::AvatarComponent.new( alt: "Jane Smith" ) %>

Custom Fallback with Slot

<%= render(Shadcn::AvatarComponent.new(size: :lg)) do |avatar| %>
  <% avatar.with_fallback { "CN" } %>
<% end %>

Multiple Avatars

JD AS

<div class="flex items-center gap-4">
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/shadcn.png",
    alt: "shadcn",
    size: :sm
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    src: "https://github.com/vercel.png",
    alt: "vercel",
    size: :default
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    alt: "Jane Doe",
    size: :lg
  ) %>
  <%= render Shadcn::AvatarComponent.new(
    alt: "Alex Smith",
    size: :xl
  ) %>
</div>

API Reference

Prop	Type	Default	Description
src	`String`	`nil`	Image URL for the avatar
alt	`String`	`""`	Alt text for the image
fallback	`String`	`nil`	Fallback text when image is unavailable (auto-generated from alt if not provided)
size	`Symbol`	`:default`	Avatar size (:sm, :default, :lg, :xl)
class_name	`String`	`nil`	Additional CSS classes to apply

Size Reference

Size	Dimensions	Font Size
:sm	24x24px (size-6)	text-xs via fallback group data
:default	32x32px (size-8)	text-sm
:lg	40x40px (size-10)	text-sm
:xl	64x64px (size-16)	text-sm

Stimulus Controller

This component requires JavaScript. The Stimulus controller shadcn--avatar provides interactivity.

Handles image loading errors and shows fallback when image fails to load.

Installation

Add to your config/importmap.rb:

pin "shadcn", to: "index.esm.js"

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn"

const application = Application.start()
registerShadcnControllers(application)

Install the package:

npm install shadcn-rails-stimulus

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn-rails-stimulus"

const application = Application.start()
registerShadcnControllers(application)

Install the package:

yarn add shadcn-rails-stimulus

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn-rails-stimulus"

const application = Application.start()
registerShadcnControllers(application)

Install the package:

npm install shadcn-rails-stimulus

Then in your app/javascript/controllers/index.js:

import { Application } from "@hotwired/stimulus"
import { registerShadcnControllers } from "shadcn-rails-stimulus"

const application = Application.start()
registerShadcnControllers(application)

Or import just this controller:

import AvatarController from "shadcn-rails-stimulus/controllers/avatar_controller"

application.register("shadcn--avatar", AvatarController)

Targets

Name	Description
image	The avatar image element
fallback	The fallback element shown when image fails

Actions

Action	Description
handleError	Called when image fails to load, shows fallback

TypeScript

Type definitions are included. Import types as needed:

import type { AvatarController } from "shadcn-rails-stimulus"

Accessibility

Always provide meaningful alt text for the avatar
The fallback text is visible to screen readers when shown
If the avatar is decorative (e.g., displayed alongside a name), you can use an empty alt: alt: ""

On This Page

Installation Usage Examples API Reference