File

The file field uploads a single Active Storage attachment and displays images, audio, and video using the appropriate preview or player. It uses your application's Active Storage settings, including supported disk services.

# app/avo/resources/user.rb
class Avo::Resources::User < Avo::BaseResource
  def fields
    field :avatar, as: :file
  end
end

By default, uploads pass through your server without a file-type filter. Filenames are visible, images open in a lightbox on the Show view, and index previews do not link to the record.

Set up a single attachment

Configure Active Storage in your application and declare the attachment on your model:

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar
end

Use the Files field for multiple attachments.

WARNING

You must manually require activestorage and image_processing gems in your Gemfile.

# Active Storage makes it simple to upload and reference files
gem "activestorage"

# High-level image processing wrapper for libvips and ImageMagick/GraphicsMagick
gem "image_processing"

Choose which files users can upload

Set accept to filter the browser's file picker:

# app/avo/resources/user.rb
field :avatar, as: :file, accept: "image/*"

WARNING

The browser's filter does not validate uploads. Enforce file-type and size restrictions on the server.

Upload large files directly to storage

Enable direct_upload to send files directly to your storage service rather than through your application server. Complete Rails' direct upload setup, including any required storage CORS configuration.

# app/avo/resources/user.rb
field :avatar, as: :file, direct_upload: true

Choose where uploads are stored

Active Storage stores every upload under a random key. Set key to choose the key yourself, so the files in your bucket can be found by name. Since avo >= v4.4.4

# app/avo/resources/post.rb
field :cover,
  as: :file,
  key: -> { "posts/#{SecureRandom.base36(8)}/#{ActiveStorage::Filename.new(file.original_filename).sanitized}" }

The block gets the record, the resource, the field and the uploaded file. If it returns nil or an empty string, the file keeps a random key.

WARNING

• Keys are unique. When a key is already taken, the form shows "has already been taken" on the field and nothing is saved. Replacing a file with one of the same name counts, because the old file still exists at that moment. Put something that changes per upload in the key, like the random segment above.
• New records have no id yet. On the New page record.id and record.to_param are nil, so don't build the key from them.
• file.original_filename comes from the browser. Sanitize it before it goes into a key, as above.
• Only files uploaded through the form get the key. With direct_upload, or a file picked from the Media Library, the file is already stored when the form is sent, so it keeps its key.

Displaying images

Avo displays an attachment straight from storage — PNG, JPEG, GIF, WebP, AVIF, and everything else browsers know how to paint.

Four formats they don't get converted first: image/heic and image/heif (what an iPhone shoots by default), image/tiff, and image/vnd.adobe.photoshop. Avo displays those through an Active Storage variant, which renders them as PNG. Only Safari decodes HEIC, so the original would be a broken image in Chrome, Edge, and Firefox.

WARNING

Converting needs an image processor installed — libvips built with libheif, or ImageMagick with the HEIC delegate. Without one the variant can't be processed and the image won't render. See Active Storage's requirements.

Authorization

INFO

Please ensure you have the upload_{FIELD_ID}?, delete_{FIELD_ID}?, and download_{FIELD_ID}? methods set on your model's Pundit policy. Otherwise, the input and download/delete buttons will be hidden.

Related:

• Attachment pundit policies

Customize the attachment preview

Hide the filename below Show and form previews with display_filename. Disable lightbox if clicking an image on Show should not open a preview overlay:

# app/avo/resources/user.rb
field :avatar, as: :file, display_filename: false, lightbox: false

The lightbox closes with Escape or a click outside the image. Its original-file link is available only when downloading is authorized. Audio and video keep their players; other files keep their file controls.

Display a processed image variant

When using the file field to display an image, you can opt to show a processed variant of that image. This can be achieved using the format_using option.

# app/avo/resources/user.rb
field :photo,
  as: :file,
  format_using: -> {
    value.variant(resize_to_limit: [150, 150]).processed.image
  }

Link index previews to the record

Enable link_to_record to make image and audio previews on Index link to the record's Show page. Other file types still display their filename on Index.

# app/avo/resources/user.rb
field :avatar, as: :file, link_to_record: true

Options reference

See the File API for field-specific contracts and defaults, and Common field options for shared configuration.