PinStash

PinStash is a utility and library for composing Pinhead icons into various shapes, including pins, markers, circles, and squares. It's designed for map developers who need flexible, programmatically generated icons for MapLibre GL JS, Leaflet, or any other web-based mapping platform.

Features

• Icon Composition: Layer any Pinhead icon onto background shapes.
• Smart Coloring: Automatically chooses contrasting icon colors based on the background fill.
• Multiple Shapes: Supports circle, square, map_pin, and marker.
• CLI & API: Use it as a command-line tool for batch processing or as a JavaScript library in your app.
• Custom SVGs: Pass raw SVG strings to compose custom icons

Installation

npm install @trailstash/pinstash

Options

These options are common across both the CLI and API.

| Option | Description | Default | | :------------- | :---------------------------------------------------------------- | :---------------------------------------------------- | | cornerRadius | Corner radius (applies to square only) | 4 | | fill | Sets the fill color of the icon | black or white (auto-calculated from shapeFill) | | padding | Internal padding between icon and shape edge | Varies by shape | | scale | Scale factor for the output SVG dimensions | 1 | | shape | Background shape: square, circle, map_pin, or marker | none | | shapeFill | Fill color of the background shape | black | | stroke | Color of the stroke (applies to shape if present, otherwise icon) | Auto-calculated (contrasting or darkened/lightened) | | strokeWidth | Width of the stroke | 1 for marker, else 0 |

Usage

JavaScript API

Ideal for dynamic icon generation in the browser or on the server.

import { getSprite } from "@trailstash/pinstash";

// Simple icon
const svg = getSprite("cargobike");

// Icon with background and custom colors
const marker = getSprite("jeep", {
  shape: "map_pin",
  shapeFill: "#6486f5",
  strokeWidth: 1,
});

Examples

| Result | Code | | :------------------------------------------- | :-------------------------------------------------------------------------------------------------- | | | getSprite("cargobike") | | | getSprite("cup_and_saucer", { strokeWidth: 1 }) | | | getSprite("bicycle", { shape: "circle", shapeFill: "white", fill: "#6dad6f", stroke: "#6dad6f" }) | | | getSprite("burger", { shape: "marker", shapeFill: "#3FB1CE" }) | | | getSprite("ice_cream_on_cone", { shape: "circle", shapeFill: "pink" }) | | | getSprite("rocketship", { shape: "map_pin", shapeFill: "purple" }) |

Command Line Interface (CLI)

1. Generate a single sprite

Outputs the SVG string directly to stdout.

npx pinstash get-sprite cargobike --shape=square --shapeFill='#6486f5' > icon.svg

2. Batch build from configuration

The build-sprites command creates a collection of SVG files based on a JSON configuration file. By default, it looks for pinstash.json and writes results to a ./svgs/ directory.

npx pinstash build-sprites --config my-icons.json --outdir ./assets/icons

pinstash.json structure:

{
  "groups": [
    {
      "icons": {
        "bicycle": "bike-icon",
        "bus": "bus-marker"
      },
      "options": {
        "shape": "circle",
        "shapeFill": "#6486f5"
      }
    }
  ]
}

Custom SVG icon requirements

To work with PinStash, custom SVG strings must follow these constraints:

• Use only <path> elements.
• Path elements should only contain the d attribute.
• The viewBox should be "0 0 15 15", or height and width should be set to 15.

Integrations

Ultra

The develop branch(available at https://ultra.trailsta.sh) of Ultra features experimental PinStash integration . You can use it by specifying an icon-image value with the pinstash: prefix:

pinstash:ICONNAME?OPTION=VALUE

Example: pinstash:burger?shape=marker

MapLibre GL JS

To use PinStash dynamically with MapLibre:

const svg = getSprite("hospital", { shape: "circle", shapeFill: "red" });

const img = new Image();
const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });
img.src = URL.createObjectURL(blob);
await img.decode();

map.addImage("hospital-icon", img);

URL.revokeObjectURL(url);

Credits & Inspiration

PinStash is inspired by the Maki Icon Editor and makiwich. It uses icons from the Pinhead project.

License

WTFPL