PhxMediaLibrary

Attach files to any Ecto schema, inspired by Spatie's Laravel Media Library.

You declare collections and conversions next to your schema, pipe an upload into a collection, and render it with a component. The library stores the file under a safe name, makes thumbnails, WebP, AVIF and responsive sizes in the background, and gives every image a tiny placeholder.

Quick look

defmodule MyApp.Post do
  use Ecto.Schema
  use PhxMediaLibrary.HasMedia

  schema "posts" do
    field :title, :string

    has_media()          # all media for this model
    has_media(:images)   # scoped to "images" collection
    has_media(:avatar)   # scoped to "avatar" collection

    timestamps()
  end

  media_collections do
    collection :images, max_files: 20, max_size: 10_000_000, webp: true, avif: true, responsive: true
    collection :documents, accepts: ~w(application/pdf text/plain), file_naming: :random
    collection :avatar, single_file: true, fallback_url: "/images/default.png"
  end

  media_conversions do
    convert :thumb, width: 150, height: 150, fit: :cover
    convert :preview, width: 800, quality: 85
    convert :banner, width: 1200, height: 400, fit: :crop, collections: [:images]
  end
end

{:ok, media} =
  post
  |> PhxMediaLibrary.add("/path/to/photo.jpg")
  |> PhxMediaLibrary.with_custom_properties(%{"alt" => "Red summer dress"})
  |> PhxMediaLibrary.to_collection(:images)

PhxMediaLibrary.get_media(post, :images)
PhxMediaLibrary.get_first_media_url(post, :images, :thumb)

PhxMediaLibrary.delete(media)
{:ok, count} = PhxMediaLibrary.clear_collection(post, :images)

LiveView uploads

defmodule MyAppWeb.PostLive.Edit do
  use MyAppWeb, :live_view
  use PhxMediaLibrary.LiveUpload

  def mount(%{"id" => id}, _session, socket) do
    post = Posts.get_post!(id)

    {:ok,
     socket
     |> assign(:post, post)
     |> allow_media_upload(:images, model: post, collection: :images)
     |> stream_existing_media(:media, post, :images)}
  end

  def handle_event("save_media", _params, socket) do
    case consume_media(socket, :images, socket.assigns.post, :images) do
      {:ok, saved} ->
        {:noreply, stream_media_items(socket, :media, saved)}

      {:error, {:partial, saved, failed}} ->
        {:noreply,
         socket
         |> stream_media_items(:media, saved)
         |> put_flash(:error, "#{length(failed)} file(s) could not be uploaded")}
    end
  end
end

<form phx-change="validate" phx-submit="save_media">
  <.media_upload upload={@uploads.images} id="post-images" />
  <button type="submit">Upload</button>
</form>

<.media_gallery media={@streams.media} id="gallery">
  <:item :let={{_id, media}}>
    <.media_img media={media} conversion={:thumb} class="rounded-lg" />
  </:item>
</.media_gallery>

Fast pages by default

The image components do the page-speed work for you:

<%!-- The hero: loads first, no lazy loading --%>
<.responsive_img media={@post.cover} priority class="w-full h-auto" />

<%!-- A product grid: lazy, and the browser picks the size for the slot --%>
<.responsive_img
  :for={product <- @products}
  media={product.photo}
  conversion={:preview}
  sizes="(max-width: 768px) 50vw, 25vw"
/>

• Placeholders. Every image gets a 32px blurred WebP of about 260 bytes, set as its background until it loads. No JavaScript, no layout jump. placeholder: :color uses the average color instead.
• No layout shift. width and height come from the stored file, so the browser reserves the space.
• The right size. With responsive: true, srcset lists every variant, and lazy images default to sizes="auto, 100vw", so supporting browsers measure the slot instead of assuming the full screen.
• Small formats. Conversions are WebP by default. webp: true also serves the original as WebP; avif: true adds an AVIF of the original and its sizes, which <.picture> and <.responsive_img> offer first, with WebP or the original as the fallback. A plain URL is never AVIF, since AI tools and most link previews can't read it.
• Priority. priority marks the page's main image loading="eager" and fetchpriority="high"; other images decode asynchronously.
• Caching. cdn_url/2 adds a content fingerprint (?vsn=…) that Plug.Static answers with a one-year cache.

Files named by the library

Uploaded filenames are never trusted. The library picks the stored name: posts_42_images_<uuid>.jpg by default, a readable summer-dress.jpg with file_naming: :slug (Cyrillic is transliterated), or a name that reveals nothing with :random. The uploaded name is kept, and the library uses it for alt text and as the name of downloads, Лятна рокля.pdf included.

A doctor for your media

$ mix phx_media_library.doctor               # report only
$ mix phx_media_library.doctor --regenerate  # make missing thumbnails, WebP, AVIF, placeholders
$ mix phx_media_library.doctor --rename      # move older files to the naming scheme
$ mix phx_media_library.doctor --id <uuid>   # one media item

It finds media with no files left, missing derivatives, lost metadata, checksum mismatches (--deep) and records whose parent is gone. Repairs show their plan and ask first.

Uploads straight to S3 or R2

presigned_upload/3 signs a browser upload to S3, Cloudflare R2 or any S3-compatible service, as a form POST or a PUT, whichever the provider supports. complete_external_upload/4 then reads the stored file and checks its size and type against the collection before recording it. The storage guide has a LiveView uploader.

Features

Installation

def deps do
  [
    {:phx_media_library, "~> 0.9"},

    # Optional: image processing (requires libvips)
    {:image, "~> 0.54"},

    # Optional: S3 storage
    {:ex_aws, "~> 2.5"},
    {:ex_aws_s3, "~> 2.5"},
    {:sweet_xml, "~> 0.7"},

    # Optional: async processing with Oban
    {:oban, "~> 2.18"}
  ]
end

# config/config.exs
config :phx_media_library,
  repo: MyApp.Repo,
  default_disk: :local,

  # The column type of your models' primary keys.
  # :binary_id  UUID (default, keeps existing installs working)
  # :integer    bigint (integer primary keys)
  # :string     varchar (any primary key type; recommended for new apps)
  mediable_id_type: :string,

  disks: [
    local: [
      adapter: PhxMediaLibrary.Storage.Disk,
      root: "priv/static/uploads",
      base_url: "/uploads"
    ]
  ]

# For integer primary keys, pass --id-type to generate the right column:
mix phx_media_library.install --id-type integer
mix ecto.migrate

mediable_id_type sets the column type of the polymorphic foreign key. The default stays :binary_id (UUID) so existing installs keep working; :string works with any primary key type. Set it explicitly and a future change of default won't affect you.

The :image dependency is optional. Without it the library stores files; conversions, WebP, AVIF and placeholders need it.

Guides

Full API documentation is on HexDocs.

Contributing

Contributions are welcome. Please open a pull request.

The tests need Postgres on localhost (user and password postgres), and podman or Docker for the S3 tests. Those run against a Ministack container that the first mix test starts and later runs reuse; without podman or Docker they are skipped. Run mix precommit before opening a pull request.

1. Fork it
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Create a pull request

License

MIT. See the LICENSE file.

Acknowledgments

Inspired by Spatie's Laravel Media Library.