Pencilkit

PencilKit

Capture Apple Pencil and finger input using PKCanvasView, manage drawing tools with PKToolPicker, serialize drawings with PKDrawing, and wrap PencilKit in SwiftUI.

Contents

• Setup
• Capture-to-Export Workflow
• PKCanvasView Basics
• PKToolPicker
• PKDrawing Serialization
• Content Version Compatibility
• Exporting to Image
• Stroke Inspection
• SwiftUI Integration
• PaperKit Relationship
• Common Mistakes
• Review Checklist
• References

Setup

PencilKit requires no entitlements or Info.plist entries. Import PencilKit and create a PKCanvasView.

import PencilKit

Platform availability: iOS 13+, iPadOS 13+, Mac Catalyst 13.1+, visionOS 1.0+.

Capture-to-Export Workflow

1. Capture: Read canvasView.drawing from canvasViewDrawingDidChange(_:); keep the previous persisted revision until the new revision completes the remaining checkpoints.
2. Serialize: Create dataRepresentation(), write atomically, and run the decode validate/fix/retry loop. Do not mark bytes valid when PKDrawing(data:) still throws.
3. Version-gate: Apply Content Version Compatibility before editable sync. If the recipient cannot load the drawing, preserve the full-fidelity source and use an existing compatible fallback or read-only preview.
4. Sync: Send only validated, compatible data and mark the revision synced after acknowledgement. On transport or conflict failure, retain the pending revision, resolve the cause, and retry without discarding the last good copy.
5. Export: Validate a nonempty drawing region and intended scale before calling image(from:scale:); skip export on invalid bounds without altering the serialized drawing.

PKCanvasView Basics

PKCanvasView is a UIScrollView subclass that captures Apple Pencil and finger input and renders strokes.

