react-leaflet-milsymbol

A React Leaflet integration for the milsymbol library, allowing you to easily add military symbols to your React Leaflet maps. Works with react-leaflet v4 and v5.

Live Demo

Installation

npm install react-leaflet-milsymbol
# or
yarn add react-leaflet-milsymbol
# or
pnpm add react-leaflet-milsymbol

[!IMPORTANT] If using React 19, install react-leaflet v5 — v4 supports React ^18.0.0 only.

Dependencies

This package requires the following peer dependencies:

• react (v18.0.0 or v19.0.0)
• react-dom (v18.0.0 or v19.0.0)
• leaflet (v1.9.0 or higher)
• react-leaflet (v4 or v5 — use v5 with React 19)
• milsymbol (v3.0.0 or higher)

Make sure to install these dependencies in your project if you haven't already.

Getting a SIDC

A SIDC (Symbol Identification Code) is the string that tells milsymbol which military symbol to draw — affiliation (friendly, hostile, …), domain (ground, air, sea), and what the unit actually is. It is the only required prop besides position, and it is the one thing you can't guess.

Two ways to get one:

1. Build it interactively — SIDC Builder (APP-6) lets you pick affiliation and unit type from dropdowns and copies out the code.
2. Copy one from the table below and change a single character to adjust it.

[!TIP] If a symbol renders as an empty box or doesn't appear at all, the SIDC is probably invalid. This library logs a console.warn naming the bad code when that happens.

Common SIDCs

Every code below is verified valid against milsymbol@3.

| Symbol | Letter-based (APP-6B/C) | Numeric (APP-6D) | | ------ | ----------------------- | ---------------- | | Friendly infantry | SFGPUCI----D | 10031000141211000000 | | Hostile infantry | SHGPUCI----D | 10061000141211000000 | | Neutral infantry | SNGPUCI----D | 10041000141211000000 | | Unknown infantry | SUGPUCI----D | 10011000141211000000 | | Friendly armor | SFGPUCA----D | — | | Friendly field artillery | SFGPUCF----D | — | | Friendly air defense | SFGPUCD----D | — | | Friendly headquarters | SFGPUH-----D | — | | Friendly fixed-wing aircraft | SFAPMFF---- | 10030100001101000000 | | Friendly rotary-wing aircraft | SFAPMHR---- | — | | Friendly surface combatant | SFSPCLBB--- | 10033000001201000000 |

Changing affiliation in a letter-based code is the 2nd character: F friendly (blue), H hostile (red), N neutral (green), U unknown (yellow). So SFGPUCI----D → SHGPUCI----D turns friendly infantry into hostile infantry.

SIDC Formats

The sidc prop accepts Symbol Identification Codes in both letter-based (APP-6B/C) and numeric (APP-6D) formats. Both are passed directly to milsymbol.

| Format | Length | Example | Description | | ------ | ------ | ------- | ----------- | | Letter-based (APP-6B/C) | 12–15 characters | SFGPEWRH--MT | Traditional format using letters to encode affiliation, dimension, function, etc. | | Numeric (APP-6D) | 20 digits | 10031000001211000000 | Newer standard using numeric fields for symbol set, entity, and modifiers |

For more details on constructing SIDCs, see the milsymbol documentation.

Usage

[!WARNING] Breaking change in 0.3.0 — the size prop now takes precedence over options.size. If you passed both, the symbol previously rendered at options.size and now renders at size. Passing only one of them is unaffected.

Basic Example (Letter-based SIDC)

import { MapContainer, TileLayer } from 'react-leaflet';
import { MilSymbol } from 'react-leaflet-milsymbol';

function MyMap() {
  return (
    <MapContainer center={[51.505, -0.09]} zoom={13} style={{ height: '500px', width: '100%' }}>
      <TileLayer
        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
        attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
      />

      <MilSymbol
        position={[51.505, -0.09]}
        sidc="SFGPEWRH--MT"
        options={{
          size: 35,
          fill: true,
          fillOpacity: 0.5,
        }}
      />
    </MapContainer>
  );
}

