Understanding iOS Custom Keyboard Extensions

iOS provides a robust framework for building custom keyboard extensions that can replace or supplement the system keyboard. These extensions run as separate processes and are sandboxed, meaning they have limited access to system resources and user data. The `UIInputViewController` class is the foundation for any custom keyboard, managing input handling, view layout, and communication with the host app.

Custom keyboards can include any layout, including special characters, accented letters, emojis, or even gesture-based input. However, Apple imposes strict rules: the keyboard cannot access network resources without explicit user permission, and it must not collect keystroke data for analytics without clear consent. This ensures user privacy while still allowing flexibility for developers.

When you build a custom keyboard, you are essentially creating an app extension. The extension is packaged within a host app, and users must install that app and then enable the extension via Settings > General > Keyboard > Keyboards. Unlike Android, iOS does not allow fully replacing the system keyboard; users must switch to your keyboard manually.

For special characters, the real power lies in designing efficient access patterns. Many developers create keyboards that group symbols logically, offer long-press popups for additional variants, or provide a dedicated symbols layer. The following sections walk through every stage of creating a production-ready custom keyboard with special characters.

Setting Up the Keyboard Extension Project

Creating a custom keyboard begins inside Xcode. You need both a container app and the keyboard extension target.

Add a New Target in Xcode

Open your existing iOS project or create a new one. Go to File > New > Target, then select Custom Keyboard Extension under the Application Extension category. Give it a product name, such as “SpecialCharKeyboard.” Xcode generates a template with a `KeyboardViewController` subclass of `UIInputViewController`.

Configure Info.plist

The extension’s `Info.plist` contains two critical keys under `NSExtension`:

  • IsASCIICapable: Set to `YES` if your keyboard only uses ASCII characters; otherwise set `NO`.
  • PrefersRightToLeft: Adjust if your language reads right-to-left.
  • PrimaryLanguage: Define a language code (e.g., `en-US`).

Also add the `Privacy - Camera Usage Description` only if you include camera-based input features (rare for a keyboard). Avoid unnecessary permissions.

Understand the RequestOpenAccess Entitlement

By default, custom keyboards have no network access. If you need to download special character sets or provide cloud sync, you must add the `RequestOpenAccess` key under `NSExtensionAttributes` in `Info.plist` and set it to `YES`. However, Apple reviews apps that request open access carefully. For a keyboard focused on offline special characters, skip this key to avoid user trust issues.

Build the Basic UI

The `viewDidLoad` method inside `KeyboardViewController` is where you set up your keyboard layout. You can use a storyboard or build the interface programmatically. For a complex layout with many special characters, programmatic UI offers better control over dynamic sizing and Auto Layout constraints.

override func viewDidLoad() {
    super.viewDidLoad()
    
    // Set up the main container view
    let stackView = UIStackView()
    stackView.axis = .vertical
    stackView.distribution = .fillEqually
    stackView.spacing = 4
    stackView.translatesAutoresizingMaskIntoConstraints = false
    self.view.addSubview(stackView)
    
    NSLayoutConstraint.activate([
        stackView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 4),
        stackView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -4),
        stackView.topAnchor.constraint(equalTo: view.topAnchor, constant: 4),
        stackView.bottomAnchor.constraint(equalTo: view.bottomAnchor, constant: -4)
    ])
}

This minimal setup creates a vertical stack that will hold rows of keys.

Designing the Keyboard Layout for Special Characters

Special character keyboards require careful organization. Users need to find symbols quickly without hunting through endless key pages. Start by grouping symbols into logical categories:

  • Currency symbols: $, €, £, ¥, ₩, ₹
  • Mathematical signs: +, -, ×, ÷, =, ≠, ≈, ±, √, ∞, ∫
  • Punctuation variants: …, —, –, •, ‹, ›, «, »
  • Accented letters: á, é, í, ó, ú, ü, ñ, ç
  • Arrows and directional: ←, →, ↑, ↓, ↔, ↕

