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.

The Symbol class is the core of milsymbol. Each instance represents a single military unit symbol generated from a SIDC (Symbol Identification Code) according to MIL-STD-2525 or STANAG APP-6. Once created, a symbol object can render itself to SVG, Canvas, or DOM, and can expose rich metadata about the decoded SIDC.

​
Constructor Signature

new ms.Symbol(code: string | SymbolOptions, ...options: SymbolOptions[]): Symbol
The first argument can be a SIDC string or an options object (in which case the SIDC must be supplied via the sidc property). All subsequent arguments are additional options objects that are merged in order. 
// SIDC as first argument
const symbol = new ms.Symbol("SFG-UCI----D", { size: 30 });

// SIDC inside an options object
const symbol = new ms.Symbol({ sidc: "SFG-UCI----D", size: 30 });

// Multiple options objects — all merged left to right
const symbol = new ms.Symbol("SFG-UCI----D", { size: 30 }, { frame: true, fill: true });

​
How Options Work

Options can be spread across any number of arguments or collected into a single object — the result is identical. Every time options are updated (via setOptions) the symbol is automatically re-rendered.
Pass all options at construction time for the best performance. Every call to setOptions triggers a full re-render. If you have no options at all, passing an empty object is also fast — it is only incremental updates that carry a re-render cost.
Methods can be chained directly off construction: 
const svgString = new ms.Symbol("SFG-UCI----D", { size: 30 }).asSVG();

​
General Options

​
sidc
string
The SIDC (Symbol Identification Code) for the symbol. Can also be passed as the first positional argument to the constructor instead of inside an options object. Defaults to ''.

​
Modifier Options

Modifiers are text or graphical additions defined in MIL-STD-2525 and STANAG APP-6. They appear as labels or decorations around the symbol frame.
​
additionalInformation
string
A text modifier for units, equipment, and installations; content is implementation specific. Corresponds to Field H (max 20 characters). Defaults to ''.
​
altitudeDepth
string
A text modifier for units, equipment, and installations that displays either altitude flight level, depth for submerged objects, or height of equipment or structures on the ground. Corresponds to Field X (max 14 characters). Defaults to ''.
​
auxiliaryEquipmentIndicator
string
Auxiliary equipment indicator modifier. Defaults to ''.
​
combatEffectiveness
string
A text modifier for units and installations that indicates unit effectiveness or installation capability. Corresponds to Field K (max 5 characters). Defaults to ''.
​
commonIdentifier
string
Common name for the equipment. Example: "Hawk" for the Hawk SAM system. Corresponds to Field AF. Defaults to ''.
​
country
string
Three-letter code representing the country of origin. Corresponds to Field AC. Defaults to ''.
​
direction
number
Direction of movement or orientation in degrees (not mils). Set to undefined to remove the direction arrow entirely. Corresponds to Field Q. Defaults to undefined.
​
dtg
string
A text modifier for units, equipment, and installations that displays a date-time group in the format DDHHMMSSZMONYYYY, or "O/O" for on order. Corresponds to Field W (max 16 characters). Defaults to ''.
​
engagementBar
string
Engagement bar text. Shall be formatted as A:BBB-CC. Corresponds to Field AO. Defaults to ''.
​
engagementType
string
Engagement bar type. Should be one of "TARGET", "NON-TARGET", or "EXPIRED". Defaults to ''.
​
equipmentTeardownTime
string
Equipment teardown time in minutes. Corresponds to Field AE. Defaults to ''.
​
evaluationRating
string
A text modifier consisting of a one-letter reliability rating and a one-number credibility rating. Corresponds to Field J (max 2 characters). Defaults to ''.
​
guardedUnit
string
During ballistic missile defence, identifies the unit guarding a particular track. Corresponds to Field AQ (max 2 characters). Defaults to ''.
​
headquartersElement
string
Name of the headquarters element. Example: 'TOC' for Tactical Operations Centre. Corresponds to Field AH. Defaults to ''.
​
higherFormation
string
A text modifier for units indicating the number or title of the higher echelon command (corps are designated by Roman numerals). Corresponds to Field M (max 21 characters). Defaults to ''.
​
hostile
string
A text modifier for equipment; the letters "ENY" denote hostile symbols. Corresponds to Field N (max 3 characters). Defaults to ''.
​
iffSif
string
A text modifier displaying IFF/SIF identification modes and codes. Corresponds to Field P (max 5 characters). Defaults to ''.
​
installationComposition
string
Composition of installation modifier. Defaults to ''.
​
location
string
A text modifier for units, equipment, and installations that displays the symbol’s location in degrees, minutes, and seconds (or UTM or other applicable display format). Corresponds to Field Y (max 19 characters). Defaults to ''.
​
platformType
string
Platform type identifier. Should be "ELNOT" or "CENOT". Corresponds to Field AD. Defaults to ''.
​
quantity
string
A text modifier in an equipment symbol that identifies the number of items present. Corresponds to Field C or Field R (max 9 characters). Defaults to ''.
​
reinforcedReduced
string
A text modifier in a unit symbol that displays (+) for reinforced, (-) for reduced, or (±) for reinforced and reduced. Corresponds to Field F (max 3 characters). Defaults to ''.
​
sigint
string
SIGINT mobility indicator. Accepted values: M = Mobile, S = Static, U = Uncertain. Corresponds to Field R2. Defaults to ''.
​
signatureEquipment
string
A text modifier for hostile equipment; "!" indicates detectable electronic signatures. Corresponds to Field L (max 1 character). Defaults to ''.
​
specialDesignator
string
Special track designators such as Non-Real Time (NRT) or Tactically Significant (SIG). Corresponds to Field AR (max 3 characters). Defaults to ''.
​
specialHeadquarters
string
A text modifier for units rendered inside the frame; contains the name of a special C2 Headquarters. Corresponds to Field AA (max 9 characters). Defaults to ''.
​
speed
string
A text modifier for units and equipment that displays velocity as set forth in MIL-STD-6040. Corresponds to Field Z (max 8 characters). Defaults to ''.
​
speedLeader
number
The length of the speed leader line in pixels. This value is independent of the symbol size. Defaults to 0.
​
staffComments
string
A text modifier for units, equipment, and installations; content is implementation specific. Corresponds to Field G (max 20 characters). Defaults to ''.
​
type
string
A text modifier for equipment indicating equipment type. Corresponds to Field V (max 24 characters). Defaults to ''.
​
uniqueDesignation
string
A text modifier for units, equipment, and installations that uniquely identifies a particular symbol or track number. Also identifies acquisition number when used with SIGINT symbology. Corresponds to Field T (max 21 characters). Defaults to ''.

