Avatar

Images and accessible initial fallbacks at predictable sizes.

Source: app/components/nitro_kit/avatar.rb
API: NitroKit::Avatar.new(src:, alt:, fallback:, size:)

Sizes

All closed sizes keep fallback text, geometry, and accessibility semantics aligned.

Size scale

Extra small

Small

Medium

Large

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/avatar_page.rb

Gallery::Data.avatar_sizes.each do |avatar|
  sample(avatar.label, slug: avatar.slug) do
    render_avatar(avatar)
  end
end

Images and fallbacks

Image, generated initials, custom long fallback, anonymous, and broken-image states are explicit.

Content modes

Image

Generated initials

Long custom fallback

Anonymous

Broken image

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/avatar_page.rb

sample("Image", slug: "image") do
  render NitroKit::Avatar.new(
    src: "/gallery/avatars/ada.svg",
    alt: "Ada Lovelace",
    fallback: "AL",
    size: :lg,
    id: "gallery-avatar-image"
  )
end
sample("Generated initials", slug: "generated-initials") do
  render NitroKit::Avatar.new(
    alt: "Alexandria Ocasio-Cortez",
    size: :lg,
    id: "gallery-avatar-generated"
  )
end
sample("Long custom fallback", slug: "long-fallback") do
  render NitroKit::Avatar.new(
    alt: "Platform engineering team",
    fallback: "TEAM",
    size: :lg,
    id: "gallery-avatar-long-fallback"
  )
end
sample("Anonymous", slug: "anonymous") do
  render NitroKit::Avatar.new(size: :lg, id: "gallery-avatar-anonymous")
end
sample("Broken image", slug: "broken-image") do
  render NitroKit::Avatar.new(
    src: "/gallery/avatars/missing.svg",
    alt: "Katherine Johnson",
    fallback: "KJ",
    size: :lg,
    id: "gallery-avatar-broken-image"
  )
end

Accessible names

Fallback-only identities label the root; image identities retain native alt text.

Named identities

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/avatar_page.rb

render NitroKit::Avatar.new(
  alt: "Katherine Johnson",
  fallback: "KJ",
  id: "gallery-avatar-labelled-fallback"
)
render NitroKit::Avatar.new(
  src: "/gallery/avatars/grace.svg",
  alt: "Grace Hopper",
  fallback: "GH",
  id: "gallery-avatar-labelled-image"
)

Under pressure

Generated initials for every Gallery::Hostile identity, from unbroken, RTL, CJK, Thai, and emoji names to zero-width, combining, and single-letter ones, plus four-grapheme and non-Latin custom fallbacks at every size and a broken image falling back to four letters of an unbroken word.

Hostile initials

Identity 1

Identity 2

Identity 3

Identity 4

Identity 5

Identity 6

Identity 7

Identity 8

Identity 9

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/avatar_page.rb

Gallery::Hostile::NAMES.each_with_index do |name, index|
  sample("Identity #{index + 1}", slug: "identity-#{index + 1}") do
    render NitroKit::Avatar.new(alt: name, size: :lg, id: "gallery-avatar-hostile-initials-#{index + 1}")
  end
end

Hostile fallbacks

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/avatar_page.rb

Gallery::Hostile::INITIALS.each_with_index do |fallback, index|
  render NitroKit::Avatar.new(
    alt: Gallery::Hostile::NAMES.fetch(index),
    fallback:,
    size: %i[xs sm md lg].fetch(index % 4),
    id: "gallery-avatar-hostile-fallback-#{index + 1}"
  )
end
render NitroKit::Avatar.new(
  alt: Gallery::Hostile::LONG_NAME,
  fallback: Gallery::Hostile::LONG_WORD[0, 4],
  size: :lg,
  id: "gallery-avatar-hostile-fallback-word"
)
render NitroKit::Avatar.new(
  src: "/gallery/not-an-image.txt",
  alt: Gallery::Hostile::LONG_NAME,
  fallback: Gallery::Hostile::LONG_WORD[0, 4],
  size: :md,
  id: "gallery-avatar-hostile-broken-image"
)

Component contract

Constructor options, rendered root, closed vocabularies, and compound boundary for this component, exactly as shipped.

docs/component_contracts.md · NitroKit::Avatar

Constructor-specific options: src: nil, alt: "", fallback: nil, decorative: false, size: :md, loading: "lazy", decoding: "async", id: nil
Root and closed vocabulary: span[data-nk=avatar]; sizes xs sm md lg; state error
Compound contract: Renders fallback and optional image slots. The source is a keyword; there is no positional form. fallback: is a non-blank String of at most four characters; derived initials never exceed two, and three- or four-character fallbacks carry data-length so the stylesheet steps the type down to stay inside the circle. An image with empty alt: raises unless decorative: true. When a source is present the root carries nk--avatar, which sets data-state="error" if the image fails to load so the initials fallback shows through instead of a broken-image glyph, and unhides that fallback for assistive technology.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.