REFERENCE · COMPLETE CONTRACT
API Reference & URL Patterns
The canonical reference for each supported asset family, quality value, URL pattern and JavaScript helper.
Asset URL matrix
| Type | Quality values | Default | Path format | ID casing |
|---|---|---|---|---|
emoji | svg, png | svg | /emojis/svg/{unicode}.svg/emojis/72x72/{unicode}.png | lowercase hex |
flag | s, m, l | m | /flag/{quality}/{CODE}.svg | UPPERCASE |
flags | 1x1, 4x3 | 4x3 | /flags/{quality}/{code}.svg | lowercase |
Emoji endpoints
Emoji IDs use lowercase hexadecimal Unicode code points. Multi-code-point sequences are joined with hyphens.
SVG https://softhoursdiary-emojis.pages.dev/[emojis/svg/1f632.svg
PNG https://softhoursdiary-emojis.pages.dev/[emojis/72x72/1f632.pngSVG is the recommended default for scalable UI. PNG is useful when a raster image is required.
Flag SVG endpoints
Small https://softhoursdiary-emojis.pages.dev/[flag/s/IN.svg
Medium https://softhoursdiary-emojis.pages.dev/[flag/m/IN.svg
Large https://softhoursdiary-emojis.pages.dev/[flag/l/IN.svgThe legacy flag collection uses uppercase country or region codes.
Flag icon endpoints
Square https://softhoursdiary-emojis.pages.dev/[flags/1x1/in.svg
Landscape https://softhoursdiary-emojis.pages.dev/[flags/4x3/in.svgThe flag icon collection uses lowercase country or region codes.
JavaScript methods
| Method | Purpose | Returns |
|---|---|---|
getUrl(options) | Build any supported asset URL. | string |
emojiUrl(id, options?) | Emoji SVG or PNG URL. | string |
flagUrl(id, options?) | Small, medium or large flag SVG. | string |
flagIconUrl(id, options?) | Square or 4:3 flag icon. | string |
createImage(options) | Create an HTMLImageElement. | HTMLImageElement |
mount(target, options) | Set an image or append one to a container. | HTMLImageElement |
scan(scope?) | Process data-shd elements in a DOM scope. | number |
createReactComponents(React) | Create React components. | component set |
registerElements() | Register custom elements. | true |
Validation rules
- Emoji quality must be svg or png.
- Flag quality must be s, m or l.
- Flag icon quality must be 1x1 or 4x3.
- Flag IDs use 2–12 letters, digits or hyphens and are case-normalised.
- Emoji IDs accept hex strings or literal Unicode characters.
- Optional baseUrl must be an absolute HTTP(S) URL.
Request and file availability
URL generation is local; it does not check the network or confirm that a file exists. A valid URL may still return 404. Use the explorers or playground to check a particular file.