​
Style Options

Style options control the visual rendering of the symbol — colors, size, frame, fill, and text appearance.
​
alternateMedal
boolean
MIL-STD-2525D provides both MEDAL and alternate MEDAL icons for mine warfare symbols. Set to true to use the alternate MEDAL icons. Defaults to false.
​
civilianColor
boolean
MIL-STD-2525C specifies purple as an optional color for civilian symbols. Set to false to disable civilian purple coloring. Defaults to true.
​
colorMode
ColorMode | string
The color mode used for symbol fill. Can be set to a ColorMode object or a string name of a registered color mode. The built-in registered modes are "Light", "Medium", and "Dark". Use ms.ColorMode() to create a new mode or ms.getColorMode() to retrieve an existing one.
The string value is the name of a registered color mode — not a raw color value. Passing an unregistered name will fall back to the default behavior.
Defaults to 'Light'.
​
fill
boolean
Whether the symbol should be filled with color. Set to false for an outlined/unfilled symbol. Defaults to true.
​
fillColor
string
Overrides the affiliation-derived fill color with any valid CSS color string. When set, colorMode is ignored for the fill. Defaults to ''.
​
fillOpacity
number
The opacity of the symbol fill color, from 0 (transparent) to 1 (opaque). Defaults to 1.
​
fontfamily
string
The font family used for all text labels surrounding the symbol icon. Defaults to 'Arial'.
​
frame
boolean
Whether the symbol should have a frame. All symbols support being unframed, not just those specified in MIL-STD-2525B. Defaults to true.
​
frameColor
ColorMode
Overrides the color of the symbol frame with a ColorMode object. When set to false (the default), the frame color is derived from the affiliation and colorMode. Defaults to false.
​
hqStaffLength
number
Overrides the global headquarters staff length for this symbol instance. When omitted the global value set by ms.setHqStaffLength() is used. Defaults to undefined.
​
icon
boolean
Whether the symbol should render its function icon inside the frame. Set to false to display the frame only. Defaults to true.
​
iconColor
ColorMode | string
Overrides the color of the symbol’s icon. Accepts a ColorMode object or a CSS color string. When set to false (the default), the icon color is derived automatically. Defaults to false.
​
infoBackground
ColorMode | string
Sets the background color of the information (text label) area. Accepts a ColorMode object or a CSS color string. Defaults to ''.
​
infoBackgroundFrame
ColorMode | string
Sets the frame color of the information (text label) background area. Accepts a ColorMode object or a CSS color string. Defaults to ''.
​
infoColor
ColorMode | string
The color used for text fields surrounding the symbol. Accepts a ColorMode object or a CSS color keyword / numerical RGB specification. Defaults to the same color as the frame outline.
​
infoFields
boolean
Set to false to suppress rendering of all text modifier fields and the direction arrow, even if they have been populated. This lets you initialise a symbol with full data but hide the labels. Defaults to true.
​
infoOutlineColor
string
The color of the outline drawn around text fields. Set to false to inherit the value of outlineColor. Defaults to 'rgb(239, 239, 239)'.
​
infoOutlineWidth
number
The width in pixels of the outline drawn around text fields. Set to false to inherit the value of outlineWidth. Defaults to false.
​
infoSize
number
The relative size of text label fields. The value is a percentage of the default symbol size of 100. For example, 40 means 40% of the octagon width. Defaults to 40.
​
monoColor
string
A CSS color keyword or numerical RGB specification. When set, the symbol is rendered in monochrome using this color without any fill. Overrides colorMode, fillColor, and other color options. Defaults to ''.
​
outlineColor
ColorMode | string
The color of the outline drawn around all symbol parts. Accepts a ColorMode object or a CSS color keyword / numerical RGB specification. Defaults to 'rgb(239, 239, 239)'.
​
outlineWidth
number
The width in pixels of the outline drawn around all symbol parts. Set to 0 to disable the outline. Defaults to 0.
​
padding
number
Extra padding in pixels to add around the tightly-fitted symbol bounding box. Useful when placing symbols in contexts that clip at the bounding edge. Defaults to 0.
​
size
number
The L value — the width of the icon octagon in pixels. All other symbol dimensions scale proportionally to this value. Defaults to 100.
​
simpleStatusModifier
boolean
Forces the use of simplified status modifiers. This is the automatic default for unfilled symbols, but can be explicitly applied to filled symbols as well. Defaults to false.
​
square
boolean
When true, renders the symbol as a square with the insertion point at the center. Defaults to false.
​
stack
number
Renders the symbol as a stack of unit symbols. The value indicates the number of additional units displayed behind the main symbol. For example, 0 renders one unit, 3 renders four units in total. Defaults to 0.
​
standard
string
Per-symbol override of the global preferred standard. Set to "2525" for MIL-STD-2525 or "APP6" for STANAG APP-6. When omitted the global standard set by ms.setStandard() is used. Defaults to ''.
​
strokeWidth
number
The stroke width used when drawing the symbol outline and frame. Defaults to 3.

