Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/spatialillusions/milsymbol/llms.txt

Use this file to discover all available pages before exploring further.

Once a Symbol instance is created, its methods let you render the symbol in multiple formats, interrogate the decoded SIDC metadata, retrieve or update options, and validate the symbol code. All rendering methods reflect the current state of the symbol — calling setOptions before any render method gives you the updated output. Methods that return this can be chained directly.

​
Rendering Methods

​
asSVG()

Returns the symbol rendered as an SVG markup string. This is the lightest-weight rendering path and works in any environment (browser, Node.js, Deno). 
asSVG(): string
Returns
​
(return value)
string
A complete <svg> element as a string, ready to be injected into the DOM or written to a file.
const svg = new ms.Symbol("SFG-UCI----D", { size: 40 }).asSVG();
document.getElementById("map-icon").innerHTML = svg;

​
asCanvas(factor?)

Returns the symbol rendered onto an HTMLCanvasElement. An optional resolution factor multiplies the pixel dimensions of the canvas, which is useful for high-DPI (Retina) displays. 
asCanvas(factor?: number): HTMLCanvasElement
​
factor
number
Optional resolution multiplier. A value of 2 produces a canvas that is twice as wide and tall in pixels, giving a sharper image on HiDPI screens. Does not affect the values returned by getSize(), getAnchor(), or getOctagonAnchor().
Returns
​
(return value)
HTMLCanvasElement
A canvas element with the symbol painted onto it at the requested resolution.
factor scales the raw canvas pixel buffer only. The logical dimensions reported by getSize() and the anchor coordinates from getAnchor() / getOctagonAnchor() are always based on the unscaled size.
const canvas = new ms.Symbol("SFG-UCI----D", { size: 60 }).asCanvas(2);
document.getElementById("canvas-container").appendChild(canvas);

​
asDOM()

Returns the symbol as a live SVG Element in the browser’s DOM. Suitable for direct insertion into an HTML document or further DOM manipulation. 
asDOM(): Element
Returns
​
(return value)
Element
An SVG DOM element representing the symbol.
const svgElement = new ms.Symbol("SFG-UCI----D", { size: 40 }).asDOM();
document.getElementById("map-overlay").appendChild(svgElement);

​
asOffscreenCanvas(factor?)

Returns the symbol rendered onto an OffscreenCanvas. Intended for use in Web Workers, where HTMLCanvasElement is unavailable. 
asOffscreenCanvas(factor?: number): OffscreenCanvas
​
factor
number
Optional resolution multiplier — identical semantics to the factor parameter in asCanvas(). Does not affect the values returned by getSize(), getAnchor(), or getOctagonAnchor().
Returns
​
(return value)
OffscreenCanvas
An OffscreenCanvas with the symbol painted onto it.
// Inside a Web Worker
const offscreen = new ms.Symbol("SFG-UCI----D", { size: 60 }).asOffscreenCanvas(2);

​
toDataURL()

Returns the SVG of the symbol encoded as a Base64 data URL (data:image/svg+xml;base64,...). Useful for assigning the symbol as the src of an <img> element. 
toDataURL(): string
Returns
​
(return value)
string
A Base64-encoded SVG data URL string.
To get a PNG data URL instead, use the Canvas API:
const pngDataUrl = symbol.asCanvas().toDataURL("image/png");

const img = document.createElement("img");
img.src = new ms.Symbol("SFG-UCI----D", { size: 40 }).toDataURL();
document.body.appendChild(img);

​
Geometry & Size Methods

​
getAnchor()

Returns the anchor point — the position within the symbol image that should be pinned to the map coordinate. Measured in pixels from the top-left corner of the symbol bounding box. 
getAnchor(): { x: number; y: number }
Returns
​
(return value)
{ x: number; y: number }
const symbol = new ms.Symbol("SFG-UCI----D", { size: 40 });
const anchor = symbol.getAnchor();
console.log(anchor); // e.g. { x: 20, y: 40 }

​
getOctagonAnchor()

Returns the center of the symbol’s octagon (the core tactical symbol shape), measured in pixels from the top-left corner of the bounding box. Use this when you want to align two symbols by their octagon centers, rather than by the anchor pin point. 
getOctagonAnchor(): { x: number; y: number }
Returns
​
(return value)
{ x: number; y: number }
const symbol = new ms.Symbol("SFG-UCI----D", { size: 40 });
const center = symbol.getOctagonAnchor();
console.log(center); // e.g. { x: 20, y: 20 }

​
getSize()

Returns the pixel dimensions of the rendered symbol bounding box. The dimensions include all drawn parts: the frame, any modifiers, text labels, the direction arrow, and any extra padding. 
getSize(): { width: number; height: number }
Returns
​
(return value)
{ width: number; height: number }
getSize() always reflects the logical size regardless of the factor passed to asCanvas() or asOffscreenCanvas().
const symbol = new ms.Symbol("SFG-UCI----D", { size: 40 });
const { width, height } = symbol.getSize();
console.log(width, height); // e.g. 40 40

​
Color & Style Methods

​
getColors()

Returns the full set of resolved colors used to render the symbol, reflecting the current colorMode, fillColor, monoColor, and related style options. 
getColors(): SymbolColors
Returns
​
(return value)
SymbolColors
Each ColorMode object has the shape: 
type ColorMode = {
  Civilian: string;
  Friend:   string;
  Hostile:  string;
  Neutral:  string;
  Unknown:  string;
  Suspect:  string;
};

