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).
| Palette | Web | Swift | Slots |
|---|---|---|---|
| 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.