​
Example

The following example creates a friendly ground unit symbol with a full set of modifiers and custom style options: 
import ms from "milsymbol";

const symbol = new ms.Symbol("SFG-UCI----D", {
  // Style
  size: 60,
  colorMode: "Medium",
  fill: true,
  frame: true,
  outlineWidth: 2,
  outlineColor: "rgb(0, 0, 0)",
  infoSize: 45,
  fontfamily: "Arial",
  padding: 4,

  // Modifiers
  uniqueDesignation: "2-69 AR",
  higherFormation: "3ID",
  quantity: "12",
  speed: "015KPH",
  direction: 90,
  dtg: "011800ZJAN2025",
  staffComments: "OPCON 3ID",
  additionalInformation: "C2",
});

// Render as SVG string
document.getElementById("symbol-container").innerHTML = symbol.asSVG();

// Render as Canvas element
document.getElementById("canvas-container").appendChild(
  symbol.asCanvas(2) // 2× resolution for HiDPI screens
);

import ms, { SymbolOptions } from "milsymbol";

const opts: SymbolOptions = {
  size: 60,
  colorMode: "Light",
  uniqueDesignation: "2-69 AR",
  higherFormation: "3ID",
  direction: 90,
};

const symbol = new ms.Symbol("SFG-UCI----D", opts);
console.log(symbol.isValid()); // true

Build docs developers (and LLMs) love

Get started for freeTalk to us