Sparkline Charts
Relevant source files
The following files were used as context for generating this wiki page:
- Sources/SwiftDitherKit/DitherCartesianCharts.swift
- Sources/SwiftDitherKit/DitherTypes.swift
- Sources/SwiftDitherKit/DitherSparkles.swift
- Sources/SwiftDitherKit/DitherRasterView.swift
- Tests/SwiftDitherKitTests/DitherSparkleTests.swift
- README.md
- Sources/SwiftDitherKit/SwiftDitherKit.docc/SwiftDitherKit.md
Sparkline charts in SwiftDitherKit are compact, single-series area charts designed for high-density data visualization without the overhead of traditional chart chrome. They are rendered using ordered-dither textures and include specialized idle animations known as "sparkles."
Unlike standard Cartesian charts, sparklines are non-interactive by default and omit axes, legends, and tooltips to maintain a minimal footprint suitable for inline text or dashboard summaries.
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:233-271, Sources/SwiftDitherKit/SwiftDitherKit.docc/SwiftDitherKit.md:12-14
Architecture and Data Flow
The DitherSparkline view acts as a convenience wrapper around the internal DitherCartesianChart logic. It transforms a simple array of Double values into the library's standard DitherDatum format, specifying the chart kind as .area.
Data Transformation
The sparkline internalizes the mapping of raw values to structured data. Every index in the input array is converted into a DitherDatum with a generated ID (e.g., "sample-0") and a label.
The diagram above shows the lifecycle of data from a raw array to the final dithered raster.
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:273-294
Idle Sparkle System
One of the defining visual features of sparklines in this library is the "sparkle" effect. These are small, single-pixel glints that appear within the filled area of the chart.
Sparkle Generation
Sparkles are generated based on the geometry of the chart's dithered bands. The DitherSparkleField calculates positions using a pseudo-random seed to ensure stability between renders while maintaining a density derived from the chart's width.
- Placement Logic: Sparkles are constrained between the "top" (data line) and "floor" (zero line) of the area series.
- Stability: The field uses a combining checksum to detect when the sparkle configuration needs updating.
Sources: Sources/SwiftDitherKit/DitherSparkles.swift:25-70, Tests/SwiftDitherKitTests/DitherSparkleTests.swift:24-36
Animation States
The motion of sparkles is governed by a global tick system. Each sparkle winks based on a sine wave function influenced by its individual phase.
The logic ensures that sparkles remains visible even when "Reduce Motion" is enabled, though they stop blinking.
Sources: Sources/SwiftDitherKit/DitherSparkles.swift:105-139, Tests/SwiftDitherKitTests/DitherSparkleTests.swift:65-80
Visual Configuration
Sparklines support several visual variants and enhancements through the DitherSparkline initializer.
| Parameter | Type | Description | Default |
|---|---|---|---|
values | [Double] | The sequence of data points to render. | Required |
color | DitherColor | The primary color for the dithered area. | Required |
variant | DitherVariant | The dither fill pattern (gradient, dotted, hatched, solid). | .gradient |
bloom | DitherBloom | Intensity of the glow effect behind the raster. | .off |
markerIndex | Int? | Optional vertical line at a specific data index. | nil |
animate | Bool | Whether to animate data changes and entrances. | false |
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:248-271, Sources/SwiftDitherKit/DitherTypes.swift:51-65
Implementation Example
A typical sparkline implementation within a SwiftUI view:
DitherSparkline(
values: [3, 7, 5, 9, 8, 12],
color: .green,
variant: .hatched,
bloom: .aura
)
.frame(height: 40)
Sources: Sources/DitherKitSnapshot/main.swift:108-115
Technical Constraints
- Margins: Sparklines use
DitherMargins.sparkline, which sets all insets (top, trailing, bottom, leading) to0. Sources: Sources/SwiftDitherKit/DitherTypes.swift:85 - Rendering: Like all charts in the kit, sparklines use
DitherAsyncRasterto generate pixels away from the Main Actor, unless.ditherRenderingMode(.immediate)is applied. Sources: Sources/SwiftDitherKit/DitherRasterView.swift:186-200 - Data Handling: Infinite and
NaNvalues provided in thevaluesarray are automatically treated as zero. Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:273-275
Conclusion
Sparkline charts provide a lightweight, dithered alternative to standard area charts within the SwiftDitherKit ecosystem. By leveraging the internal Cartesian rendering engine but disabling high-overhead features like axes and interaction, they achieve a high-performance, aesthetically unique "pixel art" style suitable for dense data environments.
Sources: README.md:95-103, Sources/SwiftDitherKit/DitherCartesianCharts.swift:233-246