JavaScript API Reference

Load the library

<script defer src="https://softhoursdiary-emojis.pages.dev/soft-hours-diary.js"></script>

In browser code, the public global is window.SoftHoursDiary. The same UMD file supports CommonJS when used locally.

getUrl(options)

Use getUrl for all asset families. Its options are type, quality, id and optional baseUrl.

const SHD = window.SoftHoursDiary;

const emoji = SHD.getUrl({
  type: "emoji",
  quality: "svg",
  id: "1f632"
});

const flag = SHD.getUrl({
  type: "flag",
  quality: "l",
  id: "IN"
});

const flagIcon = SHD.getUrl({
  type: "flags",
  quality: "4x3",
  id: "IN"
});

Convenience URL helpers

These methods default to SVG emoji, medium flag SVG and 4:3 flag icons.

SHD.emojiUrl("1f632");
SHD.emojiUrl("1f632", { quality: "png" });

SHD.flagUrl("IN", { quality: "s" });
SHD.flagUrl("IN", { quality: "m" });
SHD.flagUrl("IN", { quality: "l" });

SHD.flagIconUrl("IN", { quality: "1x1" });
SHD.flagIconUrl("IN", { quality: "4x3" });

Each method returns a URL string without making a network request.

createImage(options)

Create an HTMLImageElement with common image attributes. Lazy loading and async decoding are the defaults.

const image = SHD.createImage({
  type: "emoji",
  id: "1f632",
  quality: "svg",
  alt: "Surprised face",
  width: 36,
  height: 36,
  loading: "lazy",
  decoding: "async",
  className: "reaction-emoji"
});

document.querySelector("#reactions").append(image);

mount(target, options)

mount accepts a CSS selector or DOM element. It updates an existing image or appends a new image to the target container.

SHD.mount("#india-flag", {
  type: "flag",
  id: "IN",
  quality: "l",
  alt: "Flag of India",
  width: 48,
  height: 32
});

scan(scope?) and data attributes

scan processes elements with data-shd-type and data-shd-id. It returns the count of processed nodes. Invalid nodes receive a data-shd-error attribute.

<img data-shd-type="emoji" data-shd-id="1f632"
  data-shd-quality="svg" alt="Surprised face"
  width="32" height="32" />

<div data-shd-type="flag" data-shd-id="IN"
  data-shd-quality="l"></div>

const processedCount = SHD.scan();
console.log("Resolved nodes:", processedCount);

Custom elements

The browser bundle registers shd-asset, shd-emoji, shd-flag and shd-flag-icon.

<shd-asset type="emoji" asset-id="1f632"
  quality="svg" alt="Surprised face"></shd-asset>

<shd-emoji asset-id="1f632" quality="svg"
  alt="Surprised face"></shd-emoji>

<shd-flag asset-id="IN" quality="l"
  alt="Flag of India"></shd-flag>

Use asset-id for the CDN identifier. The regular HTML id attribute remains available for your own selectors.

Validation and errors

Unsupported types, invalid quality combinations, malformed IDs and invalid base URLs throw descriptive TypeError or RangeError exceptions.

try {
  const src = SHD.getUrl({
    type: "flag",
    quality: "l",
    id: "IN"
  });
  console.log(src);
} catch (error) {
  console.error("Invalid asset options:", error.message);
}

A valid URL may still point to a file that does not exist. File availability is checked by the browser when it requests the asset.