SVG Formatter
Provides a field formatter that enables the display of SVG images on Drupal websites through file and image fields.
svg_formatter
Install
composer require 'drupal/svg_formatter:^2.0'
composer require 'drupal/svg_formatter:8.x-1.18'
Overview
The SVG Formatter module addresses a fundamental limitation in Drupal's standard image field, which does not natively support SVG (Scalable Vector Graphics) images. This module provides a specialized field formatter that can be applied to file fields or image fields (when used with the SVG Image module), allowing SVG files to be displayed on your website.
The module offers two output modes: standard image tag output using the <img> element, or inline SVG output where the SVG markup is embedded directly in the HTML. The inline mode is particularly useful when you need to manipulate the SVG with CSS or JavaScript, such as for animations, interactive graphics, or dynamic color changes.
A key security feature is the integration with the enshrined/svg-sanitize library, which sanitizes inline SVG content to prevent XSS (Cross-Site Scripting) attacks. This is critical when allowing users to upload SVG files, as malicious SVGs can contain embedded JavaScript code. The module also supports configurable dimensions, alt text, and title attributes with token integration for dynamic values.
Features
- Provides SVG Formatter field formatter for file and image field types
- Inline SVG output mode for CSS and JavaScript manipulation of SVG graphics
- SVG sanitization using enshrined/svg-sanitize library to prevent XSS attacks from malicious SVG uploads
- Configurable image dimensions (width and height) that can be applied to both inline SVG elements and img tags
- Alt text attribute support with automatic generation from filename or custom token-based values
- Title attribute support for accessibility, automatically adds aria-labelledby for inline SVGs
- Token integration for dynamic alt and title values based on entity fields (requires Token module)
- Automatic filtering to only process files with image/svg+xml MIME type
- Compatible with both file fields and image fields (image fields require SVG Image module)
Use Cases
Display logos and icons with CSS customization
Use inline SVG mode to display brand logos or icons that need to change color based on theme or user interaction. With inline SVG, you can target SVG elements with CSS selectors to change fill colors, stroke widths, or apply hover effects.
Responsive vector graphics
Display illustrations, diagrams, or infographics as SVG images that scale perfectly at any resolution. Set the dimensions in the formatter or leave them to be controlled by CSS for fully responsive behavior.
Accessible iconography
Create accessible icon sets by enabling alt and title attributes. Use tokens to dynamically generate descriptive text based on the content, ensuring screen readers can properly describe the images.
User-uploaded SVG content with security
Allow content editors or site users to upload SVG images while protecting against XSS attacks. Enable the sanitize option to automatically remove potentially malicious scripts and event handlers from uploaded SVGs.
Interactive data visualizations
Use inline SVG mode to display charts, graphs, or interactive maps that can be manipulated with JavaScript. The inline mode exposes the SVG DOM elements, allowing libraries like D3.js to interact with the graphics.
Tips
- For best CSS manipulation, use inline SVG mode and ensure your SVG files use classes or IDs on the elements you want to style.
- Token module integration allows using tokens like [node:title] or [file:name] for dynamic alt and title text based on the parent entity.
- The alt text is automatically generated from the filename if no custom token is specified - 'my-icon.svg' becomes 'My icon'.
- For accessibility, inline SVGs with title enabled automatically include aria-labelledby attributes linking to the title element.
- The formatter automatically skips non-SVG files in multi-value fields, so you can mix SVG and other file types in the same field.
Technical Details
Hooks 2
hook_help
Implements hook_help to provide module documentation on the help page.
hook_theme
Implements hook_theme to register the svg_formatter theme hook with its variables.
Troubleshooting 5
Install the SVG Image module (drupal/svg_image). The formatter only appears for image fields when SVG Image module is installed, as Drupal's core image field doesn't support SVG uploads by default.
Verify that the enshrined/svg-sanitize library is installed. Run 'composer require enshrined/svg-sanitize' if it's missing. The sanitize checkbox will be disabled if the library is not found.
Install and enable the Token module for token support. The module provides a token browser in the formatter settings to help select valid tokens for your entity type.
Ensure 'Set image dimensions' is enabled in the formatter settings. For inline SVGs, dimensions are set as attributes on the SVG root element. Some SVGs may override this with internal CSS - check the SVG source.
The SVG file may have invalid XML or encoding issues. Ensure the SVG is valid XML and uses UTF-8 encoding. The module uses DOMDocument to parse SVGs, which requires well-formed XML.
Security Notes 4
- Always install the module via Composer to ensure the enshrined/svg-sanitize library is included. Without this library, inline SVGs will not be sanitized and may expose your site to XSS vulnerabilities.
- When allowing untrusted users to upload SVG files, always enable the 'Sanitize inline SVG' option to remove potentially malicious JavaScript code embedded in SVG files.
- The sanitization library removes script tags, event handlers, and other potentially dangerous elements from SVG files when using inline mode.
- When using non-inline mode (img tag), SVGs are treated as external resources and browser security prevents script execution, making sanitization less critical but still recommended for defense in depth.