Styling Military Symbols in milsymbol

milsymbol provides extensive control over symbol appearance through its style options. You can produce filled or unfilled symbols, framed or unframed symbols, choose from built-in color modes or define your own, add outlines for map legibility, adjust sizes and padding, and fine-tune every text element. Style options can be mixed freely with modifier options and are passed through the same options object to the Symbol constructor or setOptions().

Fill, Frame, and Icon

Three boolean options independently control the three core visual layers of a symbol: the frame shape, the fill color inside the frame, and the icon drawn on top.

Option	Type	Default	Description
`fill`	Boolean	`true`	Fill the symbol frame with its affiliation color.
`frame`	Boolean	`true`	Draw the symbol frame shape.
`icon`	Boolean	`true`	Draw the symbol icon inside the frame.

All combinations are valid. Setting fill: false produces an unfilled (outline-only) symbol. Setting frame: false renders only the icon, useful for custom overlays. Setting all three to false produces a blank bounding box.

// Standard filled, framed symbol
var filled = new ms.Symbol("SFG-UCI----D", { size: 60 });

// Unfilled (outline only) — standard for anticipated/planned units
var unfilled = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  fill: false
});

// No frame, icon only
var iconOnly = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  frame: false
});

// Frame only, no icon
var frameOnly = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  icon: false
});

When fill is false, milsymbol automatically uses simplified dashed-line status modifiers. You can also force this behavior on filled symbols with simpleStatusModifier: true.

Size and Padding

`size`

The size option sets the L value — the width of the icon octagon in pixels. The default is 100, which makes the octagon 100 px wide. All other symbol dimensions (frame, text, staff lengths) scale proportionally.

// Small symbol for a dense map
var small = new ms.Symbol("SFG-UCI----D", { size: 20 });

// Large symbol for a presentation
var large = new ms.Symbol("SFG-UCI----D", { size: 120 });

`padding`

milsymbol normally fits the bounding box as tightly as possible around the symbol (including text modifiers). Use padding to add extra whitespace around the symbol when you need a consistent margin for map icons or icon arrays.

var padded = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  padding: 10   // 10-pixel padding on all sides
});

`square`

When square is true, the symbol is output as a square image with the insertion point at the center of the square. This simplifies placement in systems that expect square icons.

var square = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  square: true
});

Color Control

`colorMode`

The primary color control for the symbol. Pass a registered color mode name or a ColorMode object. milsymbol ships with the following built-in color modes:

Name	Description
`"Light"`	Light fill colors (default)
`"Medium"`	Medium fill colors
`"Dark"`	Dark fill colors
`"FrameColor"`	Frame colors for unfilled symbols
`"IconColor"`	Icon colors for unfilled/unframed symbols
`"Black"`	All black
`"White"`	All white
`"OffWhite"`	Off-white (used for white icon parts)
`"None"`	Transparent (turns colors off)

var lightSymbol = new ms.Symbol("SFG-UCI----D", { size: 60, colorMode: "Light" });
var darkSymbol  = new ms.Symbol("SFG-UCI----D", { size: 60, colorMode: "Dark"  });

// Using a custom ColorMode object
var customMode = ms.ColorMode(
  "rgb(150,0,150)",  // Civilian
  "rgb(0,0,200)",    // Friend
  "rgb(200,0,0)",    // Hostile
  "rgb(0,150,0)",    // Neutral
  "rgb(255,255,0)",  // Unknown
  "rgb(255,100,0)"   // Suspect
);
var custom = new ms.Symbol("SFG-UCI----D", { size: 60, colorMode: customMode });

You can also register a custom color mode globally so that all symbols can reference it by name:

ms.setColorMode("MyScheme", customMode);

var symbol = new ms.Symbol("SFG-UCI----D", { size: 60, colorMode: "MyScheme" });

`fillColor`

Directly override the fill color with any CSS color string, bypassing the color mode entirely. Useful for quick one-off customization.

var symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  fillColor: "#0077cc"
});

`fillOpacity`

Controls the opacity of the fill color (0 = transparent, 1 = fully opaque).

var symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  fillOpacity: 0.5   // semi-transparent fill
});

`monoColor`

Renders the symbol as monochrome and unfilled using a single color. Overrides color mode, fill, and icon colors.

// White monochrome — good for dark map backgrounds
var mono = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  monoColor: "white"
});

// Black monochrome
var monoBlack = new ms.Symbol("SHG-UCI----D", {
  size: 60,
  monoColor: "black"
});

Frame and Icon Colors

These options override the colors for individual visual layers, independently of the fill color mode.

`frameColor`

Override the color of the frame shape using a ColorMode object.

var symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  frameColor: ms.getColorMode("Black")
});

`iconColor`

Override the color of the icon using a ColorMode object or a CSS string.

var symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  iconColor: ms.getColorMode("White")
});

Outlines

Outlines improve legibility on complex map backgrounds by drawing a contrasting halo around all symbol parts. By default the outline is disabled (outlineWidth: 0).

`outlineWidth` and `outlineColor`

