Skip to main content

How to Use a Base64 Encoded Image as background-image in JavaScript

Using Base64-encoded images as Data URLs is a powerful technique for embedding images directly into your CSS or JavaScript, eliminating the need for an extra HTTP request. This is especially useful for small, critical images like icons or background patterns.

This guide will teach you the two primary methods for setting an element's background-image to a Base64-encoded image: directly via JavaScript's inline style property, and the more maintainable approach of toggling a CSS class.

What is a Data URL?​

A Data URL is a URI scheme that allows you to embed small files inline in documents. For a Base64-encoded image, it follows a specific format.

Format: data:[<mediatype>];base64,[<data>] Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

The browser can interpret this string directly as an image, just as it would a normal URL like https://example.com/image.png.

Method 1: Setting the Inline style Property​

This is the most direct way to apply a Base64 image to a single element's background using JavaScript.

Problem: you have a div and you want to programmatically set its background to a Base64-encoded image.

<div id="my-box" style="width: 150px; height: 150px;"></div>

Solution: you set the backgroundImage property on the element's style object, wrapping the Data URL in the url() CSS function.

// The Base64 string for a tiny red dot PNG
let dataURL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==';

let box = document.getElementById('my-box');

// Use a template literal to construct the CSS value.
box.style.backgroundImage = `url('${dataURL}')`;
note

After this code runs, the div will have the tiny red dot as its repeating background image. This method is effective for dynamic, one-off style changes.

For better separation of concerns and more maintainable code, the recommended best practice is to define the background image in a CSS class and then use JavaScript to simply add or remove that class from the element.

Problem: you want to apply a Base64 background, but you want to keep your styles in your CSS and your logic in your JavaScript.

Solution: 1. Define the class in your CSS:

/* style.css */
.has-red-dot-background {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==');
}

2. Add the class with JavaScript:

let box = document.getElementById('my-box');

// Add the class to apply the background.
box.classList.add('has-red-dot-background');

This approach is superior because:

  • Maintainability: Your styles are kept in your stylesheet, not hardcoded in your JavaScript.
  • Reusability: You can apply the .has-red-dot-background class to any element.
  • Simplicity: Toggling the background is as easy as box.classList.toggle('has-red-dot-background').

How the Data URL Syntax Works​

The url() function in CSS is what allows the browser to interpret the Data URL string as an image source.

background-image: url('data:image/png;base64,iVBORw0K...')

where:

  • url(...): The CSS function that specifies a URL for a resource.
  • data:: The scheme, indicating that the content is embedded directly.
  • image/png: The MIME type of the data. This is crucial. It tells the browser how to interpret the data (e.g., as a PNG, a GIF, a JPEG, etc.).
  • ;base64: The encoding used for the data.
  • ,: The separator between the metadata and the actual data.
  • iVBORw0K...: The Base64-encoded string itself.

If your Base64 string is missing the data:image/png;base64, prefix, you must add it for the browser to understand it.

let base64Data = 'iVBORw0KGgoAAAANSUhEUg...';
let prefix = 'data:image/png;base64,';
let dataURL = prefix + base64Data; // Construct the full Data URL

Conclusion​

Using Base64-encoded images for backgrounds is a powerful technique for embedding small assets directly into your code.

  • For dynamic or one-off applications, setting the element.style.backgroundImage property directly in JavaScript is a quick and effective solution.
  • For better maintainability, reusability, and separation of concerns, the recommended best practice is to define the background in a CSS class and use JavaScript's classList API (.add(), .remove(), .toggle()) to apply it.

Table of Contents