Using icons

An icon is a definition object (dwSave on the web and in React Native, .save in Swift, DotwearIcons.save in Flutter) 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

React Native

With @dotwear/react-native, import everything from "@dotwear/react-native" instead.

import { DotwearIcon, DotwearIconProvider, byName, byPrefixAndName, dwTrash, palettes, type DotwearIconName } from "@dotwear/react-native-icons";

Flutter

import 'package:dotwear_icons/dotwear_icons.dart'; // or: package:dotwear/dotwear.dart

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 and in React Native a non-integer is rounded down with a console warning; in Swift and Flutter the parameter is an Int. In React Native and Flutter each cell is also rounded to whole device pixels, so icons stay sharp on fractional densities such as 2.625×.

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

React Native

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

Flutter

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

Color

The main color follows the text color: currentColor on the web, foregroundStyle in SwiftUI. React Native has no inherited text color, so pass color, or set it for a subtree with <DotwearIconProvider color> (<DotwearTheme> sets it to the theme's foreground). In Flutter it follows IconTheme, like a Material Icon. Palette colors (below) are separate.

Web (React)

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

iOS (SwiftUI)

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

React Native

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

Flutter

const DotwearIcon(DotwearIcons.trash, scale: 2, color: Colors.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"))

React Native

{/* Decorative: hidden from VoiceOver and TalkBack */}
<DotwearIcon icon={dwSave} />

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

Flutter

// Decorative: excluded from VoiceOver and TalkBack
const DotwearIcon(DotwearIcons.save),

// Meaningful on its own: give it a label
const DotwearIcon(DotwearIcons.trash, semanticLabel: '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)

React Native

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

Flutter

const DotwearIcon(DotwearIcons.save, grid: DotwearIconGrid.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)
}

React Native

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

Flutter

if (DotwearIcons.named(name) case final icon?) 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), .dotwearPalette() (SwiftUI) or <DotwearIconProvider palette> (React Native) or DotwearIconTheme(palette:) (Flutter).

PaletteWebSwiftReact NativeFlutterSlots
default data-dw-palette="default" .default palettes["default"] DotwearPalettes.default_ 2 3 4 5
retro-green data-dw-palette="retro-green" .retroGreen palettes["retro-green"] DotwearPalettes.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)

React Native

<DotwearIconProvider palette={palettes["retro-green"]}>
  <DotwearIcon icon={byName.folder} scale={2} />
</DotwearIconProvider>

Flutter

const DotwearIconTheme(
  palette: DotwearPalettes.retroGreen,
  child: DotwearIcon(DotwearIcons.folder, scale: 2),
),

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.