Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
SwiftDitherKit is a dependency-free SwiftUI chart library that renders area, line, bar, pie, donut, radar, and sparkline views using ordered-dither textures. The library focuses on providing a native, lightweight alternative for charting with a specific retro-aesthetic, based on the original Dither Kit.
The core workflow involves defining stable data identifiers, configuring series or slices, and selecting a chart type. The library handles rendering and caching dithered images away from the Main Actor to ensure performance, though it provides specific modes for offscreen rendering like ImageRenderer.
Sources: Sources/SwiftDitherKit/SwiftDitherKit.docc/SwiftDitherKit.md, README.md:1-10
Core Data Structures
To render a chart, developers must provide data in the form of DitherDatum for Cartesian/Radar charts or DitherSlice for Pie/Donut charts. These structures rely on stable IDs to maintain consistency during updates and animations.
Cartesian and Radar Data
DitherDatum represents a single category (e.g., a month or a specific attribute). Its values dictionary maps series IDs to numerical data points.
public struct DitherDatum: Identifiable, Hashable, Sendable {
public let id: String
public let label: String
public let values: [String: Double]
// ...
}
Sources: Sources/SwiftDitherKit/DitherTypes.swift:105-115
Pie and Donut Data
DitherSlice represents a single wedge. It includes a specific value, color, and dither variant.
| Field | Type | Description |
|---|---|---|
id | String | Unique stable identifier for the slice. |
label | String? | Optional display label; defaults to ID if nil. |
value | Double | Numerical value; negative/NaN values are treated as zero. |
color | DitherColor | The primary color of the slice. |
variant | DitherVariant | The dither pattern (e.g., .gradient, .dotted). |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:133-149, Sources/SwiftDitherKit/SwiftDitherKit.docc/GettingStarted.md:40-45
Component Architecture and Flow
SwiftDitherKit uses a decoupled architecture where chart views receive configuration options and data, then trigger asynchronous rendering of dithered rasters.
The diagram above illustrates the data flow from user configuration to the final rendered dithered image.
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:80-100, Sources/SwiftDitherKit/SwiftDitherKit.docc/SwiftDitherKit.md:15-20
Basic Implementation
To implement a basic chart, you define your series and data, then embed the chart view in your SwiftUI hierarchy. You must provide a height, as the raster follows the proposed size of the chart.
let series = [
DitherSeries(id: "desktop", label: "Desktop", color: .blue),
DitherSeries(id: "mobile", label: "Mobile", color: .purple, variant: .hatched)
]
DitherAreaChart(
data: data,
series: series,
options: DitherCartesianOptions(stacking: .stacked)
)
.frame(height: 260)
Sources: README.md:40-70, Sources/SwiftDitherKit/SwiftDitherKit.docc/GettingStarted.md:30-38
Customization and Visual Effects
The library provides several options to customize the appearance of the dithered output, including color definitions and "bloom" effects.
Colors and Dither Variants
DitherColor can be initialized via RGB components or hex values. DitherVariant determines the thresholding pattern used during the dithering process.
- DitherColor Static Presets:
.green,.blue,.purple,.pink,.orange,.red,.grey. - DitherVariants:
gradient,dotted,hatched,solid.
Sources: Sources/SwiftDitherKit/DitherTypes.swift:15-45, Sources/SwiftDitherKit/DitherTypes.swift:51-56
Bloom Effects
DitherBloom creates a glow effect by blurring a copy of the low-resolution raster.
| Option | Intensity | Style Characteristics |
|---|---|---|
.off | None | No glow applied. |
.low | Subtle | 3pt blur, 0.70 opacity. |
.high | Moderate | 5pt blur, 0.78 opacity. |
.aura | Dramatic | 15pt blur, 0.10 opacity, high saturation. |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:59-64, Sources/SwiftDitherKit/DitherTypes.swift:190-201
Interaction and State Management
Charts support selection via tapping marks (for Area, Line, Bar, and Pie) or the legend (for Radar). Selection is managed through an optional Binding<String?>.
The sequence diagram shows the selection logic where tapping an active item clears it, while tapping a new item updates the selection.
Sources: Sources/SwiftDitherKit/SwiftDitherKit.docc/InteractionAndAccessibility.md:5-20, Sources/SwiftDitherKit/DitherCartesianCharts.swift:230-245
Conclusion
Getting started with SwiftDitherKit requires defining data with stable identifiers and choosing between Cartesian or Polar chart types. By configuring DitherCartesianOptions or DitherPolarOptions, developers can control stacking, animation, and accessibility. The library ensures performance by rendering rasters asynchronously, while providing a synchronous .immediate mode for offscreen snapshots.
Sources: Sources/SwiftDitherKit/SwiftDitherKit.docc/GettingStarted.md:50-60, README.md:120-130