Skill v1.0.1
currentAutomated scan100/100+1 new
version: "1.0.1" name: paperkit description: "Add drawings, shapes, and a consistent markup experience using PaperKit. Use when integrating PaperMarkupViewController for markup editing, adding shape recognition, working with PaperMarkup data models, embedding markup tools in document editors, or building annotation features that need the system-standard markup toolbar. New in iOS 26."
PaperKit
Beta-sensitive. PaperKit is new in iOS/iPadOS 26, macOS 26, and visionOS 26. API surface may change. Verify details against current Apple documentation before shipping.
PaperKit provides a unified markup experience — the same framework powering markup in Notes, Screenshots, QuickLook, and Journal. It combines PencilKit drawing with structured markup elements (shapes, text boxes, images, lines) in a single canvas managed by PaperMarkupViewController. Requires Swift 6.3 and the iOS 26+ SDK.
Contents
- Setup
- PaperMarkupViewController
- PaperMarkup Data Model
- Insertion Controllers
- FeatureSet Configuration
- Integration with PencilKit
- SwiftUI Integration
- Common Mistakes
- Review Checklist
- References
Setup
PaperKit requires no entitlements or special Info.plist entries.
import PaperKit
Platform availability: iOS 26.0+, iPadOS 26.0+, Mac Catalyst 26.0+, macOS 26.0+, visionOS 26.0+.
Three core components:
| Component | Role | |
|---|---|---|
PaperMarkupViewController | Interactive canvas for creating and displaying markup and drawing | |
PaperMarkup | Data model for serializing all markup elements and PencilKit drawing | |
MarkupEditViewController / MarkupToolbarViewController | Insertion UI for adding markup elements |
PaperMarkupViewController
The primary view controller for interactive markup. Provides a scrollable canvas for freeform PencilKit drawing and structured markup elements. Conforms to Observable and PKToolPickerObserver.
Basic UIKit Setup
import PaperKitimport PencilKitimport UIKitclass MarkupViewController: UIViewController, PaperMarkupViewController.Delegate {var paperVC: PaperMarkupViewController!var toolPicker: PKToolPicker!override func viewDidLoad() {super.viewDidLoad()let pageBounds = CGRect(origin: .zero, size: CGSize(width: 612, height: 792))let markup = PaperMarkup(bounds: pageBounds)let features = FeatureSet.latestpaperVC = PaperMarkupViewController(markup: markup,supportedFeatureSet: features)paperVC.delegate = selfaddChild(paperVC)paperVC.view.frame = view.boundspaperVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]view.addSubview(paperVC.view)paperVC.didMove(toParent: self)toolPicker = PKToolPicker()toolPicker.addObserver(paperVC)paperVC.pencilKitResponderState.activeToolPicker = toolPickerpaperVC.pencilKitResponderState.toolPickerVisibility = .visible}func paperMarkupViewControllerDidChangeMarkup(_ controller: PaperMarkupViewController) {guard let markup = controller.markup else { return }Task { try await save(markup) }}}
Key Properties
| Property | Type | Description | |
|---|---|---|---|
markup | PaperMarkup? | The current data model | |
selectedMarkup | PaperMarkup | Currently selected content | |
isEditable | Bool | Whether the canvas accepts input | |
isRulerActive | Bool | Whether the ruler overlay is shown | |
drawingTool | any PKTool | Active PencilKit drawing tool | |
contentView | UIView? / NSView? | Background view rendered beneath markup | |
zoomRange | ClosedRange<CGFloat> | Min/max zoom scale | |
supportedFeatureSet | FeatureSet | Enabled PaperKit features |
Touch Modes
PaperMarkupViewController.TouchMode has two cases: .drawing and .selection.
paperVC.directTouchMode = .drawing // Finger drawspaperVC.directTouchMode = .selection // Finger selects elementspaperVC.directTouchAutomaticallyDraws = true // System decides based on Pencil state
Content Background
Set any view beneath the markup layer for templates, document pages, or images being annotated. Keep the PaperMarkup(bounds:) coordinate space aligned to the background content, such as a PDF page or rendered image size, so saved annotations restore in the right place:
let pageBounds = CGRect(origin: .zero, size: pageImage.size)let imageView = UIImageView(image: pageImage)imageView.frame = pageBoundslet markup = PaperMarkup(bounds: pageBounds)paperVC = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)paperVC.contentView = imageView
Delegate Callbacks
| Method | Called when | |
|---|---|---|
paperMarkupViewControllerDidChangeMarkup(_:) | Markup content changes | |
paperMarkupViewControllerDidBeginDrawing(_:) | User starts drawing | |
paperMarkupViewControllerDidChangeSelection(_:) | Selection changes | |
paperMarkupViewControllerDidChangeContentVisibleFrame(_:) | Visible frame changes |
PaperMarkup Data Model
PaperMarkup is a Sendable struct that stores all markup elements and PencilKit drawing data.
Creating and Persisting
// New empty model. Bounds define the saved document coordinate space.let markup = PaperMarkup(bounds: CGRect(x: 0, y: 0, width: 612, height: 792))// Load from saved datalet markup = try PaperMarkup(dataRepresentation: savedData)// Save — dataRepresentation() is async throwsfunc save(_ markup: PaperMarkup) async throws {let data = try await markup.dataRepresentation()try data.write(to: fileURL)}
Inserting Content Programmatically
// Text boxmarkup.insertNewTextbox(attributedText: AttributedString("Annotation"),frame: CGRect(x: 50, y: 100, width: 200, height: 40),rotation: 0)// Imagemarkup.insertNewImage(cgImage, frame: CGRect(x: 50, y: 200, width: 300, height: 200), rotation: 0)// Shapelet shapeConfig = ShapeConfiguration(type: .rectangle,fillColor: UIColor.systemBlue.withAlphaComponent(0.2).cgColor,strokeColor: UIColor.systemBlue.cgColor,lineWidth: 2)markup.insertNewShape(configuration: shapeConfig, frame: CGRect(x: 50, y: 420, width: 200, height: 100), rotation: 0)// Line with arrow end markerlet lineConfig = ShapeConfiguration(type: .line, fillColor: nil, strokeColor: UIColor.red.cgColor, lineWidth: 3)markup.insertNewLine(configuration: lineConfig,from: CGPoint(x: 50, y: 550), to: CGPoint(x: 250, y: 550),startMarker: false, endMarker: true)
Shape types: .rectangle, .roundedRectangle, .ellipse, .line, .arrowShape, .star, .chatBubble, .regularPolygon.
Other Operations
markup.append(contentsOf: otherMarkup) // Merge another PaperMarkupmarkup.append(contentsOf: pkDrawing) // Merge a PKDrawingmarkup.transformContent(CGAffineTransform(...)) // Apply affine transformmarkup.removeContentUnsupported(by: featureSet) // Strip unsupported elements
| Property | Description | |
|---|---|---|
bounds | Coordinate space of the markup | |
contentsRenderFrame | Tight bounding box of all content | |
featureSet | Features used by this data model's content | |
indexableContent | Extractable text for search indexing |
Use suggestedFrameForInserting(contentInFrame:) on the view controller to get a frame that avoids overlapping existing content.
Insertion Controllers
MarkupEditViewController (iOS, iPadOS, Mac Catalyst, visionOS)
Presents a popover menu for inserting shapes, text boxes, lines, and other elements.
func showInsertionMenu(from barButtonItem: UIBarButtonItem) {let editVC = MarkupEditViewController(supportedFeatureSet: paperVC.supportedFeatureSet,additionalActions: [])editVC.delegate = paperVC // PaperMarkupViewController conforms to the delegateeditVC.modalPresentationStyle = .popovereditVC.popoverPresentationController?.barButtonItem = barButtonItempresent(editVC, animated: true)}
MarkupToolbarViewController (macOS, Mac Catalyst)
Provides a toolbar with drawing tools and insertion buttons. Use it for native macOS and for Mac Catalyst toolbar-style UI; Catalyst apps that want a UIKit popover can use MarkupEditViewController.
let toolbar = MarkupToolbarViewController(supportedFeatureSet: paperVC.supportedFeatureSet)toolbar.delegate = paperVCaddChild(toolbar)toolbar.view.frame = toolbarContainerView.boundstoolbarContainerView.addSubview(toolbar.view)toolbar.didMove(toParent: self)
Both controllers must use the same FeatureSet as the PaperMarkupViewController.
FeatureSet Configuration
FeatureSet controls which markup capabilities are available.
| Preset | Description | |
|---|---|---|
.latest | All current features — recommended starting point | |
.version1 | Features from version 1 | |
.empty | No features enabled |
Customizing
var features = FeatureSet.latestfeatures.remove(.stickers)features.remove(.images)// Or build up from emptyvar features = FeatureSet.emptyfeatures.insert(.drawing)features.insert(.text)features.insert(.shapeStrokes)
Available Features
| Feature | Description | |
|---|---|---|
.drawing | Freeform PencilKit drawing | |
.text | Text box insertion | |
.images | Image insertion | |
.stickers | Sticker insertion | |
.links | Link annotations | |
.loupes | Loupe/magnifier elements | |
.shapeStrokes | Shape outlines | |
.shapeFills | Shape fills | |
.shapeOpacity | Shape opacity control |
HDR Support
Set colorMaximumLinearExposure above 1.0 on both the FeatureSet and PKToolPicker:
var features = FeatureSet.latestfeatures.colorMaximumLinearExposure = 4.0toolPicker.colorMaximumLinearExposure = features.colorMaximumLinearExposure
Use view.window?.windowScene?.screen.potentialEDRHeadroom to match the device screen's capability. Use 1.0 for SDR-only.
Shapes, Inks, and Line Markers
features.shapes = [.rectangle, .ellipse, .arrowShape, .line]features.inks = [.pen, .pencil, .marker]features.lineMarkerPositions = .all // .single, .double, .plain, or .all
Integration with PencilKit
PaperKit accepts PKTool for drawing and can append PKDrawing content.
PaperKit is not a drop-in replacement for a low-level PKCanvasView when the app depends on custom brush behavior, raw PKDrawing / PKStroke analytics, or custom lasso-centric editing. Keep those workflows owned by PencilKit, and add PaperKit beside them for structured review markup such as callouts, arrows, text boxes, labels, image stamps, and system-standard insertion UI. Migrate or duplicate existing drawings into a PaperKit annotation layer with PaperMarkup.append(contentsOf: PKDrawing) only when the low-level editing path no longer needs to own that content.
import PencilKit// Set drawing toolpaperVC.drawingTool = PKInkingTool(.pen, color: .black, width: 3)// Merge existing PKDrawing into markupmarkup.append(contentsOf: existingPKDrawing)
Tool Picker Setup
let toolPicker = PKToolPicker()toolPicker.addObserver(paperVC)paperVC.pencilKitResponderState.activeToolPicker = toolPickerpaperVC.pencilKitResponderState.toolPickerVisibility = .visible
Setting toolPickerVisibility to .hidden keeps the picker functional (responds to Pencil gestures) but not visible, enabling the mini tool picker experience.
Content Version Compatibility
FeatureSet.ContentVersion maps to PKContentVersion:
let pkVersion = features.contentVersion.pencilKitContentVersion
SwiftUI Integration
Wrap PaperMarkupViewController in UIViewControllerRepresentable:
struct MarkupView: UIViewControllerRepresentable {@Binding var markup: PaperMarkuplet features: FeatureSetfunc makeUIViewController(context: Context) -> PaperMarkupViewController {let vc = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)vc.delegate = context.coordinatorlet toolPicker = PKToolPicker()toolPicker.addObserver(vc)vc.pencilKitResponderState.activeToolPicker = toolPickervc.pencilKitResponderState.toolPickerVisibility = .visiblecontext.coordinator.toolPicker = toolPickerreturn vc}func updateUIViewController(_ vc: PaperMarkupViewController, context: Context) {if vc.markup != markup { vc.markup = markup }}func makeCoordinator() -> Coordinator { Coordinator(parent: self) }class Coordinator: NSObject, PaperMarkupViewController.Delegate {let parent: MarkupViewvar toolPicker: PKToolPicker?init(parent: MarkupView) { self.parent = parent }func paperMarkupViewControllerDidChangeMarkup(_ controller: PaperMarkupViewController) {if let markup = controller.markup { parent.markup = markup }}}}
Initialize the bound PaperMarkup from the document or page size before creating the SwiftUI bridge:
struct DocumentMarkupScreen: View {let pageSize: CGSize@State private var markup: PaperMarkupprivate let features = FeatureSet.latestinit(pageSize: CGSize) {self.pageSize = pageSize_markup = State(initialValue: PaperMarkup(bounds: CGRect(origin: .zero, size: pageSize)))}var body: some View {MarkupView(markup: $markup, features: features)}}
Common Mistakes
Mismatched FeatureSets
// DON'Tlet paperVC = PaperMarkupViewController(markup: m, supportedFeatureSet: .latest)let editVC = MarkupEditViewController(supportedFeatureSet: .version1, additionalActions: [])// DO — use the same FeatureSet for bothlet features = FeatureSet.latestlet paperVC = PaperMarkupViewController(markup: m, supportedFeatureSet: features)let editVC = MarkupEditViewController(supportedFeatureSet: features, additionalActions: [])
Ignoring Content Version on Load
// DON'Tlet markup = try PaperMarkup(dataRepresentation: data)paperVC.markup = markup// DO — check version compatibilitylet markup = try PaperMarkup(dataRepresentation: data)if markup.featureSet.isSubset(of: paperVC.supportedFeatureSet) {paperVC.markup = markup} else {showVersionMismatchAlert()}
Blocking Main Thread with Serialization
// DON'T — dataRepresentation() is async, don't try to work around it// DO — save from an async contextfunc paperMarkupViewControllerDidChangeMarkup(_ controller: PaperMarkupViewController) {guard let markup = controller.markup else { return }Task {let data = try await markup.dataRepresentation()try data.write(to: fileURL)}}
Forgetting to Retain the Tool Picker
// DON'T — local variable gets deallocatedfunc viewDidLoad() {let toolPicker = PKToolPicker()toolPicker.addObserver(paperVC)}// DO — store as instance propertyvar toolPicker: PKToolPicker!
Wrong Insertion Controller for Platform
// DON'T — treat MarkupEditViewController as unavailable on Mac Catalyst// DO — use the right UI for the presentation style#if os(macOS)let toolbar = MarkupToolbarViewController(supportedFeatureSet: features)#elseif targetEnvironment(macCatalyst)// Catalyst supports both: toolbar-style UI or UIKit popover insertion.let toolbar = MarkupToolbarViewController(supportedFeatureSet: features)let editVC = MarkupEditViewController(supportedFeatureSet: features, additionalActions: [])#elselet editVC = MarkupEditViewController(supportedFeatureSet: features, additionalActions: [])#endif
Review Checklist
- [ ]
import PaperKitpresent; deployment target is iOS 26+ / macOS 26+ / visionOS 26+ - [ ]
PaperMarkupinitialized with bounds matching content size - [ ] Same
FeatureSetused forPaperMarkupViewControllerand insertion controller - [ ]
dataRepresentation()called in async context - [ ]
PKToolPickerretained as a stored property - [ ] Delegate set on
PaperMarkupViewControllerfor change callbacks - [ ] Content version checked when loading saved data
- [ ] Correct insertion controller per platform (
MarkupToolbarViewControllerfor macOS/Catalyst toolbar UI;MarkupEditViewControllerfor UIKit/Catalyst popovers) - [ ]
MarkupErrorcases handled on deserialization - [ ] HDR:
colorMaximumLinearExposureset onFeatureSetandPKToolPicker.colorMaximumLinearExposure
References
- PaperKit documentation
- Integrating PaperKit into your app
- Meet PaperKit — WWDC25
- The
pencilkitskill covers PencilKit drawing, tool pickers, and PKDrawing serialization - references/paperkit-patterns.md — data persistence, rendering, multi-platform setup, custom feature sets