Rendering Images

Images are stored as originals in the Alchemy picture library. Editors assign these images to Picture ingredients on elements. You control the rendering dimensions, cropping, and output format through ingredient settings and rendering options.

Alchemy supports two storage adapters: ActiveStorage and Dragonfly. Both use the same rendering API, so you can switch between them without changing your templates.

Configuration

Image rendering is configured in your initializer. See the Configuration guide for all available options.

# config/initializers/alchemy.rb
Alchemy.configure do |config|
  config.output_image_quality = 85
  config.preprocess_image_resize = "1000x1000"
  config.image_output_format = "original"
  config.sharpen_images = false
end

TIP

You can override the output format and quality per ingredient by passing format and quality as rendering options.

Rendering

In most cases, rendering a Picture ingredient through el.render(:image) in your element view is all you need. It generates the correct image URL with all configured options applied.

<%# app/views/alchemy/elements/_article.html.erb %>
<%= el.render(:hero_image) %>

The output depends on what the editor has configured on the picture:

• Image only — renders an <img> tag
• With caption — wraps in a <figure> with a <figcaption>
• With link — wraps the image in an <a> tag
• With caption and link — wraps the linked image in a <figure> with a <figcaption>

Ingredient Settings

Configure rendering in your elements.yml definition.

- name: article
  ingredients:
    - role: hero_image
      type: Picture
      settings:
        size: 1200x600
        crop: true

See the Picture ingredient settings for the full list of options.

Rendering Options

These options control how the image variant is generated.

size

String

The dimensions to resize the image to, preserving aspect ratio. Example: "400x300".

crop

Boolean

Crop the image to exactly match the given size.

format

String

The output format: "jpg", "png", "gif", or "webp".

quality

Integer

The quality of rendered JPEG and WebP images.

upsample

Boolean

Allow the image to be scaled up beyond its original dimensions. By default, images are only scaled down.

Responsive Images

Use the srcset and sizes ingredient settings to generate responsive <img> tags with multiple sources.

- role: photo
  type: Picture
  settings:
    size: 1200x800
    crop: true
    srcset: ['400x267', '800x533', '1200x800']
    sizes: ['(max-width: 600px) 400px', '(max-width: 900px) 800px', '1200px']

This renders an <img> tag with a srcset attribute containing URLs for each size and a sizes attribute telling the browser which source to use at each viewport width.

Remote Storage

In production you typically want to store images on a remote service like Amazon S3, Google Cloud Storage, or Azure Storage instead of the local filesystem.

With ActiveStorage, configure your storage service in config/storage.yml and set the active service in your environment config, just like any Rails application. See the Active Storage Overview in the Rails guides.

# config/storage.yml
amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: eu-central-1
  bucket: my-app-production

# config/environments/production.rb
config.active_storage.service = :amazon

With Dragonfly, use the alchemy-dragonfly-s3 extension to store images on S3 compatible services.

TIP

See Extensions for all available storage add-ons.

Caching

Alchemy caches rendered image variants automatically. The caching strategy depends on your storage adapter.

ActiveStorage uses Rails' built-in variant caching. Variants are generated on first request and stored alongside the original blob.

Dragonfly uses Alchemy's PictureThumb model to cache rendered variants in the database. Three admin thumbnail sizes are pregenerated on upload.

In both cases, adding a CDN in front of your application is recommended for production to avoid hitting the application server for repeated image requests.