/pencilkit

name: pencilkit
description: "Add Apple Pencil drawing with PKCanvasView, PKToolPicker, PKDrawing serialization/export, stroke inspection, and PencilKit/PaperKit handoffs. Use when building drawing apps, annotation features, handwriting capture, signature fields, content-version-safe ink workflows, or Apple Pencil-powered experiences on iOS/iPadOS/visionOS."

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](#setup)
• [Capture-to-Export Workflow](#capture-to-export-workflow)
• [PKCanvasView Basics](#pkcanvasview-basics)
• [PKToolPicker](#pktoolpicker)
• [PKDrawing Serialization](#pkdrawing-serialization)
• [Content Version Compatibility](#content-version-compatibility)
• [Exporting to Image](#exporting-to-image)
• [Stroke Inspection](#stroke-inspection)
• [SwiftUI Integration](#swiftui-integration)
• [PaperKit Relationship](#paperkit-relationship)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#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](#decode-validatefixretry-loop). Do not mark bytes valid when `PKDrawing(data:)` still throws. 3. **Version-gate:** Apply [Content Version Compatibility](#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 PencilKit
import 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

| Policy | Behavior | |---|---| | `.default` | Respects `UIPencilInteraction.prefersPencilOnlyDrawing` when the tool picker is visible; otherwise Pencil-only | | `.anyInput` | Both pencil and finger draw | | `.pencilOnly` | Only Apple Pencil touches draw on the canvas |

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 ruler
canvasView.isRulerActive = true

// Set the current tool programmatically
canvasView.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

| Type | Description | |---|---| | `.pen` | Smooth, pressure-sensitive pen | | `.pencil` | Textured pencil with tilt shading | | `.marker` | Semi-transparent highlighter | | `.monoline` | Uniform-width pen | | `.fountainPen` | Variable-width calligraphy pen | | `.watercolor` | Blendable watercolor brush | | `.crayon` | Textured crayon | | `.reed` | Reed pen (iOS/iPadOS/macOS/visionOS 26+) |

Content Versions

Use [Content Version Compatibility](#content-version-compatibility) as the single version map and compatibility gate for both the canvas and tool picker.

PKDrawing Serialization

`PKDrawin