Implement two or three layout layers: a main alphabet layer with a toggle to switch to a symbols layer, and possibly a secondary layer with less common characters. Use a dedicated key (e.g., “123” or “#+=”) to switch between layers. Each layer is a separate collection of row views that you can swap via the `inputView` property or by hiding/showing views.

Long-Press Gestures for Additional Characters

If your keyboard displays a standard QWERTY layout, users expect long-press to reveal character variants. For example, long-pressing the “E” key shows “é”, “è”, “ê”, “ë”. Implement this by adding a `UILongPressGestureRecognizer` to each key. When triggered, present a popup view above the key with the available variants. The popup should be dismissed when the user lifts their finger or taps one of the variants.

Apple’s system keyboard uses an internal mechanism, but for your extension, you can use a `UIView` that appears as a floating bubble. Ensure the popup does not extend beyond the safe area and that it respects the device orientation.

Code Snippet: Adding Long Press to a Key

let longPress = UILongPressGestureRecognizer(target: self, action: #selector(handleLongPress(_:)))
longPress.minimumPressDuration = 0.3
keyButton.addGestureRecognizer(longPress)

Inside the handler, track the state `.began`, `.changed`, and `.ended` to show, update, and select from the popup.

Key Size and Spacing

iOS devices vary in screen width. Use proportional sizing: 10–12 keys per row on iPhones, and slightly more on iPads. Each key should be at least 28 points tall to meet Apple’s Human Interface Guidelines for touch targets. Set constraints so that keys shrink appropriately on smaller screens. For special characters, ensure that symbols are clearly visible; use a font size of 16–18 points for the key labels.

Handling Input with the Text Document Proxy

When a user taps a key, the keyboard must insert the character into the currently focused text field. This is done through the `textDocumentProxy` object, an instance of `UITextDocumentProxy`. The proxy provides methods like `insertText(_:)`, `deleteBackward()`, and `adjustTextPosition(byCharacterOffset:)`.

For special characters, you often need to insert multibyte glyphs (like emojis or combining diacritics). These are handled correctly by `insertText`, as long as you pass the correct Unicode string. For example, to insert the accented character “é”, call `proxy.insertText("é")`. For a combining accent like “e” with a combining acute accent (U+0301), you would insert both characters: `proxy.insertText("e\u{0301}")`. However, it is simpler to use the precomposed form: `"\u{00E9}"`.

Handling Shift and Caps Lock

Implement shift state management to toggle between uppercase and lowercase letters, and optionally uppercase symbols. When the shift key is active, your keyboard should display uppercase variants. For special characters that have case (like Greek letters), provide both. For symbols without case, the shift state can be ignored or used to display alternative symbols (e.g., shift + number key often shows the symbol above the number).

Use a boolean property `shiftActive` to track state. When the user taps the shift key, toggle it and reload the keys. For caps lock, detect a double tap on the shift key; enable a persistent caps state and show an indicator (e.g., underlined shift key).

Delete and Cursor Control

Include a delete key that calls `proxy.deleteBackward()`. For a special characters keyboard, users may need to delete entire words quickly. You can implement a “delete word” action by calling `deleteBackward()` in a loop or by using the `adjustTextPosition` method to move the cursor backward over word boundaries, then deleting. However, Apple limits how much you can manipulate the cursor via `adjustTextPosition` for privacy reasons; you cannot read the text around the cursor.

To move the cursor forward or backward, use `proxy.adjustTextPosition(byCharacterOffset: 1)` and `-1`. This is used for a “next space” or “previous space” button if you choose to include one.

Enabling and Testing the Keyboard Extension

Simulator Testing

In Xcode, run the container app on a simulator. Then go to Settings > General > Keyboard > Keyboards > Add New Keyboard and select your custom keyboard extension under the “Third-Party Keyboards” section. You may need to switch to your keyboard by tapping the globe icon when a text field is active. Debugging keyboard extensions in the simulator can be tricky because breakpoints may not always trigger. Use `NSLog` or `print` statements and check the console output.

Physical Device Testing

Device testing is essential because the simulator does not fully emulate all iOS behaviours (e.g., keyboard height constraints, auto-correction). Install the container app on a device via a development provisioning profile. Then enable the keyboard from Settings. Use Xcode’s Attach to Process feature to debug the extension: in the debug navigator, pick your extension’s process name (e.g., “SpecialCharKeyboard”).

Common Issues

  • Keyboard not appearing: Ensure the extension is properly enabled and the `RequestOpenAccess` entitlement matches your needs. Also check that the `Principal class` in `Info.plist` points to your `KeyboardViewController`.
  • Layout not sizing correctly: Override `viewWillLayoutSubviews` in your `KeyboardViewController` and update the height constraint of the view. The keyboard must conform to the system’s expected height (usually between 216 and 330 points on iPhone, and larger on iPad).
  • Input not registering: Verify that you are calling `insertText` on the correct proxy object. The proxy is available as soon as the keyboard is active.

Privacy and User Permissions

Custom keyboards are a point of concern for user privacy. Apple requires that keyboards do not collect, transmit, or store keystroke data without explicit user consent. The following guidelines are critical:

  • No network calls: Unless you have `RequestOpenAccess` enabled and the user grants permission, your extension cannot make network requests. Even with open access, you must disclose data collection in a privacy policy.
  • No clipboard access: Your keyboard cannot read the system clipboard. Only the host app can access the clipboard, and only when the app is active.
  • No analytics of keystrokes: You cannot log which keys are pressed. If you need to learn user preferences (e.g., frequently used symbols), store that data only locally with a clear explanation and an opt-out option.
  • Provide a toggle for data collection: If your keyboard uses networking for special character updates, include a switch in the container app to enable/disable it, and respect the user’s choice.

When users enable your keyboard, iOS displays a warning that the keyboard could collect all keystrokes. Your app’s reviews and ratings will suffer if users feel their data is at risk. Be honest and transparent in your App Store description and inside the container app.

Design Tips for Special Character Access

Organize Symbols for Fitts’ Law

Place the most frequently used special characters near the center of the keyboard or on the bottom row for easier thumb reach. For example, if your target audience often types currency, put $, €, and £ on the home row of the symbols layer. Group similar symbols together to reduce cognitive load.

Use Visual Feedback

When a key is pressed, show a brief popup (like the system keyboard’s character preview) to confirm the input. This is especially helpful for tiny symbols. Implement a custom `UIControl` for each key that responds to the touch down event and displays a magnified version of the character above the key.

Include an Auto-Advance Feature for Symbols

After inserting a special character, many users expect the keyboard to automatically return to the letters layer. You can toggle this behavior with an option in the container app. This makes typing a mixture of letters and symbols faster.

Support Accessibility

Ensure that VoiceOver can read all keys. Set `accessibilityLabel` on each key button to the character or its name (e.g., “asterisk” for *). For symbolic keys where the glyph is not obvious, provide a spoken description. Also support dynamic type so that users with large text settings can see the symbols clearly.

Additional Considerations

Performance Optimization

Keyboard extensions run in a memory-constrained environment. Avoid loading heavy images or complex animations. Use lightweight `UIButton` subclasses or `UICollectionView` for efficient reuse. On older devices, rendering a full grid of 30+ keys should be smooth. Profile your extension with Instruments to check for frame drops.

Localization

If your keyboard supports multiple languages, consider providing localized symbol sets. For example, a French user might need « », while a German user needs ß and Ä, Ö, Ü. Use the `PrimaryLanguage` key in `Info.plist` to hint at the default language, but let users switch via the container app. Store the selected layout in `UserDefaults` with a shared suite (using App Groups) so the extension can read the preference.

App Store Review

Apple reviews custom keyboard extensions more strictly than normal apps. Ensure your keyboard does not crash, does not include offensive content, and does not circumvent system restrictions. Avoid ad banners or promotional overlays on the keyboard itself. If your keyboard requires network access for any reason, be prepared to justify it during the review process.

Updates and Maintenance

New iOS versions may change how keyboard extensions interact with the system. Test your extension on beta releases and update `UIInputViewController` method implementations as needed. For example, iOS 16 introduced new keyboard layout APIs for taller keyboards on iPads. Keep an eye on Apple’s release notes.

Conclusion

Implementing a custom keyboard with special characters on iOS is a powerful way to improve typing efficiency for users who need symbols, accented letters, or emojis that the system keyboard does not surface immediately. By building a keyboard extension with carefully designed layouts, intuitive long-press access, and robust input handling, you can deliver a seamless experience. Prioritize privacy, adhere to Apple’s guidelines, and thoroughly test on real devices to ensure reliability. With the right design, your custom keyboard can become an essential tool for multilingual users, developers, writers, and anyone who frequently types non-standard characters.

For further reading, consult the official Apple documentation on Creating a Custom Keyboard, the App Extension Programming Guide, and the Human Interface Guidelines for Keyboards.