const symbol = new ms.Symbol("SFG-UCI----D", { size: 40, colorMode: "Dark" });
const colors = symbol.getColors();
console.log(colors.fillColor.Friend); // e.g. "#006BA6"
console.log(colors.frameColor.Hostile); // e.g. "#C70000"

​
Metadata Method

​
getMetadata()

Returns an object containing all metadata computed from the symbol’s SIDC. This is the primary way to introspect what milsymbol understood about the code — affiliation, dimension, echelon, special modifiers, and so on. 
getMetadata(): SymbolMetadata
Returns
​
(return value)
SymbolMetadata
const symbol = new ms.Symbol("SFG-UCI----D", { size: 40 });
const meta = symbol.getMetadata();

console.log(meta.affiliation);    // "Friend"
console.log(meta.dimension);      // "Ground"
console.log(meta.echelon);        // "Company/battery/troop"
console.log(meta.headquarters);   // false
console.log(meta.taskForce);      // false
console.log(meta.numberSIDC);     // false

​
Options Methods

​
getOptions(includeStyle?)

Returns the options currently set on the symbol. By default the returned object includes both modifier and style options. 
getOptions(includeStyle?: boolean): SymbolOptions
​
includeStyle
boolean
When true (or omitted), style options are included in the returned object. When false, only non-style options (e.g. SIDC, modifiers) are returned. Defaults to true.
Returns
​
(return value)
SymbolOptions
The current options object. See the Symbol Constructor for the full list of available option keys.
const symbol = new ms.Symbol("SFG-UCI----D", {
  size: 40,
  uniqueDesignation: "2-69 AR",
});

// Including style options (default)
const allOpts = symbol.getOptions();
console.log(allOpts.size);               // 40
console.log(allOpts.uniqueDesignation);  // "2-69 AR"

// Excluding style options
const modifiersOnly = symbol.getOptions(false);
console.log(modifiersOnly.size);         // undefined
console.log(modifiersOnly.uniqueDesignation); // "2-69 AR"

​
getStyle()

Returns only the style portion of the symbol’s current options. Equivalent to calling getOptions(true) and keeping only the style keys. 
getStyle(): SymbolOptions
Returns
​
(return value)
SymbolOptions
An object containing only the style-related options (e.g. size, fill, colorMode, outlineWidth, etc.).
const symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  colorMode: "Dark",
  outlineWidth: 2,
  uniqueDesignation: "2-69 AR",
});

const style = symbol.getStyle();
console.log(style.size);             // 60
console.log(style.colorMode);        // "Dark"
console.log(style.uniqueDesignation); // undefined — not a style option

​
setOptions(...args)

Updates the symbol’s options and triggers a full re-render. Accepts any number of options objects, merged in order — identical in semantics to passing multiple options objects to the constructor. A new SIDC can be supplied via the sidc property in any of the argument objects. Returns this, so calls can be chained. 
setOptions(opts: SymbolOptions): Symbol
​
opts
SymbolOptions
One or more options objects to merge into the current symbol options. Pass a sidc key to change the symbol code. All keys are optional — only the supplied keys are updated.
Returns
​
(return value)
Symbol
The symbol instance (this), enabling method chaining.
If you need to update many properties at once, batch them into a single setOptions call to avoid multiple re-renders.
const symbol = new ms.Symbol("SFG-UCI----D", { size: 40 });

// Update a single option
symbol.setOptions({ size: 60 });

// Update multiple options in one call (single re-render)
symbol.setOptions({ size: 80, colorMode: "Dark", outlineWidth: 2 });

// Change the SIDC
symbol.setOptions({ sidc: "SHGPUCIL---" });

// Chain with a render method
const svg = new ms.Symbol("SFG-UCI----D")
  .setOptions({ size: 40, fill: true })
  .setOptions({ uniqueDesignation: "2-69 AR" })
  .asSVG();

​
Validation Method

​
isValid(extended?)

Validates the symbol’s SIDC. Without an argument (or with extended set to false) returns a simple boolean indicating whether milsymbol was able to find an icon for the provided SIDC. With extended set to true, returns a detailed object describing the validity of individual SIDC parts. 
isValid(extended?: boolean): boolean | Object
​
extended
boolean
When false or omitted, returns a boolean — true if a valid icon was found for the SIDC, false otherwise. When true, returns an object describing the validity of each part of the SIDC code.
Returns
​
(return value)
boolean | Object
A boolean when extended is false or omitted; a validity detail object when extended is true.
const valid = new ms.Symbol("SFG-UCI----D").isValid();
console.log(valid); // true

const invalid = new ms.Symbol("INVALID-SIDC").isValid();
console.log(invalid); // false

// Extended validation — returns an object with per-part results
const detail = new ms.Symbol("SFG-UCI----D").isValid(true);
console.log(detail);
// e.g. { symbolSet: true, ... }

​
Method Chaining

Because setOptions returns this, you can build a fully configured symbol and render it in a single expression: 
const svg = new ms.Symbol("SFG-UCI----D")
  .setOptions({
    size: 60,
    colorMode: "Light",
    uniqueDesignation: "2-69 AR",
    higherFormation: "3ID",
    direction: 45,
  })
  .asSVG();

import ms, { SymbolOptions } from "milsymbol";

const opts: SymbolOptions = {
  size: 60,
  colorMode: "Medium",
  uniqueDesignation: "1-7 CAV",
  direction: 180,
};

const dataUrl: string = new ms.Symbol("SFG-UCI----D", opts).toDataURL();
const { width, height } = new ms.Symbol("SFG-UCI----D", opts).getSize();

Build docs developers (and LLMs) love

Get started for freeTalk to us