import PencilKitimport UIKit
class DrawingViewController: UIViewController, PKCanvasViewDelegate {    let canvasView = PKCanvasView()
    override func viewDidLoad() {        super.viewDidLoad()        canvasView.delegate = self        canvasView.drawingPolicy = .anyInput        canvasView.tool = PKInkingTool(.pen, color: .black, width: 5)        canvasView.frame = view.bounds        canvasView.autoresizingMask = [.flexibleWidth, .flexibleHeight]        view.addSubview(canvasView)    }
    func canvasViewDrawingDidChange(_ canvasView: PKCanvasView) {        // Drawing changed -- save or process    }}

Drawing Policies

canvasView.drawingPolicy = .pencilOnly

Use .default for system-standard Pencil-primary canvases when the tool picker's drawing-policy control should follow the user's Pencil preference. Use .anyInput for signature pads, whiteboards, or explicit finger-drawing modes. Use .pencilOnly when finger input should never create strokes.

Configuring the Canvas

// Set a large drawing area (scrollable)canvasView.contentSize = CGSize(width: 2000, height: 3000)
// Enable/disable the rulercanvasView.isRulerActive = true
// Set the current tool programmaticallycanvasView.tool = PKInkingTool(.pencil, color: .blue, width: 3)canvasView.tool = PKEraserTool(.vector)

PKToolPicker

PKToolPicker displays a floating palette of drawing tools. The canvas automatically adopts the selected tool.

class DrawingViewController: UIViewController {    let canvasView = PKCanvasView()    let toolPicker = PKToolPicker()
    override func viewDidAppear(_ animated: Bool) {        super.viewDidAppear(animated)        toolPicker.addObserver(canvasView)        toolPicker.setVisible(true, forFirstResponder: canvasView)        canvasView.becomeFirstResponder()    }}

Custom Tool Picker Items

Create a tool picker with specific tools. PKToolPicker(toolItems:) and custom tool picker item classes require iOS/iPadOS 18+, Mac Catalyst 18+, and visionOS 2+; those item classes are available on macOS starting in macOS 26.

let toolPicker = PKToolPicker(toolItems: [    PKToolPickerInkingItem(type: .pen, color: .black, width: 5),    PKToolPickerInkingItem(type: .pencil, color: .gray, width: 5),    PKToolPickerInkingItem(type: .marker, color: .yellow, width: 12),    PKToolPickerEraserItem(type: .vector),    PKToolPickerLassoItem(),    PKToolPickerRulerItem()])

Ink Types

Content Versions

Use Content Version Compatibility as the single version map and compatibility gate for both the canvas and tool picker.

PKDrawing Serialization

PKDrawing is a value type (struct) that holds all stroke data. Serialize it to Data for persistence.

// Savefunc saveDrawing(_ drawing: PKDrawing) throws {    let data = drawing.dataRepresentation()    try data.write(to: fileURL, options: .atomic)}
// Loadfunc loadDrawing() throws -> PKDrawing {    let data = try Data(contentsOf: fileURL)    return try PKDrawing(data: data)}

Decode Validate/Fix/Retry Loop

For synced or user-provided data: validate with PKDrawing(data:); on failure preserve the original bytes and fix the cause by refetching an intact revision or selecting a previously generated compatible copy; then retry the decode. Assign the drawing only after a successful retry. If recovery still fails, keep the source unchanged and show an error or available read-only preview instead of suppressing the failure with try?.

do {    canvasView.drawing = try PKDrawing(data: correctedData) // retry} catch {    showReadOnlyPreview(for: document, loadError: error)}

Combining Drawings

var drawing1 = PKDrawing()let drawing2 = PKDrawing()drawing1.append(drawing2)
// Non-mutatinglet combined = drawing1.appending(drawing2)

Transforming Drawings

let scaled = drawing.transformed(using: CGAffineTransform(scaleX: 2, y: 2))let translated = drawing.transformed(using: CGAffineTransform(translationX: 100, y: 0))

Content Version Compatibility

For sync, migration, downgrade, or cross-device editing tasks, use requiredContentVersion as the compatibility gate and choose an explicit maximumSupportedContentVersion when old clients must keep editing.

let targetVersion: PKContentVersion = .version1canvasView.maximumSupportedContentVersion = targetVersiontoolPicker.maximumSupportedContentVersion = targetVersion
switch drawing.requiredContentVersion {case .version1:    // Older marker, pen, and pencil ink set    syncEditable(drawing)case .version2:    // iPadOS 17-era inks: monoline, fountain pen, watercolor, crayon    syncIfRecipientsSupportVersion2(drawing)case .version3, .version4:    // Later features such as barrel-roll data and Reed Pen    syncEditableOnlyToCurrentClients(drawing)@unknown default:    showReadOnlyPreview(for: drawing)}

If a drawing requires a newer version than a recipient can load, preserve the full-fidelity PKDrawing for capable clients and provide a read-only preview or separate fallback instead of silently overwriting it. See references/pencilkit-patterns.md [blocked] for the deeper compatibility table.

Exporting to Image

Generate a UIImage from a drawing.

func exportImage(from drawing: PKDrawing, scale: CGFloat = 2.0) -> UIImage {    drawing.image(from: drawing.bounds, scale: scale)}
// Export a specific regionlet region = CGRect(x: 0, y: 0, width: 500, height: 500)let scale = UITraitCollection.current.displayScalelet croppedImage = drawing.image(from: region, scale: scale)

Stroke Inspection

Access individual strokes, their ink, and control points.

for stroke in drawing.strokes {    let ink = stroke.ink    print("Ink type: \(ink.inkType), color: \(ink.color)")    print("Bounds: \(stroke.renderBounds)")
    // Access path points    let path = stroke.path    print("Points: \(path.count), created: \(path.creationDate)")
    // Interpolate along the path    for point in path.interpolatedPoints(by: .distance(10)) {        print("Location: \(point.location), force: \(point.force)")    }}

Constructing Strokes Programmatically

Load Constructing Strokes Programmatically [blocked] only for generated ink paths; ordinary drawing and inspection do not need the advanced constructors.

SwiftUI Integration

Wrap PKCanvasView in a UIViewRepresentable for SwiftUI.

import SwiftUIimport PencilKit
struct CanvasView: UIViewRepresentable {    @Binding var drawing: PKDrawing    @Binding var toolPickerVisible: Bool
    func makeUIView(context: Context) -> PKCanvasView {        let canvas = PKCanvasView()        canvas.delegate = context.coordinator        canvas.drawingPolicy = .anyInput        canvas.drawing = drawing        context.coordinator.toolPicker.addObserver(canvas)        return canvas    }
    func updateUIView(_ canvas: PKCanvasView, context: Context) {        if canvas.drawing != drawing {            canvas.drawing = drawing        }        let toolPicker = context.coordinator.toolPicker        toolPicker.setVisible(toolPickerVisible, forFirstResponder: canvas)        if toolPickerVisible { canvas.becomeFirstResponder() }    }
    func makeCoordinator() -> Coordinator { Coordinator(self) }
    class Coordinator: NSObject, PKCanvasViewDelegate {        let parent: CanvasView        let toolPicker = PKToolPicker()
        init(_ parent: CanvasView) {            self.parent = parent            super.init()        }
        func canvasViewDrawingDidChange(_ canvasView: PKCanvasView) {            parent.drawing = canvasView.drawing        }    }}

For SwiftUI wrappers, set the input policy using the canonical Drawing Policies table.

Usage in SwiftUI

struct DrawingScreen: View {    @State private var drawing = PKDrawing()    @State private var showToolPicker = true
    var body: some View {        CanvasView(drawing: $drawing, toolPickerVisible: $showToolPicker)            .ignoresSafeArea()    }}

PaperKit Relationship

PaperKit (iOS 26+) extends PencilKit with a complete markup experience including shapes, text boxes, images, stickers, and loupes. Use the sibling paperkit skill when you need structured markup rather than only freeform drawing.

PaperKit uses PencilKit under the hood: PaperMarkupViewController accepts PKTool for its drawingTool property, and PaperMarkup can append a PKDrawing.

Common Mistakes

DON'T: Forget to call becomeFirstResponder for the tool picker

The tool picker only appears when its associated responder is first responder.

// WRONG: Tool picker never showstoolPicker.setVisible(true, forFirstResponder: canvasView)
// CORRECT: Also become first respondertoolPicker.setVisible(true, forFirstResponder: canvasView)canvasView.becomeFirstResponder()

DON'T: Create multiple tool pickers for the same canvas

One PKToolPicker per canvas. Creating extras causes visual conflicts.

// WRONGfunc viewDidAppear(_ animated: Bool) {    let picker = PKToolPicker()  // New picker every appearance    picker.setVisible(true, forFirstResponder: canvasView)}
// CORRECT: Store picker as a propertylet toolPicker = PKToolPicker()

DON'T: Ignore content versions for backward compatibility

Apply the Content Version Compatibility gate to both the canvas and tool picker before syncing editable drawings.

DON'T: Compare drawings by data representation

dataRepresentation() is for persistence and interchange, not comparison. Use PKDrawing equality for exact value checks, and inspect strokes or rendered images for visual/approximate comparisons.

// WRONGif drawing1.dataRepresentation() == drawing2.dataRepresentation() { }
// CORRECTif drawing1 == drawing2 { }

Review Checklist

• PKCanvasView.drawingPolicy follows the canonical policy table
• PKToolPicker stored as a property, not recreated each appearance
• canvasView.becomeFirstResponder() called to show the tool picker
• Canvas added as a PKToolPicker observer before showing the picker
• Drawing serialized via dataRepresentation() and loaded via PKDrawing(data:)
• canvasViewDrawingDidChange delegate method used to track changes
• maximumSupportedContentVersion set on both canvas and tool picker if backward compatibility is needed
• Custom tool picker item code guarded for iOS/iPadOS 18+ and visionOS 2+
• Exported images use appropriate scale factor for the device
• SwiftUI wrapper avoids infinite update loops by checking drawing != binding
• Drawing bounds checked before image export (empty drawings have .zero bounds)

References

• Extended PencilKit patterns (advanced strokes, content versions, delegates): references/pencilkit-patterns.md [blocked]
• PencilKit framework
• PKCanvasView
• PKDrawing
• PKToolPicker
• PKInkingTool
• PKStroke
• Drawing with PencilKit
• Configuring the PencilKit tool picker