Progressive Image

Progressive Image component provides smooth image loading experiences with blur-to-sharp transitions. Perfect for displaying ActiveStorage attachments with automatic placeholder generation, responsive sizing, and optimized loading performance.

Basic Example

<%= nk_progressive_image(attachment: @game.box_art, alt: @game.title) %>

Different Sizes

Choose from predefined sizes or specify custom dimensions for optimal image delivery.

Small

Medium

Large

Custom Size (500px)

<% game = Game.find_by(title: "Mario Kart 8") || Game.with_attached_box_art.first %>

<div class="grid grid-cols-1 gap-4 w-full md:grid-cols-3">
  <div>
    <h3 class="mb-2 text-sm font-medium">Small</h3>
    <%= nk_progressive_image(attachment: game&.box_art, size: :sm, alt: game&.title) %>
  </div>

  <div>
    <h3 class="mb-2 text-sm font-medium">Medium</h3>
    <%= nk_progressive_image(attachment: game&.box_art, size: :md, alt: game&.title) %>
  </div>

  <div>
    <h3 class="mb-2 text-sm font-medium">Large</h3>
    <%= nk_progressive_image(attachment: game&.box_art, size: :lg, alt: game&.title) %>
  </div>
</div>

<div class="mt-6">
  <h3 class="mb-2 text-sm font-medium">Custom Size (500px)</h3>
  <%= nk_progressive_image(
    attachment: game&.box_art,
    size: 500,
    alt: game&.title,
    class: "max-w-md",
  ) %>
</div>

<%= nk_progressive_image(attachment: @game.box_art, size: :small, alt: @game.title) %>
<%= nk_progressive_image(attachment: @game.box_art, size: :medium, alt: @game.title) %>
<%= nk_progressive_image(attachment: @game.box_art, size: :large, alt: @game.title) %>

<!-- Custom size -->
<%= nk_progressive_image(attachment: @game.box_art, size: 500, alt: @game.title) %>

Handling Missing Images

Component gracefully handles cases where no image is attached with a placeholder div.

<!-- When attachment is nil or not attached -->
<%= nk_progressive_image(attachment: nil, alt: "Missing image") %>

Install

Premium

Set up Nitro Kit then

bin/rails app:template \
  LOCATION="https://nitrokit.dev/t/premium/progressive_image?license=LICENSE-KEY"

Usage


`nk_progressive_image(attachment:, alt: nil, size: :medium, **attrs)`
Property	Default	Description
`attachment`	`ActiveStorage::Attached::One`	The ActiveStorage attachment to display. Component handles nil/unattached gracefully.
`alt`	`String`	Alt text for accessibility. Highly recommended for all images.
`size`	`:small, :medium, :large, or Integer`	Controls image variant resolution (:small=250px, :medium=720px, :large=1800px). Component grows to fill container width.
`**attrs`		HTML attributes for `<div>` element

Helper Method


`nk_progressive_image(attachment:, alt: nil, size: :medium, **attrs)`
Property	Default	Description
`attachment`	`ActiveStorage::Attached::One`	The ActiveStorage attachment to display progressively.
`alt`	`String`	Alt text for the image. Essential for accessibility.
`size`	`:small, :medium, :large, or Integer`	Controls image variant resolution, not display size. Component fills its container width.
`**attrs`		HTML attributes for `<div>` element

How It Works

The Progressive Image component creates a smooth loading experience through these steps:

Placeholder Generation: Creates a tiny (50x50px), low-quality version as a blurred background
Full Image Loading: Loads the full-resolution image with proper srcset for high-DPI displays
Smooth Transition: Uses CSS opacity transition to fade from blur to sharp image
Responsive Images: Automatically generates 1x and 2x variants for different screen densities
Lazy Loading: Images load only when they enter the viewport
Error Handling: JavaScript controller gracefully handles loading failures

💡 ActiveStorage Analysis Recommended

For proper aspect ratio styling, ActiveStorage attachments should be analyzed to extract image dimensions. Analysis happens automatically when attachments are created, but you can ensure it with:

attachment.analyze unless attachment.analyzed?

Or add a callback to your model for automatic analysis:

class Post < ApplicationRecord
  has_one_attached :image
  
  after_commit :analyze_image, on: [:create, :update]
  
  private
  
  def analyze_image
    image.analyze_later if image.attached? && !image.analyzed?
  end
end

Performance Benefits

Perceived Performance: Users see content immediately with blur placeholder
Bandwidth Optimization: Loads appropriately sized images based on display requirements
Layout Stability: Maintains proper aspect ratios to prevent content shifts
Modern Web Standards: Uses native lazy loading and responsive images