SVG Image Field
Provides a dedicated field type, widget, and formatters for uploading and displaying SVG (Scalable Vector Graphics) images in Drupal.
svg_image_field
Install
composer require 'drupal/svg_image_field:^2.3'
Overview
The SVG Image Field module addresses a significant limitation in Drupal's core Image field, which does not support SVG files. This module provides a complete solution for handling SVG images by introducing a new field type called "Vector image" along with a specialized widget and formatter.
Unlike the standard file field approach, SVG Image Field provides proper support for alt and title attributes at the database level, an intuitive user experience (simply select "Vector image" as your field type), built-in mime type validation to ensure only valid SVG files are uploaded, and a preview image during file upload.
The module supports both inline SVG rendering (allowing CSS and JavaScript manipulation) and standard img tag output. When using inline rendering, the module can sanitize SVG content to prevent XSS attacks using the enshrined/svg-sanitize library. Additional features include the ability to force fill to currentColor for dynamic coloring, link images to content or file URLs, and apply custom dimensions.
SVG Image Field also integrates seamlessly with Drupal's Media system through a dedicated media source plugin, enabling SVG files to be managed as media entities. The optional submodule (SVG Image Field - Media Bundle) provides a pre-configured media type ready for immediate use with the Media Library.
Features
- Dedicated "Vector image" field type specifically designed for SVG files with proper alt and title attribute support at the database level
- SVG-specific widget with configurable preview image dimensions (max width and height) and file upload validation
- Multiple display options including inline SVG rendering for CSS/JavaScript manipulation and standard img tag output
- Built-in SVG sanitization using enshrined/svg-sanitize library to prevent XSS attacks, with optional remote reference removal
- Configurable image dimensions (width and height) applied to the output
- Option to force fill attribute to currentColor, allowing SVGs to inherit color from parent elements like links
- Link SVG images to content entity or file URL
- Default image configuration at both field storage and field instance levels
- Media source plugin (SVG) for integration with Drupal's core Media module
- Stage File Proxy module compatibility for development environments
- Media Library integration with proper styling for SVG thumbnails
- Comprehensive file validation ensuring uploaded files have correct MIME type (image/svg+xml) and valid SVG XML structure
Use Cases
Logo and Icon Management
Use SVG Image Field for site logos and icons that need to scale perfectly at any size. The inline rendering option allows icons to inherit colors from CSS, enabling hover effects and theme color variations without creating multiple image files.
Media Library SVG Assets
Enable the Media Bundle submodule to create a Vector image media type. Content editors can then upload SVGs through the Media Library, reuse them across the site, and manage them centrally alongside other media assets like images and videos.
Responsive Graphics
Store infographics, diagrams, or illustrations as SVGs. With dimensions configured in the formatter, the same SVG can be displayed at different sizes in different view modes (teaser vs full) while maintaining crisp quality.
Accessible Vector Images
Take advantage of built-in alt and title field support to ensure all SVG images have proper accessibility metadata. Configure the field to require alt text for compliance with accessibility standards.
Secure User-Generated SVGs
When accepting SVG uploads from less trusted users, enable the sanitize option to strip potentially malicious code. Use sanitize_remote to also remove external references that could leak data.
CSS-Themeable Icons
Use force_fill option with inline rendering to create icons that automatically adopt the text color of their parent element. Perfect for icon buttons or links where the icon should match the link color on hover.
Tips
- Enable both 'Sanitize SVG code' and 'Remove remote references' options when accepting SVG uploads from untrusted users to prevent XSS attacks and HTTP leaks
- Use inline rendering when you need CSS/JavaScript manipulation of the SVG, but use img tag rendering for better performance and caching when interaction isn't needed
- The force_fill option is particularly useful for icons that should match text color - it sets fill='currentColor' on the SVG element
- Configure preview_image_max_width and preview_image_max_height in widget settings to ensure large SVGs don't overwhelm the edit form
- For Media integration, install the Media Library module before the SVG Image Field Media Bundle submodule to get the media_library form and view display configurations
- Alt text is recommended for accessibility - enable and require the alt field in field settings to ensure all SVG images have descriptive text
Technical Details
Troubleshooting 5
After updating to a version that renamed the media source class (SVG.php to ScalableVectorGraphic.php), Git or Composer may fail to apply the case-only rename. Delete any old SVG.php or Svg.php files from svg_image_field/src/Plugin/media/Source/ and ensure ScalableVectorGraphic.php exists. Alternatively, remove and re-require the module with Composer.
Check that the SVG file exists on the server. If using Stage File Proxy, the module will automatically fall back to img tag output when the file is missing locally. Also verify the SVG is valid XML with an svg root element.
Ensure the file has the correct MIME type (image/svg+xml or image/svg). Some servers may incorrectly detect SVG MIME types. The file must also be valid XML with an svg root element to pass validation.
SVGs may not display as thumbnails depending on your image processor and image style configuration. See Drupal issue #3105482 for more information. The actual SVG file is used as the thumbnail source.
Make sure the inline option is enabled in the formatter settings. Check that the SVG doesn't have hardcoded fill or style attributes that override your CSS. Use the force_fill option to set fill to currentColor.
Security Notes 4
- Inline SVG rendering can pose security risks as SVGs can contain JavaScript. Only enable inline rendering for fields where trusted users upload content, or always enable the sanitize option
- The sanitize option uses the enshrined/svg-sanitize library to strip potentially malicious code including scripts, event handlers, and other XSS vectors
- Enable sanitize_remote to remove references to external resources, preventing HTTP leaks that could expose user information or be used for tracking
- Standard img tag rendering (non-inline) is inherently safer as the SVG is loaded as an image resource rather than inline HTML