JavaScript Document mozSetImageElement() Method

What You’ll Learn

document.mozSetImageElement() is a Non-standard instance method that overrides which element backs a CSS -moz-element(#id) background (see MDN Document: mozSetImageElement()). Learn the MDN canvas click demo, how to clear with null, and safer cross-browser alternatives.

Introduction

Firefox can paint one element as another’s CSS background using background-image: -moz-element(#some-id). Normally that ID points at a real element in the page.

MDN: mozSetImageElement(imageElementId, imageElement) changes the element used for that background ID — even to a detached <canvas> you just created. Pass null to remove the override.

Related tutorials: createElement(), getElementById(), moveBefore().

Understanding document.mozSetImageElement()

An instance method on Document (MDN). It is Mozilla-prefixed and not standardized.

• imageElementId — string name used with -moz-element() (MDN).
• imageElement — the Element to use as that background, or null to clear (MDN).
• Returns — undefined (MDN).
• Pairs with CSS — only affects backgrounds that reference that ID via -moz-element() (MDN).
• Detached OK — MDN example uses a newly created canvas that is not in the tree.
• Spec — not part of any specification (MDN).

📝 Syntax

General form of Document.mozSetImageElement (MDN):

mozSetImageElement(imageElementId, imageElement)

Parameters

• imageElementId — a string indicating the name of an element specified as a background image using the -moz-element CSS function (MDN).
• imageElement — the new element to use as the background for that ID. Specify null to remove the background element (MDN).

Return value

None (undefined) (MDN).

CSS companion

#my-box {
  background-image: -moz-element(#canvas-bg);
  text-align: center;
  width: 400px;
  height: 400px;
  cursor: pointer;
}

MDN quick sample

let c = 0x00;
function clicked() {
  const canvas = document.createElement("canvas");
  canvas.setAttribute("width", 100);
  canvas.setAttribute("height", 100);

  const ctx = canvas.getContext("2d");
  ctx.fillStyle = `#${c.toString(16)}0000`;
  ctx.fillRect(25, 25, 75, 75);

  c += 0x11;
  if (c > 0xff) {
    c = 0x00;
  }

  document.mozSetImageElement("canvas-bg", canvas);
}

⚖️ mozSetImageElement vs standard backgrounds

Examples Gallery

Examples follow MDN Document: mozSetImageElement(). Open try-it labs in Firefox to see the live background effect.

let c = 0x00;
function clicked() {
  if (typeof document.mozSetImageElement !== "function") {
    console.log("mozSetImageElement unsupported");
    return;
  }

  const canvas = document.createElement("canvas");
  canvas.width = 100;
  canvas.height = 100;

  const ctx = canvas.getContext("2d");
  ctx.fillStyle = `#${c.toString(16)}0000`;
  ctx.fillRect(25, 25, 75, 75);

  c += 0x11;
  if (c > 0xff) c = 0x00;

  document.mozSetImageElement("canvas-bg", canvas);
}

In Firefox: #my-box background updates each click
Elsewhere: unsupported message

const supported = typeof document.mozSetImageElement === "function";
console.log("mozSetImageElement supported:", supported);

if (!supported) {
  console.log("Use a standard background-image fallback");
}

mozSetImageElement supported: false
(or true in Firefox)

function setBg(el) {
  if (typeof document.mozSetImageElement !== "function") return;
  document.mozSetImageElement("canvas-bg", el);
}

function clearBg() {
  if (typeof document.mozSetImageElement !== "function") return;
  document.mozSetImageElement("canvas-bg", null);
}

// setBg(myCanvas); clearBg();

Override cleared (Firefox) or no-op when unsupported

function paintBoxBackground(box, canvas) {
  if (typeof document.mozSetImageElement === "function") {
    document.mozSetImageElement("canvas-bg", canvas);
    return "used mozSetImageElement";
  }
  box.style.backgroundImage = "url(" + canvas.toDataURL("image/png") + ")";
  return "used canvas.toDataURL fallback";
}

used canvas.toDataURL fallback
(or mozSetImageElement in Firefox)

const box = document.getElementById("my-box");
let c = 0x00;

box.addEventListener("click", () => {
  const canvas = document.createElement("canvas");
  canvas.width = 100;
  canvas.height = 100;
  const ctx = canvas.getContext("2d");
  ctx.fillStyle = `#${c.toString(16).padStart(2, "0")}0000`;
  ctx.fillRect(25, 25, 50, 50);
  c = (c + 0x11) % 0x100;

  if (typeof document.mozSetImageElement === "function") {
    document.mozSetImageElement("canvas-bg", canvas);
  } else {
    box.style.backgroundImage = `url(${canvas.toDataURL()})`;
  }
});

Box background updates on each click

🚀 Common Use Cases

• Firefox demos — live element / canvas as CSS background (MDN).
• Legacy literacy — recognize moz* prefixed Document APIs.
• Dynamic tile patterns — regenerate a canvas and override the ID (MDN).
• Not for production sites — MDN advises against non-standard features.
• Progressive enhancement — optional Firefox path + standard fallback.
• Clearing overrides — pass null when done (MDN).

📝 Notes

• MDN: marked Non-standard — not part of any specification.
• Not Deprecated or Experimental on MDN, but still unsuitable for production dependency.
• Requires matching CSS -moz-element(#id) to show an effect.
• Firefox 4+; not supported in Chrome, Safari, Edge, Opera, or IE.
• Pass null to remove an override (MDN).
• Related: createElement(), getElementById(), moveBefore().

💡 Best Practices