// White outline for symbols on dark maps
var outlined = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  outlineWidth: 4,
  outlineColor: "white"
});

// Black outline for symbols on light maps
var outlinedDark = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  outlineWidth: 3,
  outlineColor: "black",
  colorMode: "Light"
});

outlineColor defaults to rgb(239, 239, 239) (off-white) and accepts either a CSS color string or a ColorMode object.

Text Styling

These options control the appearance of text modifier fields rendered around the symbol.

Option	Type	Default	Description
`infoColor`	`ColorMode` or String	Same as frame outline	Color of the text modifier labels.
`infoBackground`	`ColorMode` or String	`''`	Background color behind text modifier groups.
`infoBackgroundFrame`	`ColorMode` or String	`''`	Stroke color for the border of text modifier backgrounds.
`infoOutlineColor`	String or `false`	`rgb(239, 239, 239)`	Outline color for text modifier labels. Pass `false` to inherit `outlineColor`.
`infoOutlineWidth`	Number or `false`	`false`	Outline width for text modifier labels. Pass `false` to inherit `outlineWidth`.
`infoSize`	Number	`40`	Label size as a percentage of the default symbol size (100).
`fontfamily`	String	`'Arial'`	Font family for all text modifier labels.

var styled = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  uniqueDesignation: "1-68 AR",
  higherFormation: "3ID",
  infoColor: "black",
  infoBackground: "rgba(255,255,255,0.7)",
  infoBackgroundFrame: "black",
  infoSize: 35,
  fontfamily: "Roboto, sans-serif",
  // Outline just the text labels
  infoOutlineWidth: 2,
  infoOutlineColor: "white"
});

Stroke Width

strokeWidth controls the stroke width for all symbol path elements (frame, icon, HQ staff, etc.). The default is 3.

var thin = new ms.Symbol("SFG-UCI----D", { size: 60, strokeWidth: 1 });
var thick = new ms.Symbol("SFG-UCI----D", { size: 60, strokeWidth: 5 });

Status Modifier

By default, milsymbol renders the standard status modifier for anticipated/planned/pending symbols using a dashed frame. Setting simpleStatusModifier: true forces simplified dashed-line indicators on filled symbols as well.

var simple = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  simpleStatusModifier: true
});

Stack

Display a unit stack to convey that multiple units occupy the same position. The stack number is the count of additional units shown behind the main symbol (0 = one unit total, 3 = four units total).

var stack = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  stack: 3   // four units stacked
});

HQ Staff Length

For headquarters symbols, the HQ staff extends below the symbol frame. Use hqStaffLength to override the global default for a specific symbol. To set the global default for all HQ symbols, use ms.setHqStaffLength(length).

// Override for one symbol
var hq = new ms.Symbol("SFG-UCIZ---D", {
  size: 60,
  hqStaffLength: 120   // longer staff
});

// Set global default for all HQ symbols
ms.setHqStaffLength(100);

Standard

The standard option overrides the global standard (set with ms.setStandard()) for a single symbol. Use "2525" for MIL-STD-2525 rendering and "APP6" for STANAG APP-6 rendering. Where the two standards differ, this option selects which version to use.

// Global default
ms.setStandard("2525");

// Override one symbol to use APP-6
var app6Symbol = new ms.Symbol("SFG-UCI----D", {
  size: 60,
  standard: "APP6"
});

Alternate MEDAL

For mine warfare symbols, MIL-STD-2525D defines both MEDAL and alternate MEDAL icons. milsymbol uses MEDAL icons by default. Set alternateMedal: true to switch to the alternate version.

var altMine = new ms.Symbol("SFWM---------", {
  size: 60,
  alternateMedal: true
});

Get Started

Core Concepts

Guides

Integrations

Styling Military Symbols in milsymbol

Fill, Frame, and Icon

Size and Padding

`size`

`padding`

`square`

Color Control

`colorMode`

`fillColor`

`fillOpacity`

`monoColor`

Frame and Icon Colors

`frameColor`

`iconColor`

Outlines

`outlineWidth` and `outlineColor`

Text Styling

Stroke Width

Status Modifier

Stack

HQ Staff Length

Standard

Alternate MEDAL

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Documentation Index

​Fill, Frame, and Icon

​Size and Padding

​size

​padding

​square

​Color Control

​colorMode

​fillColor

​fillOpacity

​monoColor

​Frame and Icon Colors

​frameColor

​iconColor

​Outlines

​outlineWidth and outlineColor

​Text Styling

​Stroke Width

​Status Modifier

​Stack

​HQ Staff Length

​Standard

​Alternate MEDAL

Build docs developers (and LLMs) love

Fill, Frame, and Icon

Size and Padding

`size`

`padding`

`square`

Color Control

`colorMode`

`fillColor`

`fillOpacity`

`monoColor`

Frame and Icon Colors

`frameColor`

`iconColor`

Outlines

`outlineWidth` and `outlineColor`

Text Styling

Stroke Width

Status Modifier

Stack

HQ Staff Length

Standard

Alternate MEDAL