Progressive image

Active Storage images with low-resolution previews and explicit lifecycle states.

Source: app/components/nitro_kit/progressive_image.rb
API: NitroKit::ProgressiveImage.new(attachment:, alt:, size: :md, decorative: false)

Progressive loading

A decorative low-resolution variant covers the full image until browser decoding succeeds.

Workspace illustration

ViewportFull width

Width

Preset

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

render NitroKit::ProgressiveImage.new(
  attachment: image_attachment,
  alt: "Abstract indigo workspace illustration",
  size: :lg,
  id: "gallery-progressive-image-loaded"
)

Resolution sizes

Closed sizes request predictable one- and two-density Active Storage variants without accepting arbitrary processing options.

Variant scale

Viewport640 px · sm

Width

Preset

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

NitroKit::ProgressiveImage::SIZES.each do |size|
  sample(size.to_s.upcase, slug: size) do
    render NitroKit::ProgressiveImage.new(
      attachment: image_attachment,
      alt: "Abstract indigo workspace illustration",
      size:,
      id: "gallery-progressive-image-#{size}"
    )
  end
end

Missing and broken media

Empty markup is complete on the server; failed loads reveal the fallback while preserving informative alt text.

Fallback states

Empty attachment

Workspace cover

Viewport640 px · sm

Width

Preset

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

sample("Empty attachment", slug: "empty") do
  render NitroKit::ProgressiveImage.new(
    attachment: nil,
    alt: "Workspace cover",
    size: :sm,
    id: "gallery-progressive-image-empty"
  )
end
sample("Failed variant", slug: "error") do
  render NitroKit::ProgressiveImage.new(
    attachment: broken_attachment,
    alt: "Unavailable workspace cover",
    size: :sm,
    id: "gallery-progressive-image-error"
  )
end

Accessibility intent

The placeholder never enters the accessibility tree; decorative full images also use an empty alt.

Decorative media

Viewport640 px · sm

Width

Preset

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

render NitroKit::ProgressiveImage.new(
  attachment: image_attachment,
  alt: nil,
  decorative: true,
  size: :md,
  id: "gallery-progressive-image-decorative"
)

Record composition

Progressive media, a card, status, and record details compose without utility classes or helper registration.

Workspace overview

Mothership workspace

Owner	Ada Lovelace
Status	Active
Updated on	July 13, 2026

ViewportFull width

Width

Preset

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

render NitroKit::Card.new(id: "gallery-progressive-image-card") do |card|
  card.full do
    render NitroKit::ProgressiveImage.new(
      attachment: image_attachment,
      alt: "Abstract indigo workspace illustration",
      size: :lg,
      id: "gallery-progressive-image-card-media"
    )
  end
  card.title(SUMMARY.title, level: 3)
  card.body do
    render NitroKit::DetailsTable.new(SUMMARY, id: "gallery-progressive-image-card-details") do |details|
      details.field(:owner)
      details.field(:status) do |status|
        render NitroKit::Badge.new(
          status.to_s.humanize,
          id: "gallery-progressive-image-card-status",
          color: :success,
          size: :sm
        )
      end
      details.field(:updated_on)
    end
  end
end

Component contract

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

docs/component_contracts.md · NitroKit::ProgressiveImage

Constructor-specific options: required attachment:
alt: nil, size: :md, decorative: false, id: nil
Root and closed vocabulary: div[data-nk=progressive-image]; sizes sm md lg; states empty loading loaded error
Compound contract: Owns placeholder, image, and fallback slots. The placeholder is decorative and the full image is the only image in the accessibility tree. alt: is required unless decorative: true, and non-decorative attached images require non-blank alt text. The fallback surfaces that alt text, falling back to I18n.t("nitro_kit.progressive_image.unavailable") when there is none. Only an attached image can change after render, so only that fallback is a role="status" live region; the never-attached empty state is ordinary static content. data-enhanced on the root is the controller-connected flag shared with AppShell; it is deliberately not data-state, which already carries the closed load-state vocabulary.

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.