UIKit & AppKit

TerminalView resolves to UITerminalView on UIKit and AppTerminalView on AppKit. Catalyst follows UIKit.

View setup

import GhosttyTerminal

let terminalView = TerminalView(frame: .zero)
let controller = TerminalController(configuration: .default)

terminalView.controller = controller
terminalView.configuration = TerminalSurfaceOptions(
    backend: .inMemory(session)
)
terminalView.delegate = coordinator

The view owns the native input layer and the Metal-backed surface. TerminalController owns Ghostty app lifecycle, configuration resolution, themes, and surface creation.

Delegate callbacks

Adopt the delegate protocols that match your host UI. A single coordinator object can implement multiple protocols.

final class Coordinator:
    TerminalSurfaceTitleDelegate,
    TerminalSurfaceGridResizeDelegate,
    TerminalSurfaceBellDelegate,
    TerminalSurfaceLifecycleDelegate
{
    func terminalDidChangeTitle(_ title: String) {}
    func terminalDidResize(_ size: TerminalGridMetrics) {}
    func terminalDidRingBell() {}
    func terminalDidAttachSurface(_ surface: TerminalSurface) {}
    func terminalDidDetachSurface() {}
}

iOS input

UITerminalView conforms to UITextInput. Hardware keys enter through pressesBegan, software keyboard text enters through insertText, and marked text flows through the shared IME handler.

On iOS, the input accessory bar provides Esc, Tab, arrows, symbols, Paste, and sticky Ctrl/Alt/Cmd modifiers. Configure colors through inputAccessoryStyle.

#if canImport(UIKit)
terminalView.inputAccessoryStyle = .init(
    regularBackground: .secondarySystemBackground,
    regularForeground: .label,
    activeBackground: .label,
    activeForeground: .systemBackground
)
#endif

Hosts with a custom keyboard bar can hide the bundled accessory and drive sticky modifiers through the public sticky APIs.

#if canImport(UIKit)
terminalView.inputAccessoryItems = []
#endif

The default button list is available as TerminalInputAccessoryItem.defaultItems. Hosts can provide a smaller list while keeping the bundled bar styling and key dispatch behavior.

#if canImport(UIKit)
terminalView.inputAccessoryItems = [
    .esc,
    .ctrl,
    .alt,
    .command,
    .divider,
    .tab,
    .arrowLeft,
    .arrowRight,
    .paste,
]
#endif