1# SwiftUI Charts Reference
2 
3## Table of Contents
4 
5- [Overview](#overview)
6- [Availability](#availability)
7- [Core APIs](#core-apis)
8- [Chart Types](#chart-types)
9- [Axis Tweaks](#axis-tweaks)
10- [Selection APIs](#selection-apis)
11- [Annotations](#annotations)
12- [ChartProxy and Custom Touch Handling](#chartproxy-and-custom-touch-handling)
13- [Modifier Scope](#modifier-scope)
14- [Styling and Visual Channels](#styling-and-visual-channels)
15- [Composing Multiple Marks](#composing-multiple-marks)
16- [Animating Chart Data](#animating-chart-data)
17- [Best Practices](#best-practices)
18 
19## Overview
20 
21Swift Charts is Apple's native charting framework for SwiftUI. Use `Chart` with one or more marks to build bar, line, area, point, rule, rectangle, and sector charts. This reference covers the standard 2D chart APIs, axis customization, built-in selection APIs, annotations, and custom touch handling.
22 
23## Availability
24 
25Base `Chart`, custom axes, scales, and most marks require iOS 16 or later.
26 
27- `BarMark`, `LineMark`, `AreaMark`, `PointMark`, `RectangleMark`, and `RuleMark` are available on iOS 16+
28- `SectorMark`, built-in selection, and scrollable chart axes require iOS 17+
29- Data-driven plot types such as `BarPlot` and `LinePlot` require iOS 18+
30- Chart3D and Z-axis APIs exist on iOS 26+; this reference is primarily about 2D `Chart`, with a dedicated Chart3D section below
31 
32```swift
33if #available(iOS 17, *) {
34    // Selection, SectorMark, scrollable axes
35} else {
36    // Base Chart, axes, scales, and core marks
37}
38```
39 
40## Core APIs
41 
42### Import the Framework
43 
44Always check that the file imports `Charts` before using `Chart`, `Chart3D`, `BarMark`, `SectorMark`, or `ChartProxy`.
45 
46```swift
47import SwiftUI
48import Charts
49```
50 
51If chart types are unresolved, the first thing to verify is that `Charts` is imported in that file.
52 
53### Chart Container
54 
55`Chart` is the root view. Add one or more marks inside it.
56 
57```swift
58Chart(sales) { item in
59    BarMark(
60        x: .value("Month", item.month),
61        y: .value("Revenue", item.revenue)
62    )
63}
64```
65 
66### Data Models Should Be Identifiable
67 
68Prefer `Identifiable` models for chart data so identity stays stable as data changes.
69 
70```swift
71struct SalesPoint: Identifiable {
72    let id: UUID
73    let month: String
74    let revenue: Double
75}
76```
77 
78If your model cannot conform to `Identifiable`, provide an explicit id key path:
79 
80```swift
81Chart(sales, id: \.month) { item in
82    BarMark(
83        x: .value("Month", item.month),
84        y: .value("Revenue", item.revenue)
85    )
86}
87```
88 
89### Plottable Values
90 
91Use `.value(_, _)` to describe what each axis value means. Those labels are reused by axes, legends, and accessibility.
92 
93```swift
94LineMark(
95    x: .value("Day", entry.date),
96    y: .value("Steps", entry.count)
97)
98```
99 
100## Chart Types
101 
102### BarMark
103 
104```swift
105BarMark(
106    x: .value("Product", product.name),
107    y: .value("Units", product.units)
108)
109```
110 
111Stacking via `MarkStackingMethod`: `.standard`, `.normalized`, `.center`, `.unstacked`.
112 
113### LineMark
114 
115```swift
116LineMark(
117    x: .value("Day", day.date),
118    y: .value("Steps", day.count)
119)
120.interpolationMethod(.monotone)
121```
122 
123Interpolation methods: `.linear`, `.monotone`, `.cardinal`, `.catmullRom`, `.stepStart`, `.stepCenter`, `.stepEnd`. Cardinal and Catmull-Rom accept optional tension/alpha parameters.
124 
125### AreaMark
126 
127```swift
128AreaMark(
129    x: .value("Hour", sample.hour),
130    y: .value("Temperature", sample.value),
131    stacking: .unstacked
132)
133```
134 
135Ranged areas use `yStart`/`yEnd` for bands like min/max or confidence intervals:
136 
137```swift
138AreaMark(
139    x: .value("Day", sample.day),
140    yStart: .value("Low", sample.low),
141    yEnd: .value("High", sample.high)
142)
143```
144 
145### PointMark
146 
147```swift
148PointMark(
149    x: .value("Time", measurement.time),
150    y: .value("Value", measurement.value)
151)
152```
153 
154### RectangleMark
155 
156```swift
157RectangleMark(
158    xStart: .value("Start Day", cell.startDay),
159    xEnd: .value("End Day", cell.endDay),
160    yStart: .value("Low", cell.low),
161    yEnd: .value("High", cell.high)
162)
163```
164 
165### RuleMark
166 
167```swift
168RuleMark(y: .value("Goal", 10_000))
169    .foregroundStyle(.red)
170```
171 
172### SectorMark
173 
174Use `SectorMark` for pie and donut-style charts. `SectorMark` requires iOS 17 or later.
175 
176```swift
177Chart(expenses) { expense in
178    SectorMark(
179        angle: .value("Amount", expense.amount),
180        innerRadius: .ratio(0.6),
181        angularInset: 2
182    )
183    .foregroundStyle(by: .value("Category", expense.category))
184}
185```
186 
187Use `innerRadius` to turn a pie chart into a donut chart, and `angularInset` to separate slices visually.
188 
189### Plot Types (iOS 18+)
190 
191iOS 18 adds data-driven plot wrappers: `AreaPlot`, `BarPlot`, `LinePlot`, `PointPlot`, `RectanglePlot`, `RulePlot`, and `SectorPlot`.
192 
193`LinePlot` and `AreaPlot` also accept function closures for plotting mathematical functions without discrete data:
194 
195```swift
196if #available(iOS 18, *) {
197    Chart {
198        LinePlot(x: "x", y: "sin(x)") { x in
199            sin(x)
200        }
201    }
202    .chartXScale(domain: -Double.pi ... Double.pi)
203    .chartYScale(domain: -1.5 ... 1.5)
204}
205```
206 
207Use plot types when you want a data-first API surface or need function plotting. The underlying chart families stay the same.
208 
209### Chart3D (iOS 26+)
210 
211`Chart3D` is a separate API for 3D chart content. It supports 3D `PointMark`, `RectangleMark`, `RuleMark`, and `SurfacePlot`.
212 
213```swift
214if #available(iOS 26, *) {
215    Chart3D(points) { point in
216        PointMark(
217            x: .value("X", point.x),
218            y: .value("Y", point.y),
219            z: .value("Z", point.z)
220        )
221    }
222    .chart3DPose(.front)
223    .chart3DCameraProjection(.perspective)
224}
225```
226 
227`SurfacePlot` visualizes mathematical surfaces by evaluating a two-variable function:
228 
229```swift
230if #available(iOS 26, *) {
231    Chart3D {
232        SurfacePlot(x: "x", y: "height", z: "z") { x, z in
233            sin(x) * cos(z)
234        }
235    }
236    .chartXScale(domain: -Double.pi ... Double.pi)
237    .chartZScale(domain: -Double.pi ... Double.pi)
238}
239```
240 
241Camera and pose configuration:
242 
243- **Projection**: `.chart3DCameraProjection(.orthographic)` (default, precise measurements) or `.perspective` (depth effect)
244- **Pose presets**: `.chart3DPose(.default)`, `.front`, `.back`, `.left`, `.right`
245- **Custom pose**: `.chart3DPose(azimuth: .degrees(45), inclination: .degrees(30))`
246- On visionOS, Chart3D supports natural 3D interaction gestures for rotation and exploration
247 
248**Always** gate `Chart3D` with `#available(iOS 26, *)` — it is not available on earlier OS versions.
249 
250## Axis Tweaks
251 
252### Axis Visibility and Labels
253 
254Use `chartXAxis`, `chartYAxis`, `chartXAxisLabel`, and `chartYAxisLabel` on the `Chart` container.
255Axis visibility supports `.automatic`, `.visible`, and `.hidden`.
256 
257```swift
258Chart(data) { item in
259    BarMark(
260        x: .value("Month", item.month),
261        y: .value("Revenue", item.revenue)
262    )
263}
264.chartXAxis(.visible)
265.chartYAxis(.hidden)
266.chartXAxisLabel("Month")
267.chartYAxisLabel("Revenue")
268```
269 
270### Custom Axis Marks
271 
272Use `AxisMarks` to control tick placement, labels, and grid lines.
273 
274```swift
275Chart(steps) { day in
276    LineMark(
277        x: .value("Day", day.date),
278        y: .value("Steps", day.count)
279    )
280}
281.chartXAxis {
282    AxisMarks(
283        preset: .aligned,
284        position: .bottom,
285        values: .stride(by: .day)
286    ) {
287        AxisGridLine()
288        AxisTick(length: .label)
289        AxisValueLabel(format: .dateTime.weekday(.abbreviated))
290    }
291}
292```
293 
294Useful `AxisMarks` inputs:
295 
296- `preset`: `.automatic`, `.extended`, `.aligned`, `.inset`
297- `position`: `.automatic`, `.leading`, `.trailing`, `.top`, `.bottom`
298- `values`: `.automatic`, `.automatic(desiredCount:)`, `.stride(by:)`, `.stride(by:count:)`, or an explicit array
299 
300### Axis Components
301 
302Within `AxisMarks`, combine the built-in axis components as needed:
303 
304```swift
305AxisGridLine()
306AxisTick()
307AxisValueLabel()
308```
309 
310`AxisValueLabel` can be tuned for dense axes:
311 
312```swift
313AxisValueLabel(
314    collisionResolution: .greedy(minimumSpacing: 8),
315    orientation: .vertical
316)
317```
318 
319Label orientations: `.automatic`, `.horizontal`, `.vertical`, `.verticalReversed`.
320 
321Collision strategies: `.automatic`, `.greedy`, `.greedy(priority:minimumSpacing:)`, `.truncate`, `.disabled`.
322 
323### Axis Domains and Plot Area Tweaks
324 
325Use scales when you need explicit axis domains or plot area control.
326 
327```swift
328Chart(data) { item in
329    LineMark(
330        x: .value("Index", item.index),
331        y: .value("Score", item.score)
332    )
333}
334.chartXScale(domain: 0...30)
335.chartYScale(domain: 0...100)
336.chartPlotStyle { plotArea in
337    plotArea
338        .background(.gray.opacity(0.08))
339}
340```
341 
342You can set one axis domain without forcing the other:
343 
344```swift
345.chartXScale(domain: startDate...endDate)
346```
347 
348### Scrollable Axes (iOS 17+)
349 
350For larger datasets, make the plot area scroll and control the visible domain.
351 
352```swift
353@State private var scrollX = 7
354 
355Chart(data) { item in
356    BarMark(
357        x: .value("Day", item.day),
358        y: .value("Value", item.value)
359    )
360}
361.chartScrollableAxes(.horizontal)
362.chartXVisibleDomain(length: 7)
363.chartScrollPosition(x: $scrollX)
364```
365 
366## Selection APIs
367 
368### Single-Value Selection
369 
370Use `chartXSelection(value:)` or `chartYSelection(value:)` for one selected value.
371 
372```swift
373@State private var selectedDate: Date?
374 
375Chart(steps) { day in
376    LineMark(x: .value("Day", day.date), y: .value("Steps", day.count))
377 
378    if let selectedDate {
379        RuleMark(x: .value("Selected Day", selectedDate))
380            .foregroundStyle(.secondary)
381    }
382}
383.chartXSelection(value: $selectedDate)
384```
385 
386### Range Selection
387 
388Use `chartXSelection(range:)` or `chartYSelection(range:)` for a dragged range. Bind to a `ClosedRange` whose bound type matches the plotted axis value.
389 
390```swift
391@State private var selectedWeeks: ClosedRange<Int>?
392 
393Chart(weeks) { week in
394    BarMark(x: .value("Week", week.index), y: .value("Revenue", week.revenue))
395}
396.chartXSelection(range: $selectedWeeks)
397```
398 
399### Choosing Single vs Range
400 
401- Use `value:` bindings when only one point or axis value should be selected.
402- Use `range:` bindings when users should brush a span (for zoom windows, comparisons, or grouped summaries).
403 
404### Angle Selection
405 
406Use `chartAngleSelection(value:)` with `SectorMark` charts. No built-in range overload for angle selection.
407 
408```swift
409@State private var selectedAmount: Double?
410 
411Chart(expenses) { expense in
412    SectorMark(angle: .value("Amount", expense.amount))
413        .foregroundStyle(by: .value("Category", expense.category))
414}
415.chartAngleSelection(value: $selectedAmount)
416```
417 
418**Important**: Selection bindings return the plottable axis value, not the full data element. Map back to your model if you need the selected record.
419 
420## Annotations
421 
422Use `annotation(position:)` on a mark when you need labels, callouts, or highlighted values attached to the plotted content.
423 
424```swift
425BarMark(
426    x: .value("Month", item.month),
427    y: .value("Revenue", item.revenue)
428)
429.annotation(position: .top) {
430    Text(item.revenue.formatted())
431}
432```
433 
434This is useful for selected values, thresholds, summaries, and direct labeling. Common positions include `.overlay`, `.top`, `.bottom`, `.leading`, and `.trailing`.
435 
436## ChartProxy and Custom Touch Handling
437 
438Use `chartOverlay`/`chartBackground` (iOS 16+) or `chartGesture` (iOS 17+) with `ChartProxy` when built-in selection modifiers are not enough.
439 
440```swift
441.chartOverlay { proxy in
442    GeometryReader { geometry in
443        Rectangle().fill(.clear).contentShape(Rectangle())
444            .gesture(
445                DragGesture(minimumDistance: 0)
446                    .onChanged { value in
447                        guard let plotFrame = proxy.plotFrame else { return } // iOS 16: use proxy.plotAreaFrame
448                        let frame = geometry[plotFrame]
449                        let x = value.location.x - frame.origin.x
450                        guard x >= 0, x <= frame.size.width else { return }
451                        selectedDate = proxy.value(atX: x, as: Date.self)
452                    }
453                    .onEnded { _ in selectedDate = nil }
454            )
455    }
456}
457```
458 
459Use `proxy.plotFrame` (iOS 17+) or `proxy.plotAreaFrame` (iOS 16) to get the plot area anchor.
460 
461`ChartProxy` gives you lower-level access to:
462 
463- `value(atX:as:)`, `value(atY:as:)`, and `value(at:as:)` for converting gesture coordinates into chart values
464- `position(forX:)`, `position(forY:)`, and `position(for:)` for placing custom overlays or indicators
465- `selectXValue(at:)`, `selectYValue(at:)`, `selectXRange(from:to:)`, and `selectYRange(from:to:)` for driving built-in selection from custom gestures
466- `plotFrame` (iOS 17+) or `plotAreaFrame` (iOS 16) with `plotSize` for converting between gesture coordinates and the plot area
467 
468`select*` ChartProxy selection methods and `chartGesture` are available on iOS 17+.
469 
470## Modifier Scope
471 
472Apply chart-wide modifiers to the `Chart` container and mark-specific modifiers to the individual mark.
473 
474```swift
475Chart(data) { item in
476    LineMark(
477        x: .value("Day", item.date),
478        y: .value("Value", item.value)
479    )
480    .interpolationMethod(.monotone)   // Mark-level modifier
481}
482.chartXAxis { AxisMarks() }            // Chart-level modifier
483.chartYScale(domain: 0...100)          // Chart-level modifier
484.chartPlotStyle { $0.background(.thinMaterial) }
485```
486 
487## Styling and Visual Channels
488 
489### Categorical Coloring
490 
491Use `foregroundStyle(by: .value(...))` to color marks by a data property. Swift Charts generates a legend automatically.
492 
493```swift
494Chart(sales) { item in
495    BarMark(
496        x: .value("Month", item.month),
497        y: .value("Revenue", item.revenue)
498    )
499    .foregroundStyle(by: .value("Region", item.region))
500}
501```
502 
503**Avoid** applying `.foregroundStyle(.red)` per mark for categorical data — this suppresses the automatic legend and breaks accessibility.
504 
505### Custom Color Scales
506 
507Use `chartForegroundStyleScale` to control the mapping from data values to colors.
508 
509```swift
510.chartForegroundStyleScale([
511    "North": .blue,
512    "South": .orange,
513    "East": .green
514])
515```
516 
517For dynamic data where not all series appear at every point, use the mapping overload:
518 
519```swift
520.chartForegroundStyleScale(domain: regions, mapping: { region in
521    colorForRegion(region)
522})
523```
524 
525### Symbol and Size Channels
526 
527Use `symbol(by:)` and `symbolSize(by:)` to encode additional data dimensions on `PointMark` and `LineMark`.
528 
529```swift
530Chart(measurements) { item in
531    PointMark(
532        x: .value("Time", item.time),
533        y: .value("Value", item.value)
534    )
535    .foregroundStyle(by: .value("Category", item.category))
536    .symbol(by: .value("Category", item.category))
537    .symbolSize(by: .value("Weight", item.weight))
538}
539```
540 
541### Legend Control
542 
543```swift
544.chartLegend(.visible)
545.chartLegend(.hidden)
546.chartLegend(position: .bottom, alignment: .center)
547```
548 
549## Composing Multiple Marks
550 
551Combine different mark types inside the same `Chart` closure:
552 
553```swift
554// Line with points
555LineMark(x: .value("Day", day.date), y: .value("Steps", day.count))
556    .interpolationMethod(.monotone)
557PointMark(x: .value("Day", day.date), y: .value("Steps", day.count))
558 
559// Bars with threshold line
560BarMark(x: .value("Month", item.month), y: .value("Revenue", item.revenue))
561RuleMark(y: .value("Target", 10_000))
562    .foregroundStyle(.red)
563    .lineStyle(StrokeStyle(dash: [5, 3]))
564```
565 
566## Animating Chart Data
567 
568Chart marks animate automatically when data identity is stable and changes are wrapped in an animation.
569 
570```swift
571withAnimation(.easeInOut) {
572    chartData = updatedData
573}
574```
575 
576**Always** use `Identifiable` models (or explicit `id:`) so Swift Charts can match old and new data points and animate transitions between them.
577 
578## Best Practices
579 
580### Do
581 
582- Use semantic `.value(_, _)` labels so axes and accessibility read clearly
583- Prefer `Identifiable` models (or explicit `id:`) for stable chart data identity
584- Use `foregroundStyle(by:)` for categorical series to get automatic legends and accessibility
585- Use `RuleMark` for goals, thresholds, and selected-value indicators
586- Use explicit `AxisMarks(values:)` when automatic tick generation gets crowded
587- Use `chartXScale` and `chartYScale` when you need stable visual comparisons
588- Use `chartXSelection(range:)` or `chartYSelection(range:)` for brushed selection
589- Gate iOS 17+ APIs such as `SectorMark` and selection with `#available`
590 
591### Don't
592 
593- Put chart-wide modifiers such as `chartXAxis` or `chartXSelection` on individual marks
594- Apply manual `.foregroundStyle(.color)` per mark for categorical data — use `foregroundStyle(by:)` instead
595- Rely on unstable identities when chart data can be inserted, removed, or reordered
596- Use string values for naturally numeric or date-based axes unless you want categorical behavior
597- Stack unrelated series by default just because `BarMark` and `AreaMark` allow it
598- Force every tick label to display when collision handling or stride values would be clearer
599- Assume selection returns a model object; it only returns the plottable axis value
600- Forget that range selection is available only for X and Y axes, not angle selection
601 
602For chart accessibility (VoiceOver, Audio Graph, `AXChartDescriptorRepresentable`), fallback strategies, WWDC sessions, and a full summary checklist, see `charts-accessibility.md`.
603