Using icons

An icon is a definition object (dwSave on the web, .save in Swift) that you pass to DotwearIcon. Unused icons are tree-shaken from web bundles.

Web (React)

With @dotwear/web, import everything from "@dotwear/web" instead.

import { dwSave } from "@dotwear/icons";
import { DotwearIcon } from "@dotwear/icons/react";

iOS (SwiftUI)

import DotwearIcons   // or: import Dotwear

Size: whole numbers only

scale multiplies the grid: a 16-grid icon is 16 px (pt) at scale 1, 32 at 2, 48 at 3. Only integers are accepted, because a fractional scale would put cell edges between device pixels and blur them. On the web a non-integer is rounded down with a console warning; in Swift the parameter is an Int.

Web (React)

<DotwearIcon icon={dwSave} />            {/* 16 × 16 px */}
<DotwearIcon icon={dwSave} scale={2} />  {/* 32 × 32 px */}

iOS (SwiftUI)

DotwearIcon(.save)             // 16 × 16 pt
DotwearIcon(.save, scale: 2)   // 32 × 32 pt

Color

The main color follows the text color: currentColor on the web, foregroundStyle in SwiftUI. Palette colors (below) are separate.

Web (React)

<DotwearIcon icon={dwTrash} scale={2} style={{ color: "crimson" }} />

iOS (SwiftUI)

DotwearIcon(.trash, scale: 2)
    .foregroundStyle(.red)

Accessibility label

Without a label an icon is decorative and hidden from screen readers — right when it sits next to text. Give it a label when the icon alone carries meaning.

Web (React)

{/* Decorative: hidden from screen readers */}
<DotwearIcon icon={dwSave} />

{/* Meaningful on its own: give it a title */}
<DotwearIcon icon={dwTrash} title="Delete" />

iOS (SwiftUI)

// Decorative: hidden from VoiceOver
DotwearIcon(.save)

// Meaningful on its own: give it a label
DotwearIcon(.trash, label: Text("Delete"))

Grids

Every icon has a 16 × 16 drawing. An icon can also have hand-tuned drawings for the 12 and 24 grids; ask for one with grid. If the icon has no drawing for that grid, the 16 grid is used.

Web (React)

<DotwearIcon icon={dwSave} scale={1} grid={24} />

iOS (SwiftUI)

DotwearIcon(.save, scale: 1, grid: .grid24)

Choosing an icon by name

For icons chosen at run time (from data or settings), look them up by name. On the web this includes every icon in the bundle, so prefer direct imports when you know the icon in advance.

Web (React)

<DotwearIcon icon={byName[name]} scale={2} />
<DotwearIcon icon={byPrefixAndName.dw["save"]} scale={2} />

iOS (SwiftUI)

if let icon = DotwearIconDefinition.allIcons.first(where: { $0.name == name }) {
    DotwearIcon(icon, scale: 2)
}

Palettes

Multi-color icons paint their extra colors from palette slots 2–9. Switch the palette for a whole subtree with data-dw-palette (web) or .dotwearPalette() (SwiftUI).

PaletteWebSwiftSlots
default data-dw-palette="default" .default 2 3 4 5
retro-green data-dw-palette="retro-green" .retroGreen 2 3 4 5

Web (React)

<div data-dw-palette="retro-green">
  <DotwearIcon icon={byName.folder} scale={2} />
</div>

iOS (SwiftUI)

DotwearIcon(.folder, scale: 2)
    .dotwearPalette(.retroGreen)

SVG files

Each icon is also shipped as a plain SVG in @dotwear/icons/svg/ (for example save.svg, and save-24.svg for a 24 grid). The SVGs use shape-rendering="crispEdges"; show them at whole-number multiples of their grid size.