Image URL Formatter

Provides field formatters that output the URL of images and files instead of rendering HTML elements.

image_url_formatter
30,860 sites
34
drupal.org
field
field formatter image file url views
Drupal 8 Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10 v2.0.0
composer require 'drupal/image_url_formatter:^2.0'
Drupal 9, 8 v8.x-1.1
composer require 'drupal/image_url_formatter:8.x-1.1'

Overview

Image URL Formatter adds a new display formatter for Image and File fields that outputs the direct URL to the file instead of rendering the full HTML <img> or link markup. This is particularly useful when you need to use the image URL in custom templates, JavaScript applications, or integrate with external services that require raw URLs.

The module supports both image fields and file fields, with flexible URL output options including full URLs, absolute paths, and relative paths. For image fields, you can also apply image styles to get the URL of a processed derivative image rather than the original.

Features

  • Outputs image/file URLs instead of rendered HTML markup
  • Three URL type options: Full URL, Absolute file path, and Relative file path
  • Image style support for processed derivative image URLs (image fields only)
  • Optional linking to content entity or file
  • Compatible with Views for displaying image URLs
  • Customizable output via Twig template override

Use Cases

Headless/Decoupled Drupal

When building a decoupled Drupal site with a JavaScript frontend (React, Vue, Angular), you often need raw image URLs instead of rendered HTML. Use Image URL Formatter in Views REST exports or JSON:API to provide clean image URLs for your frontend application.

Custom Twig Templates

When building custom templates that require precise control over image markup, use Image URL Formatter to get the image URL, then construct your own <img> tags with custom attributes, lazy loading, or JavaScript-powered image galleries.

CSS Background Images

For design patterns that use background images in CSS, output the image URL and use it in inline styles or pass it to JavaScript for dynamic background setting.

Social Media Meta Tags

When constructing Open Graph or Twitter Card meta tags that require absolute image URLs, use the Full URL option to get complete URLs suitable for social sharing previews.

Email Templates

Email clients require absolute URLs for images. Use the Full URL option to generate properly formatted image URLs for HTML emails.

Image Preloading

Generate a list of image URLs for JavaScript-based preloading, lazy loading libraries, or service worker caching strategies.

Tips

  • Use 'Full URL' when the URL will be used outside your site (emails, APIs, social sharing)
  • Use 'Relative file path' for the most portable option within your own templates
  • The formatter works with multi-value image fields, outputting a URL for each image
  • Override the image-url-formatter.html.twig template in your theme to customize the output format
  • In Views, you can use the URL output as a token in rewrite results for complex formatting needs

Technical Details

Hooks 1
hook_theme

Defines the image_url_formatter theme hook with variables for item, url, image_style, and url_type

Troubleshooting 3
Image style URL shows original image path

Clear the cache after changing image style settings. If the derivative doesn't exist yet, Drupal will generate it on first access.

Relative path doesn't work with CDN

Use 'Full URL' when your site uses a CDN or different domain for files, as relative paths won't include the correct domain.

URL appears with extra HTML

Check that you're using 'Image URL Formatter' and not 'Image' formatter. Also verify no other modules are altering the field output.