bmpr.js — BMP Renderer for HTML

A tiny HTML5 BMP renderer that lets you use .bmp images on the web — rendered directly in the browser using real BMP decoding.

Use it like an image:

<bmp-img src="image.bmp" alt="my bmp image"></bmp-img>

---

Features

• Custom HTML tag: <bmp-img>
• Real BMP decoding in JavaScript (no format conversion pipeline)
• Renders pixel-perfect output using <canvas>
• Works with CSS sizing (px, %, cm, etc.)
• Supports layout similar to <img>
• alt + accessibility support
• Emits load and error events
• Exposes naturalWidth, naturalHeight, complete, decode()
• No dependencies
• Single JS file

---

Installation

Download bmpr.js and include it in your HTML:

<script src="bmpr.js"></script>

---

Usage

Basic

<bmp-img src="image.bmp" alt="example"></bmp-img>

With size

<bmp-img src="image.bmp" width="300"></bmp-img>

Responsive

<bmp-img src="image.bmp" style="width:100%; height:auto;"></bmp-img>

---

Styling (Important)

<bmp-img> behaves like an image, but it is not literally <img>, so CSS selectors like img {} will NOT match it.

Use:

img, bmp-img {
  display: inline-block;
  vertical-align: bottom;
}

.badges :is(img, bmp-img) {
  width: 88px;
  height: 31px;
  image-rendering: pixelated;
}

---

Example Project Structure

project/
├── index.html
├── bmpr.js
└── image.bmp

---

Important

You must run a local server — opening files via file:// may not work due to browser security.

Example:

python -m http.server 8000

Then open:

http://localhost:8000

---

Supported BMP Formats

• 1-bit
• 4-bit
• 8-bit (palette)
• 24-bit
• 32-bit (with alpha)

Only uncompressed BMP is supported.

---

Not Supported (yet)

• RLE-compressed BMP
• srcset / sizes
• Native <img> behaviors like right-click save / drag image (canvas limitation)

---

Events

Works similar to <img>:

const img = document.querySelector("bmp-img");

img.addEventListener("load", () => {
  console.log("loaded");
});

img.addEventListener("error", () => {
  console.log("failed");
});

---

API

BMPR exposes some image-like properties:

img.naturalWidth
img.naturalHeight
img.complete
img.currentSrc

await img.decode();

---

How it works

• Fetches the .bmp file
• Parses BMP headers manually
• Decodes pixel data (palette / RGB / RGBA)
• Writes RGBA into an ImageData buffer
• Renders using <canvas>

This means:

The image is rendered directly from BMP data — not converted to PNG/JPEG.

---

Notes

• <bmp-img> is designed to behave as close as possible to <img>

• However, due to browser limitations:

  • it cannot be a true native <img> element
  • CSS must explicitly include bmp-img selectors

---

• A test index.html is included with an example BMP badge.

---

Author

Main developer: Szymon Grajner (SfymmiK) Organization: Lings

---

License

This project is licensed under the Apache License 2.0.

You are free to:

• use
• modify
• distribute
• use commercially

As long as you:

• include the license
• state changes made
• include a NOTICE file (if applicable)

See the LICENSE file for details.