Basic Example (Numeric SIDC)

<MilSymbol
  position={[51.505, -0.09]}
  sidc="10031000001211000000"
  options={{ size: 35 }}
/>

Props

The MilSymbol component accepts the following props:

| Prop | Type | Description | | ---------------- | ----------------------- | -------------------------------------------------------- | | position | [number, number] | Latitude and longitude where the symbol should be placed | | sidc | string | Symbol Identification Code (letter-based or numeric) | | size | number | Size of the symbol (default: 35). Takes precedence over options.size | | options | object | Additional options to customize the symbol (see below) | | tooltipContent | string or ReactNode | Optional content for tooltip | | popupContent | string or ReactNode | Optional content for popup | | eventHandlers | object | Leaflet event handlers for the marker |

Options Object

The options object can include any properties available in the milsymbol library, such as:

{
  size: 35,              // Size of the symbol
  fill: true,            // Fill the symbol with color
  fillOpacity: 0.5,      // Opacity of the fill
  strokeWidth: 2,        // Width of the outline stroke
  outlineColor: "rgb(0, 0, 0)",  // Color of the outline
  outlineWidth: 3,       // Width of the symbol outline
  icon: true,            // Show the icon
  monoColor: false,      // Use monochrome color
  civilianColor: false,  // Use civilian colors for the symbol
  colorMode: "Light",    // "Light", "Medium", "Dark"
  infoColor: "rgb(70, 70, 70)",  // Color for information fields
  infoSize: 10,          // Size of information fields
  alternateMedal: false, // Use alternate medal
}

Advanced Usage

Custom Symbol Styling

{/* SHGPUCA---MT - Hostile (H) Ground Armor unit */}
<MilSymbol
  position={[51.505, -0.09]}
  sidc="SHGPUCA---MT"
  options={{
    size: 40,
    fill: true,
    fillOpacity: 0.7,
    colorMode: "Dark",
    monoColor: "rgb(255, 0, 0)",
    infoFields: false,
  }}
/>

With Popup and Tooltip

{/* SNGPUCD---MT - Neutral (N) Ground Air Defense unit */}
<MilSymbol
  position={[51.505, -0.09]}
  sidc="10031000001211000000"
  tooltipContent="Infantry Unit"
  popupContent={
    <div>
      <h3>Infantry Unit</h3>
      <p>Unit ID: 12345</p>
      <p>Status: Active</p>
    </div>
  }
/>

With Event Handlers

{/* SUGPUCF---MT - Unknown (U) Ground Artillery unit */}
<MilSymbol
  position={[51.505, -0.09]}
  sidc="SUGPUCF---MT"
  eventHandlers={{
    click: () => {
      console.log('Symbol clicked!');
    },
    mouseover: () => {
      console.log('Mouse over symbol');
    },
  }}
/>

API Reference

Components

<MilSymbol />

The main component for adding military symbols to your React Leaflet map.

Hooks

useMilSymbol(sidc, options)

A hook for creating milsymbol instances outside of the component. Accepts both letter-based and numeric SIDCs.

import { useMilSymbol } from 'react-leaflet-milsymbol';

function SymbolPreview() {
  const symbol = useMilSymbol("10031000001211000000", { size: 30 });

  return (
    <div>
      <h3>Symbol Preview</h3>
      <div dangerouslySetInnerHTML={{ __html: symbol.asSVG() }} />
    </div>
  );
}

Demo

A live demo is available at jacorbello.github.io/react-leaflet-milsymbol showing various military symbols on a Leaflet map.

To run the demo locally:

git clone https://github.com/jacorbello/react-leaflet-milsymbol.git
cd react-leaflet-milsymbol
npm install
npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• milsymbol - The core library for generating military symbols
• react-leaflet - React components for Leaflet maps