# React Native CodePad

> A native code editor for React Native, with its own Kotlin and Swift engines, tree-sitter highlighting and a Nitro binding. No WebView.

This file contains all documentation content in a single document following the llmstxt.org standard.

## AI coding agents

CodePad ships an agent skill and a plain text copy of these docs, so a coding agent can add an editor to your app without guessing the API.

### Agent skill

The skill shows an agent how to install CodePad and set up `CodeEditor`, and lists the mistakes that come from treating the editor as a `TextInput`. Install it in your project with the `skills` command-line tool:

```sh
npx skills add SectionTN/react-native-codepad
```

The command prompts for the agents to set it up for. Agents that read the Agent Skills format, such as Claude Code, Codex and Cursor, load it when a task mentions a code editor, `CodeEditor` or a language package.

The skill covers installation, the props, ref methods and events, themes, search, the keyboard toolbar and an editor nested in a `ScrollView`. For anything else it sends the agent to `node_modules/react-native-codepad/src/types.ts`, which ships with the package and always matches the installed version.

Run `npx skills update` to get the latest version of the skill.

### Plain text docs

The site publishes the docs as plain text for agents and chat tools that read a URL:

- [`llms.txt`](https://reactnativecodepad.pages.dev/llms.txt) lists every page with a one-line description.
- [`llms-full.txt`](https://reactnativecodepad.pages.dev/llms-full.txt) contains every page in one file.

Give an agent the second URL when you want it to answer from the whole documentation.

---

## Hardware keyboard

CodePad handles the keys below from any hardware keyboard: Bluetooth or USB, a Chromebook, an iPad keyboard, or the Mac keyboard on the simulator. Every other key goes to the platform, and printable keys type through the normal path, with auto close and typing coalescing.

| Action | Android | iOS |
| --- | --- | --- |
| Move by one grapheme cluster | Left, Right | Left, Right |
| Move by one word | Ctrl+Left, Ctrl+Right | Option+Left, Option+Right |
| Move by one visual row, keeping the goal column | Up, Down | Up, Down |
| Move by one viewport height | Page Up, Page Down | Page Up, Page Down |
| Line start, line end | Home, End | Home, End, Cmd+Left, Cmd+Right |
| Document start, document end | Ctrl+Home, Ctrl+End | Cmd+Home, Cmd+End, Cmd+Up, Cmd+Down |
| Extend the selection | Shift with any of the above | Shift with any of the above |
| Newline through the indenter | Enter, numpad Enter | Enter |
| Indent the caret or the selected lines | Tab | Tab |
| Outdent the selected lines | Shift+Tab | Shift+Tab |
| Delete backward (an empty auto closed pair goes in one go) | Backspace | Backspace |
| Delete forward | Delete | Forward Delete (Fn+Delete on a Mac keyboard) |
| Undo | Ctrl+Z | Cmd+Z |
| Redo | Ctrl+Shift+Z, Ctrl+Y | Shift+Cmd+Z |
| Select all | Ctrl+A | Cmd+A |
| Copy, cut, paste | Ctrl+C, Ctrl+X, Ctrl+V, the dedicated keys | Cmd+C, Cmd+X, Cmd+V |
| Collapse the selection to the caret | Escape | Escape |

Under `readOnly`, movement, selection, select all, copy and Escape still work, and the editing keys do nothing. Word movement uses runs of `[A-Za-z0-9_]` and falls back to the platform's word breaks. A paste reports origin `input` in `onChange`, and undo and redo report `undo` and `redo`.

Android leaves Alt and Meta combinations and Ctrl+Tab to the platform. iOS leaves Control combinations, and Option with any key other than Left and Right, to UIKit. The editor's commands win over UIKit's own text navigation.

### The undo stack on iOS

The editor's history is the responder chain's `undoManager`, so Cmd+Z, shake to undo and the three finger gestures run the same undo groups as `undo()` and `redo()`. On Android the history is reached through the key table and the ref.

### The same table from JavaScript

`moveCaret(direction, { select })` drives the movement rows, so a toolbar can match the keyboard:

| Direction | Android | iOS |
| --- | --- | --- |
| `left`, `right` | Left, Right | Left, Right |
| `wordLeft`, `wordRight` | Ctrl+Left, Ctrl+Right | Option+Left, Option+Right |
| `lineStart`, `lineEnd` | Home, End | Home, End |
| `documentStart`, `documentEnd` | Ctrl+Home, Ctrl+End | Cmd+Home, Cmd+End |
| `up`, `down` | Up, Down | Up, Down |
| `pageUp`, `pageDown` | Page Up, Page Down | Page Up, Page Down |

`typeText('\n')`, `indent()`, `outdent()`, `deleteBackward()` and `deleteForward()` cover Enter, Tab, Shift+Tab, Backspace and Delete. The [keyboard guide](/guides/keyboard/) has the toolbar recipe.

### Testing without a keyboard

On an Android emulator with `hw.keyboard=yes` the host keyboard types into the editor, and `adb shell input keyevent` sends keys from a script. On the iOS simulator the Mac keyboard types into the editor, and with Connect Hardware Keyboard on, Cmd and Option chords reach the table.

---

## Keyboard

Three things keep the caret visible while the soft keyboard is up: `avoidKeyboard`, `contentInsets` for anything you draw over the editor, and a toolbar pinned to the keyboard. The example app's key row uses all three.

### `avoidKeyboard`

```tsx
<CodeEditor style={{ flex: 1 }} avoidKeyboard />
```

The editor measures how much the keyboard overlaps it on every frame of the keyboard animation and adds that to its bottom inset, so the content slides up with the keyboard and back down when it closes. A keyboard opened for another field insets the editor too.

On Android the prop does nothing in two window modes, on purpose:

- `adjustPan`: the framework pans the window, and an inset would move the content twice.
- `adjustResize` without edge to edge: the window already shrank. React Native is edge to edge since 0.81.

`onContentSizeChange` never includes the keyboard overlap. The prop is off by default on both platforms.

### `contentInsets`

Style padding on the view is ignored. `contentInsets` is the padding instead: inside the scrollable area, in dp on Android and points on iOS. A bottom inset keeps the caret above a toolbar or a floating button.

```tsx
// Hoisted: object props are compared by identity.
const INSETS = { bottom: 56 };

<CodeEditor style={{ flex: 1 }} contentInsets={INSETS} avoidKeyboard />;
```

With `avoidKeyboard` on, the keyboard overlap is added on top of `contentInsets.bottom`. You pass the toolbar height, the editor adds the keyboard.

### A toolbar on the keyboard

For a toolbar that rides the keyboard, use [react-native-keyboard-controller](https://kirillzyusko.github.io/react-native-keyboard-controller/). Its `KeyboardStickyView` keeps the bar on top of the keyboard through the whole animation. The example app pins its key row and status bar that way: the editor takes the bar's height as its bottom inset, and while the keyboard is closed the bar is above the home indicator, so the inset covers that band too.

```tsx
import { useMemo, useRef, useState } from 'react';
import { StyleSheet, View } from 'react-native';
import { CodeEditor, type CodeEditorRef } from 'react-native-codepad';
import { KeyboardStickyView, useKeyboardState } from 'react-native-keyboard-controller';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import { EditorToolbar } from './EditorToolbar';

export function ToolbarScreen() {
  const editor = useRef<CodeEditorRef>(null);
  const [toolbarHeight, setToolbarHeight] = useState(0);
  const keyboardVisible = useKeyboardState((s) => s.isVisible);
  const safe = useSafeAreaInsets();
  // The editor adds the keyboard overlap itself; the home indicator only matters while the keyboard is closed.
  const lift = keyboardVisible ? 0 : safe.bottom;
  const insets = useMemo(() => ({ bottom: toolbarHeight + lift }), [toolbarHeight, lift]);
  const offset = useMemo(() => ({ closed: -safe.bottom, opened: 0 }), [safe.bottom]);
  return (
    <View style={styles.screen}>
      <CodeEditor
        ref={editor}
        style={styles.editor}
        language="javascript"
        avoidKeyboard
        contentInsets={insets}
      />
      <KeyboardStickyView offset={offset} style={styles.sticky}>
        <EditorToolbar
          editor={editor}
          onLayout={(e) => setToolbarHeight(e.nativeEvent.layout.height)}
        />
      </KeyboardStickyView>
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1 },
  editor: { flex: 1 },
  sticky: { position: 'absolute', left: 0, right: 0, bottom: 0 },
});
```

If you build the key row with a React Native `ScrollView`, set `keyboardShouldPersistTaps="always"` so tapping a key does not dismiss the keyboard. Each key calls the ref:

| Key | Call |
| --- | --- |
| Arrows, Home, End | `moveCaret(direction, { select })` |
| Tab, Untab | `indent()`, `outdent()` |
| Enter | `typeText('\n')` |
| Symbols such as `{` or `"` | `typeText(symbol)` |
| Backspace | `deleteBackward()` |
| Undo, Redo | `undo()`, `redo()`, enabled from `canUndo()` and `canRedo()` read in `onChange` |
| Hide | `blur()` |

`typeText()` and `deleteBackward()` take the keyboard path: auto close, the indenter, typing coalesced in the undo history, origin `input`, and no-ops under `readOnly`. `insertText()` is the raw path. The example's key row is in the repository under `example/src/components/AccessoryBar.tsx`, and `BottomBar.tsx` next to it pins it to the keyboard.

### Suggestions and focus

`suggestions` controls what the keyboard offers: `off` (the default) asks for no suggestions, `forceOff` also kills composition on most Android keyboards, and `on` allows autocorrect. Code wants `off`. A Markdown editor might want `on`. On iOS `forceOff` is the same as `off`. Composing keyboards (Japanese, Chinese) work in every mode.

`autoFocus` focuses the editor once the view is attached. `focus()` and `blur()` do it on demand, and `focus()` doesn't open the keyboard under `readOnly`.

---

## Languages

Each language is a compiled tree-sitter grammar plus the nvim-treesitter queries, shipped as its own npm package. The core has no language built in, so without a package every document is plain text.

### Packages and ids

| `language` | Package |
| --- | --- |
| `c` | `react-native-codepad-lang-c` |
| `css` | `react-native-codepad-lang-css` |
| `go` | `react-native-codepad-lang-go` |
| `html` | `react-native-codepad-lang-html` |
| `java` | `react-native-codepad-lang-java` |
| `javascript` | `react-native-codepad-lang-javascript` |
| `json` | `react-native-codepad-lang-json` |
| `kotlin` | `react-native-codepad-lang-kotlin` |
| `markdown` | `react-native-codepad-lang-markdown` |
| `python` | `react-native-codepad-lang-python` |
| `rust` | `react-native-codepad-lang-rust` |
| `swift` | `react-native-codepad-lang-swift` |
| `tsx` | `react-native-codepad-lang-tsx` |
| `typescript` | `react-native-codepad-lang-typescript` |
| `yaml` | `react-native-codepad-lang-yaml` |

Pass the id as `language`. The [language packages reference](/reference/languages/) lists each grammar's revision and capture names.

Use `markdown`, not `markdown_inline`: the inline grammar is reached through injection.

`Codepad.availableLanguages()` lists the installed packages:

```ts
import { Codepad } from 'react-native-codepad';

const installed = Codepad.availableLanguages();
// ['javascript', 'markdown', 'markdown_inline', ...]
```

### Plain text fallback

A `language` with no installed package renders as plain text in `foreground` and logs one warning. It doesn't throw. Switching `language` on a live editor reparses the document.

### Injections

A grammar's injection query hands ranges to another language: fenced blocks in Markdown, `<script>` and `<style>` in HTML, `css` and `html` tagged templates in JavaScript, Markdown front matter. The name comes from the document or from the query, is converted to lowercase, and goes through this table before the registry looks for a package:

| Name in the source | Resolves to |
| --- | --- |
| `js`, `jsx`, `mjs`, `cjs` | `javascript` |
| `ts`, `mts`, `cts` | `typescript` |
| `py`, `python3` | `python` |
| `kt`, `kts` | `kotlin` |
| `rs` | `rust` |
| `golang` | `go` |
| `yml` | `yaml` |
| `jsonc`, `json5` | `json` |
| `htm`, `xhtml` | `html` |
| `md` | `markdown` |
| `h` | `c` |

A name with no package keeps the host language's colors. A name from nvim-treesitter's list (`cpp`, `bash`, `sh`, `sql`, `graphql`, `text` and the rest) doesn't log a warning. Any other name logs the fallback warning once.

- Injections go one level deep: a JavaScript block inside Markdown highlights, an HTML template inside that block does not.
- `${...}` substitutions inside a tagged template are parsed by the injected language.
- Injected trees survive edits and reparse only when their own range changed. The [performance guide](/guides/performance/) has the numbers.

### Size

One native library per ABI, loaded on first use. On `arm64-v8a` in a release build:

| Package | Library |
| --- | --- |
| `kotlin` | 5.5 MB |
| `swift` | 4.0 MB |
| `tsx`, `typescript` | 1.4 MB each |
| `rust` | 1.1 MB |
| `markdown` | 0.7 MB |
| `c` | 0.6 MB |
| `java`, `javascript`, `python` | 0.4 MB each |
| `go`, `yaml` | 0.2 MB each |
| `css` | 0.1 MB |
| `html`, `json` | under 0.1 MB |

An app bundle splits libraries per ABI, so a device downloads one set.

### Adding a language

Packages are generated from `languages/grammars.json` in the repository, never written by hand:

1. Add an entry: the id (it must match the nvim-treesitter query directory), the grammar repository and commit, and the grammar directories.
2. Run `yarn gen:languages <id>`. It fetches the grammar and the queries, translates the predicates and writes the package. Patterns it cannot translate are dropped with a warning each, and `yarn gen:report` lists every predicate per language.
3. Run `yarn host:treesitter && yarn test:android` to compile the queries against the parser on the JVM.
4. Run `yarn test:device -e class codepad.example.LanguagesTest` to load the package through the real view on an emulator.

CI regenerates every package and fails on any diff. A grammar bump is a `rev` change followed by the same steps.

A third party package works when it follows the convention: the npm name `react-native-codepad-lang-<id>`, a Kotlin `LanguageProvider` at `me.sectiontn.codepad.lang.<id>` with a keep rule, an asset marker at `codepad-languages/<id>`, and a parser built against tree-sitter 0.26 (ABI 13 to 15).

---

## Nested in a ScrollView

A form, a note, a snippet in a list: sometimes the editor sits in a page that scrolls and must not scroll on its own. Two props and one event do it.

```tsx
import { useState } from 'react';
import { ScrollView, TextInput } from 'react-native';
import { CodeEditor } from 'react-native-codepad';

export function NotePage() {
  const [height, setHeight] = useState(120);
  return (
    <ScrollView keyboardShouldPersistTaps="handled">
      <TextInput placeholder="Title" />
      <CodeEditor
        style={{ height }}
        language="markdown"
        softWrap
        scrollEnabled={false}
        onContentSizeChange={(e) => setHeight(Math.ceil(e.height))}
      />
      <TextInput placeholder="Tags" />
    </ScrollView>
  );
}
```

- `scrollEnabled={false}` means the view never claims touch scrolling, so a drag over it scrolls the page. Taps, long presses and handle drags still work.
- `softWrap` keeps the content within the page width.
- `onContentSizeChange` reports the size at which nothing scrolls, insets included. Feed its height back into `style`. With soft wrap a tall document converges over a few frames as lines are measured, and `Math.ceil` avoids a one pixel scroll.
- `keyboardShouldPersistTaps="handled"` lets a tap place the caret without the page dismissing the keyboard first.

### Caret reveal is yours

The editor cannot scroll the page. In `onSelectionChange`, read `getCursorRect()` (view coordinates, in dp), add the editor's offset in the page from its `onLayout`, and scroll the page when the caret leaves the visible band:

```tsx
onSelectionChange={() => {
  const rect = editor.current?.getCursorRect();
  if (!rect) return;
  const y = editorTop + rect.y;
  if (y < pageScrollY || y + rect.height > pageScrollY + pageHeight) {
    page.current?.scrollTo({ y: y - pageHeight / 2, animated: true });
  }
}}
```

Leave `avoidKeyboard` off here: an editor that does not scroll has nothing to inset. Let the page handle the keyboard with a `KeyboardAvoidingView` or keyboard-controller's `KeyboardAwareScrollView`.

### Keep nested documents small

An auto height editor lays out and draws every line. A few hundred lines is fine, a 10k line file belongs in a scrolling editor with a fixed height.

---

## Performance

CodePad is built to handle large files without making every keystroke or scroll more expensive as the document grows.

This guide covers how the editor handles large documents, what to watch out for when using its API, and how to run the benchmarks yourself.

### Large files

Opening a large file takes time. CodePad has to parse the document, calculate syntax highlighting and lay out the text before it can display everything correctly.

CodePad runs parsing separately from rendering and can display text before syntax highlighting is ready. It also updates syntax incrementally, so editing a line doesn't require parsing the entire document again.

Here are some results from the Android benchmark suite on the `debugOptimized` variant:

- Opening a 10,000-line file took 27-35 ms.
- Opening a 100,000-line file took 143-181 ms.
- Scrolling through a 10,000-line file produced 2 janky frames out of 832.
- Scrolling through a 100,000-line file while its initial parse was running produced 4 janky frames out of 829.
- Typing in a 10,000-line file took 5-11 ms for key handling and drawing.

These measurements were taken on an Android emulator running API 36, using `-gpu host` on an M1 Pro chip for GPU acceleration through MoltenVK. The app used the `debugOptimized` build with Metro attached. Results will vary by device and build configuration.

#### Markdown and injected grammars

Markdown is more expensive to parse than it might look. A document can contain inline grammar rules, fenced code blocks and language-specific syntax inside those blocks.

We tested a Markdown document containing 2,000 paragraphs, 5,880 lines and 2,239 grammar injections.

When every edit reparsed all injected grammars, updating syntax after a keystroke took 146-165 ms in the measured runs. With CodePad's incremental parsing, warm updates took around 3-4 ms.

The initial parse still has a cost. The difference shows up when editing: CodePad can reuse unaffected syntax information instead of recalculating everything.

### API usage

#### Avoid copying the entire document on every change

`onChangeText` gives you the updated document as a string. For large files, retrieving that string on every edit means repeatedly copying the entire document.

Use `onChange` when you only need to know what changed. It provides the edit delta, so you can react to a modification without reading the whole file.

```tsx
<CodeEditor
  onChange={(change) => {
    // Handle the edit without copying the full document.
  }}
/>
```

Use `getText()` when you actually need the complete document, such as when saving or exporting it.

#### Read only the text you need

Calling `getText()` creates a copy of the document. This can become expensive when the file contains hundreds of thousands of lines.

For smaller reads, use `getLine()` or `getTextInRange()` instead.

For example, a feature that needs the current line doesn't need to retrieve the entire document just to extract it.

#### Keep object props stable

Passing a newly created object on every React render can cause unnecessary updates to the native editor.

This applies to props such as `theme` and `contentInsets`. Keep their references stable when their values haven't changed.

```tsx
const theme = {
  // Your theme configuration
};

const contentInsets = {
  // Your inset configuration
};
```

For configuration that depends on component state, use `useMemo` where appropriate.

#### Be careful with automatic height

An editor with automatic height needs to lay out all its lines. A fixed-height editor can focus its layout work on the visible viewport.

For large documents, prefer a constrained editor. Automatic height is better suited to smaller amounts of text.

Soft wrapping also requires measuring visible lines against the available width. When the width changes, such as after rotating a device, those lines need to be laid out again.

#### Avoid expensive work in frequent callbacks

`onScroll` and `onSelectionChange` are coalesced to at most one event per frame.

Keep these callbacks lightweight. Updating React state is fine when needed, but avoid running expensive document operations or unrelated computations on every event.

#### Account for language initialization

The first editor opened for a language needs to load its language library and compile its queries. Later editors using the same language in that process can reuse the initialized resources.

Keep this in mind when measuring startup performance. A first run and a subsequent run don't necessarily have the same cost.

### Searching large documents

Search performance depends on the document and the number of matches.

In the 100,000-line benchmark, literal search found 274,316 matches in 165 ms. Regex search found 54,864 matches in 103 ms.

Memory usage is another consideration. Loading the 100,000-line document increased Java heap usage by 14.3 MB for 6.6 MB of text.

These are benchmark results, not fixed limits. Use your own documents when evaluating search and memory performance in your application.

### iOS

The iOS editor uses the same general approach: recycled line layers, cached layout around the viewport, and parsing on a separate queue.

In the iOS simulator, typing in a 10,000-line document took around 3 ms for key handling and layout. Measuring through the end of drawing increased that to around 11 ms in the typical case.

Simulator results are useful for checking regressions, but they don't guarantee the same performance on a physical iPhone. If you have one, numbers from it are welcome in an issue.

### Running the benchmarks

With the example app running on an Android emulator, run from the repository root:

```sh
yarn bench:scroll
yarn bench:memory
yarn bench:typing
```

For iOS:

```sh
yarn bench:ios scroll
yarn bench:ios memory
yarn bench:ios typing
```

When comparing results, keep the device, build configuration and test conditions consistent. Run each test more than once, and distinguish first-run costs from subsequent runs.

A change that improves one benchmark may affect another. Check typing, scrolling, memory and first paint together before deciding whether an optimization is worth keeping.

Also, make sure you test on AC power, for full performance. On battery, macOS throttles the emulator.

---

## Search

Search runs in the native engine. You set a query, the editor paints every match and keeps them current through edits, and the ref walks and replaces them. A search bar in JavaScript is a few async calls.

### Query

```ts
const { count } = await editor.current.setSearch({
  text: 'readFile',
  regex: false,
  caseSensitive: false,
  wholeWord: false,
});
```

`setSearch` resolves with the match count once the matches are painted.

- `regex` uses ICU on both platforms (`java.util.regex` on Android, `NSRegularExpression` on iOS), so Unicode `\w` and `\b`, lookahead, bounded lookbehind and named groups behave the same. A pattern that does not compile rejects the promise and clears the search, so your bar can show the error while the user keeps typing.
- `caseSensitive` is off by default.
- `wholeWord` wants identifier boundaries (`[A-Za-z0-9_]`) on both ends.

Matches never overlap and empty matches are skipped, so `a*` on `aaa` is one match. The replacement text is literal: no `$1`.

### Walking the matches

`findNext()` and `findPrevious()` select the next or previous match from the caret, wrapping around, reveal it, and resolve with `{ index, total }` (`index` is 0 based). Without a query or without matches they resolve with `null`. Right after `setSearch`, `findNext()` lands on the match nearest the caret.

```ts
const hit = await editor.current.findNext();
setLabel(hit ? `${hit.index + 1}/${hit.total}` : '0/0');
```

### Replacing

`replaceCurrent(text)` replaces the selected match, selects the next one and resolves with `true`. When the selection is not a match it resolves with `false` and doesn't change the document, so call `findNext()` first. `replaceAll(text)` replaces every match in one undo group and resolves with the count.

`clearSearch()` drops the query and the highlights. Search and replace work under `readOnly`, which only blocks user input.

### Painting

Matches are filled with the theme's `searchMatch`, the selected one with `searchMatchActive`. After an edit the previous matches remain painted, shifted through the change, until the fresh ones arrive on the next frame.

### A find bar

The example app's find bar is one effect per query change and a few buttons. The `live` flag drops a stale result when the query changed while a search was running.

```tsx
useEffect(() => {
  let live = true;
  (async () => {
    if (!text) {
      await editor.current?.clearSearch();
      if (live) setMatch({ index: 0, count: 0 });
      return;
    }
    try {
      const result = await editor.current?.setSearch({ text, regex, caseSensitive, wholeWord });
      if (!live || !result?.count) return;
      const hit = await editor.current?.findNext();
      if (live && hit) setMatch({ index: hit.index + 1, count: hit.total });
    } catch (e) {
      if (live) setError(e instanceof Error ? e.message : String(e));
    }
  })();
  return () => {
    live = false;
  };
}, [text, regex, caseSensitive, wholeWord]);
```

The full component is in the repository under `example/src/components/FindBar.tsx`. A literal query with a quarter million matches on a 100,000-line file resolves in under 200 ms. The [performance guide](/guides/performance/) has the numbers.

---

## Themes

CodePad ships with 3 themes: `githubLight` (the default), `githubDark` and `oneDark`. Each one is a plain object passed as `theme`.

```tsx
import { useColorScheme } from 'react-native';
import { CodeEditor, githubDark, githubLight } from 'react-native-codepad';

export function Editor() {
  const scheme = useColorScheme();
  return <CodeEditor style={{ flex: 1 }} theme={scheme === 'dark' ? githubDark : githubLight} />;
}
```

### The shape

```ts
interface Theme {
  background: string;
  foreground: string;
  gutterBackground: string;
  gutterForeground: string;
  gutterActiveForeground: string;
  activeLine: string;
  selection: string;
  cursor: string;
  matchingBracket: string;
  searchMatch: string;
  searchMatchActive: string;
  tokens: Record<string, TokenStyle>;
}

type TokenStyle = string | { color: string; bold?: boolean; italic?: boolean };
```

Colors are `#rrggbb` or `#rrggbbaa`. `selection`, `matchingBracket`, `searchMatch` and `searchMatchActive` are drawn under the text, so give them some alpha. The [theme tokens reference](/reference/theme-tokens/) lists every value of the three themes.

### Token lookup

`tokens` is keyed by tree-sitter capture names such as `keyword`, `keyword.return`, `punctuation.bracket` or `markup.heading.1`. The lookup walks the dotted prefixes from the longest one down and ends at `foreground`, so a theme only needs the root names and can add a leaf wherever it wants a distinction.

The built-in themes cover every capture the fifteen packages produce. A theme from the nvim-treesitter ecosystem ports by renaming its keys: `@keyword.return` becomes `keyword.return`.

### A custom theme

Spread a built-in theme and override what you want:

```ts
import { githubDark, type Theme } from 'react-native-codepad';

export const midnight: Theme = {
  ...githubDark,
  background: '#000000',
  gutterBackground: '#000000',
  tokens: {
    ...githubDark.tokens,
    keyword: { color: '#ff9bce', bold: true },
    'string.regexp': '#ffd27f',
    comment: { color: '#6b7280', italic: true },
  },
};
```

Hoist the object out of the render. The prop is compared by identity, so a literal written in JSX crosses to native on every render.

A theme built from scratch needs the root names: `comment`, `keyword`, `string`, `number`, `function`, `variable`, `type`, `operator`, `punctuation`, `tag`, `attribute`, `constant`, `boolean`, `property`, `module`, `label`, `constructor`, `character` and the `markup.*` keys. A missing root paints in `foreground`.

Bold and italic need a font that has those faces. The defaults, `monospace` on Android and `Menlo` on iOS, do.

---

## Architecture

The editor engine is written twice, in Kotlin and in Swift, with the same layers, the same names and the same test vectors, and it is bound to React Native through Nitro Views. The TypeScript wrapper, the tree-sitter runtime, the grammars and the vectors are shared.

### Why an own engine

A `TextInput` is one field stretched over a document: no gutter, no horizontal scroll, no control over undo and a layout of the whole text on every edit. A WebView pays a bridge and a second runtime per keystroke. The engine stores the document and draws through the platform's text layout API (`StaticLayout` on Android, Core Text on iOS), one visible line at a time. The soft keyboard talks to it through the platform's input protocol, so composition, suggestions and swipe typing work as in any text field.

### Layers

Under `me.sectiontn.codepad` in `android/src/main/java`:

| Layer | Holds | Depends on |
| --- | --- | --- |
| `core` | `Document`, `UndoManager`, `TextMovement`, `Indenter`, `AutoCloser`, `BracketMatcher`, `Searcher`, in pure Kotlin. | nothing |
| `input` | `ImeSession`, the keyboard protocol, and `KeyCommands`, the hardware key table. | core |
| `syntax` | `SyntaxEngine` and its thread, the tree-sitter JNI binding, `LanguageRegistry`, `Highlighter`, the per line span cache. | core |
| `layout` | `LineLayout` over `StaticLayout`, `HeightMap`, `LayoutCache`, `Viewport`, `CaretMover`, `GutterMetrics`. | core, syntax |
| `view` | `CodeEditorView`: drawing, gestures, scrolling, the input connection, handles, the edit menu, the keyboard inset tracker. | every layer before it |
| `com.margelo.nitro.codepad` | `HybridCodeEditorView` and `HybridCodepad`, the Nitro layer. | view |

The core runs `tests/vectors/*.json` on the JVM and under `swift test`. The keyboard protocol replays recordings: `tests/ime/*.json` from real Gboard sessions through `ImeSession`, and `tests/ime-ios/*.json` from the iOS keyboard through `MarkedTextSession`. A keyboard bug gets a recording before a fix.

#### `core`

The document is an array of lines, each a growable UTF-16 buffer. `\r\n` and a `\r` on its own become `\n` on load. `replace(start, end, text)` is the only mutation. Undo groups hold the inverse changes plus the selection before and after. Single character typing merges into the previous group when it is adjacent, within a second and not a newline. API edits never merge with typing.

#### `syntax`

One serial thread per editor holds the parser and the live tree. It applies each edit, reparses incrementally, reconciles the injected trees against the ranges tree-sitter reports as changed, and publishes an immutable snapshot to the main thread. The first parse of a large file runs with a time budget and resumes, and an edit during a parse cancels it.

The main thread queries the published snapshot for the visible lines only and caches the spans per line. A snapshot lists the regions whose structure changed, so the painter re-queries only the visible lines inside those regions. Overlapping captures apply in pattern order and the later pattern takes precedence, which is the rule nvim queries are written for.

#### `layout`

`LineLayout` turns a line into a `StaticLayout` at the wrap width. The row height is uniform, `round(fontSize * lineHeight)`, so a fallback font for emoji or CJK never changes it. `HeightMap` stores a row count per line, with unmeasured lines counting as one. `LayoutCache` is an LRU around the viewport. Only a wrap width change drops it, and the scroll is then re-anchored to the top visible line.

#### `view`

`CodeEditorView` is an `android.view.View` with an input connection, so the input method treats it as a text editor. It draws in this order: background, active line, search matches, bracket pair, selection, text, composing underline, gutter, caret, handles, placeholder. The view blocks its parent from intercepting touches only when it can scroll in the drag direction, which lets a parent `ScrollView` take over. Its input connection is a `BaseInputConnection` subclass over the document. The keyboard inset tracker registers a window insets animation callback when `avoidKeyboard` is on.

### The same engine in Swift

`ios/Codepad/` mirrors the Kotlin layers file for file:

| Layer | Holds | Differs from Android |
| --- | --- | --- |
| `core` | The same files, lines as `[UInt16]`, the document lock a `pthread_rwlock_t`. | Foundation only. Regular expressions through `NSRegularExpression`. |
| `input` | `KeyCommands` with the Mac modifiers, `GestureMachine`, `MarkedTextSession` (the `UITextInput` composition logic). | A long press places the caret under the loupe, a triple tap selects the line. |
| `syntax` | `TreeSitter.swift` over the C API, `SyntaxEngine` on a serial queue, `LanguageRegistry`, `Highlighter`, `SearchController`. | No JNI: the parser reads a `[UInt16]` mirror through a C callback. |
| `layout` | `LineLayout` over Core Text, `ThemeColors` as `CGColor`s, the rest one to one. | Tests on macOS. |
| `view` | `CodeEditorView`, a `UIScrollView`. `TextInputView`, the `UITextInput` conformer. The recycled `LineLayer`s, the highlight, cursor and handle views, the gesture recognizer, the edit menu, the keyboard inset tracker and the undo manager bridge. | UIKit, on the main actor, tested by XCTest on the simulator. |
| `nitro` | `HybridCodeEditorView` and `HybridCodepad`. | Nonisolated for the JS thread's readers. View work hops to the main actor. |

The pure layers compile as a Swift package at the repository root, with the tree-sitter runtime and the sixteen grammars as C targets, so `swift test` runs the vectors, the syntax and layout suites and the keyboard replays on macOS in seconds. The pod compiles the same files plus `view` and `nitro`. Both use the Swift 6 language mode.

The view is a `UIScrollView` whose content view conforms to `UITextInput` over UTF-16 offsets, so the system keyboard, dictation, autocorrect and hardware keys talk to the document directly. The visible lines are recycled `CALayer`s drawn through Core Text, keyed by the line's and the snapshot's revision. The selection UI is a `UITextSelectionDisplayInteraction` with the editor's own highlight, cursor and handle views, which is what lets the theme's `selection` and `cursor` apply exactly. The loupe is a `UITextLoupeSession`, the edit menu a `UIEditMenuInteraction`, and `undoManager` a Foundation `UndoManager` subclass over the core's groups. The scroll view's `contentInset` is never used, so `contentInsets`, the keyboard inset, `scrollToLine` and `onContentSizeChange` keep the Android semantics. Keyboard avoidance reads a tracking view pinned to the window's `keyboardLayoutGuide` through its presentation layer on every frame.

### Threads

| Thread | Does |
| --- | --- |
| Main | Mutates the document, selection and layout, holds the keyboard state, draws |
| JS | Sync readers under the read lock, receives events |
| Syntax, one per editor | Parses, runs injections and search, publishes snapshots |

The document lock is a `ReentrantReadWriteLock` on Android and a `pthread_rwlock_t` on iOS, and writers hold it for one `replace`. Writers from JavaScript post to the main thread and resolve after the change is applied, so a detached view still resolves them.

### The tree-sitter binding

The runtime is tree-sitter 0.26, vendored into the core library with hidden symbols. A generated `parser.c` is self contained, so language packages never link against the runtime. The binding works in UTF-16: the input is `UTF16LE` and byte offsets are halved at the boundary, so Kotlin and Swift see the offsets JavaScript uses. The parser's read callback reads a native UTF-16 mirror of the document, so a parse never calls back into the JVM. Predicates (`eq?`, `match?`, `any-of?`, `contains?`, `has-parent?`, `has-ancestor?` with their `not-` and `any-` forms) are evaluated in Kotlin and Swift, and `lua-match?` patterns become regular expressions at generation time.

#### Injections and kept trees

The host tree's injection query yields ranges with a language. The name is converted to lowercase and aliased, `#offset!` trims columns, `injection.combined` ranges form one tree, children are always included, and injected trees do not run their own injection query.

Injected trees survive across snapshots. The engine keeps each one with the hull of its match and its extent, plus a copy of the host tree from the last completed pass. An edit goes to the reference tree and, by arithmetic, to the hulls and extents. A kept tree takes an edit only when the edit reaches it, and an edit before it accumulates as a shift the painter reads through. After a host reparse, `ts_tree_get_changed_ranges` gives the regions whose structure differs, the edits' own spans are added, and the injections query runs over those regions only. A kept tree the regions meet reparses against its old tree, and every other tree is carried over with no parser call. The first pass after `setText` or a language switch covers the whole document.

### The Nitro layer

`HybridCodeEditorView` owns one `CodeEditorView`, diffs incoming props into setters, wires the callbacks and forwards the methods. Sync readers take the document read lock on the JS thread. `getCursorRect()` and `getVisibleLines()` read a layout snapshot the main thread publishes after each layout pass. The wrapper fills in the defaults, wraps every callback once and normalizes `theme.tokens` into `{ color, bold, italic }` structs.

`HybridCodepad.availableLanguages()` lists the marker files under `assets/codepad-languages/` on Android and scans the class list for `CPLang` classes on iOS. The registry loads a language by name, checks its ABI against the runtime, compiles its queries once and caches the result for the process.

### Conventions

- UTF-16 offsets, half open ranges and 0 based lines and columns, in Kotlin, Swift, the parser and JavaScript alike.
- An unknown or failed language is one warning and plain text. Ranges clamp and swap. Methods called before `onReady` operate on the empty document. Only a regular expression that does not compile throws.
- Native never emits events from prop setters during the first batch, and object props are compared by identity before they cross.

---

## Contributing

The repository is a yarn workspace: the library at the root, the example app under `example/`, one package per language under `languages/` and this site under `website/`. You need Node 24 and yarn 4 through corepack, JDK 17, the Android SDK with an emulator, and Xcode 16 with an iOS 17 simulator.

```sh
git clone https://github.com/SectionTN/react-native-codepad
cd react-native-codepad
yarn
```

### JavaScript

| Command | Does |
| --- | --- |
| `yarn lint`, `yarn format` | Runs the Biome check, with fixes for `format` |
| `yarn typecheck` | Runs `tsc` over the library, the example, the generator and the tests |
| `yarn test` | Runs jest for the wrapper and `node --test` for the generator, the theme coverage and the docs drift tests |
| `yarn nitrogen` | Regenerates `nitrogen/generated` after a change to a `*.nitro.ts` file. The output is committed |
| `yarn prepare` | Builds the library |

### Android

The Kotlin core, the keyboard protocol and the syntax engine are tested on the JVM, so no device is needed. The syntax tests use a host build of tree-sitter, built once:

```sh
yarn host:treesitter
yarn test:android
```

For the device loop, start Metro and install the example on a running emulator:

```sh
yarn example start --port 8081
adb reverse tcp:8081 tcp:8081
yarn example android
```

Every build, bench and instrumented run uses the `debugOptimized` variant: a debuggable app over release library modules, so the numbers mean something.

| Command | Does |
| --- | --- |
| `yarn test:device [-e class codepad.example.X]` | Installs both APKs and runs the instrumented tests |
| `yarn bench:scroll [swipes]` | Prints the frame times and the janky count over flings of the benchmark document |
| `yarn bench:memory` | Prints the Java and native heaps and the PSS |
| `yarn bench:typing [chars]` | Types through `adb shell input` and prints the key handler, key to paint and parse percentiles |
| `yarn ime:record <name>` | Records the keyboard's input connection calls into `tests/ime/<name>.json`, which `yarn test:android` replays |

### Languages

| Command | Does |
| --- | --- |
| `yarn gen:languages [id...]` | Regenerates the packages from `languages/grammars.json` and the [language packages](/reference/languages/) page |
| `yarn gen:report` | Lists every predicate each language's queries use, with counts |

Generated files are never edited by hand: CI regenerates them and fails on a diff. [Adding a language](/guides/languages/#adding-a-language) has the steps.

### iOS

The Swift core, input, syntax and layout layers build as a Swift package at the root and are tested on macOS, so no simulator is needed:

```sh
yarn test:swift
swift test --filter CodepadTests.DocumentTests
```

For the simulator loop, start Metro and run the example on an iOS 17 simulator. Run `bundle exec pod install` in `example/ios` after a podspec, a Nitro spec or a dependency changed.

```sh
yarn example start --port 8081
yarn example ios --device <udid>
```

| Command | Does |
| --- | --- |
| `yarn test:ios [-only-testing:CodepadTests/<Class>]` | Runs the view and input suites on the simulator. `CODEPAD_IOS_UDID` picks the device |
| `yarn bench:ios scroll`, `memory`, `typing` | Collects the same measures as Android on the simulator, for regressions only |
| `yarn ime:record:ios <name>` | Records the keyboard's `UITextInput` calls into `tests/ime-ios/<name>.json`, which `yarn test:swift` replays |

### This site

`yarn docs` serves the site with live reload and `yarn docs:build` builds it. The pages live under `website/docs`. The reference pages are written by hand, and a test under `tests/docs` fails when a prop, method or type of `src/types.ts` is missing from them. A push to `main` that touches `website/` deploys the site to Cloudflare Pages.

### Conventions

- The layers are the ones on the [architecture](/internals/architecture/) page: `core` and `input` are pure Kotlin and pure Swift, and Nitro code lives only in `com.margelo.nitro.codepad`, `ios/Codepad/nitro` and `src/specs`.
- UTF-16 offsets, half open ranges and 0 based lines and columns, everywhere.
- Tests first: a vector or a JUnit and XCTest case for engine behavior, a jest case for the wrapper, and a keyboard recording for a keyboard bug.
- Biome formatting, conventional commits with an imperative subject under 72 characters, and comments of one to three lines for platform quirks and invariants only.
- Pull requests run `lint`, `test`, `test-swift`, `docs`, `build-library`, `build-android` and `build-ios` in CI.

[CONTRIBUTING](https://github.com/SectionTN/react-native-codepad/blob/main/CONTRIBUTING.md) in the repository is the short version of this page.

---

## Roadmap

### Now

Both editors are complete. Android is tested on the JVM and on an emulator and measured in the [performance guide](/guides/performance/). iOS runs the same vectors under `swift test` and XCTest on the simulator. Numbers from a physical iPhone are still missing.

### Release

`0.1.0` is the first npm release: the core and the fifteen language packages, published together. `1.0.0` needs the list below on both platforms.

### Not in the first version

- An autocomplete popup with provider hooks, and an LSP client on top of it.
- Code folding, a minimap and multiple cursors.
- Diagnostics: squiggles and a gutter marker API.
- Font ligatures.
- Correct bidi editing. Caret movement is logical for now.
- A web target.
- A built in keyboard toolbar. The [toolbar API](/reference/methods/#toolbar-input) and the example's key row are the building blocks.
- `indents.scm` and `locals.scm`. They ship in the packages but are not loaded yet.
- `#set! priority` in queries.
- Second level injections.
- Pinch to zoom the font size.
- Edge auto scroll while dragging a selection handle past the viewport.
- On iOS: interactive keyboard dismissal, the keyboard appearance from the theme, and iOS 15 and 16.
- Keyboards other than Gboard and the iOS system keyboard. Recordings are added as bugs come in.
- A shared C++ core replacing the two engines.

---

## Events

Every callback is wrapped once by the component, so an inline arrow function is fine. The payload types are on the [types page](/reference/types/).

### `onReady`

`() => void`. Fires once, after the first draw with `initialValue` applied. Ref methods are valid from here, and a call before it operates on an empty document.

### `onChange`

`(e: ChangeEvent) => void`. Fires once per committed change, composition updates included, with a delta: `[start, end)` was replaced with `text`. `revision` grows by one per change. `origin` is `input` for the keyboard, the edit menu and the toolbar methods, `api` for `setText()`, `replaceRange()` and `insertText()`, and `undo` or `redo` for history.

### `onChangeText`

`(text: string) => void`. The full document after every change, at the cost of one copy per edit. Prefer `onChange` on large documents.

### `onSelectionChange`

`(s: SelectionChangeEvent) => void`. The anchor and head in UTF-16 units plus their revision. At most one event per frame.

### `onScroll`

`(e: ScrollEvent) => void`. The scroll offset and the content extent in dp, without insets. At most one event per frame.

### `onFocus` and `onBlur`

`() => void`. Focus follows the native view: a tap, `focus()`, `blur()`, or the keyboard closing.

### `onContentSizeChange`

`(e: ContentSizeEvent) => void`. The view size at which nothing scrolls, `contentInsets` included, in dp. Sent after a draw whose content size changed, at most once per frame, and the first time before `onReady`. With soft wrap the value converges over a few frames as lines are measured. The keyboard overlap from `avoidKeyboard` is not included. See [nested in a ScrollView](/guides/nested-scroll/).

---

## Language packages

This page is generated by `yarn gen:languages` from the packages under `languages/`.

Install a package next to the core and pass its `language` id to `CodeEditor`. A grammar whose name differs from the package id (`markdown_inline`) is reached through injection only. The Injects column lists the languages a package's injection query names. "From the source" means the name comes from the document, as a fence info string does.

| Package | `language` | Grammar | Scanner | Injects |
| --- | --- | --- | --- | --- |
| `react-native-codepad-lang-c` | `c` | [`tree-sitter/tree-sitter-c`](https://github.com/tree-sitter/tree-sitter-c/tree/b780e47fc780ddc8da13afa35a3f4ed5c157823d) | no | `comment`, `doxygen`, `printf`, `re2c` |
| `react-native-codepad-lang-css` | `css` | [`tree-sitter/tree-sitter-css`](https://github.com/tree-sitter/tree-sitter-css/tree/dda5cfc5722c429eaba1c910ca32c2c0c5bb1a3f) | yes | `comment` |
| `react-native-codepad-lang-go` | `go` | [`tree-sitter/tree-sitter-go`](https://github.com/tree-sitter/tree-sitter-go/tree/2346a3ab1bb3857b48b29d779a1ef9799a248cd7) | no | `comment`, `printf`, `re2c`, `regex` |
| `react-native-codepad-lang-html` | `html` | [`tree-sitter/tree-sitter-html`](https://github.com/tree-sitter/tree-sitter-html/tree/73a3947324f6efddf9e17c0ea58d454843590cc0) | yes | `comment`, `css`, `javascript`, `json`, `python`, `regex`, `toml` |
| `react-native-codepad-lang-java` | `java` | [`tree-sitter/tree-sitter-java`](https://github.com/tree-sitter/tree-sitter-java/tree/e10607b45ff745f5f876bfa3e94fbcc6b44bdc11) | no | `comment`, `javadoc`, `printf` |
| `react-native-codepad-lang-javascript` | `javascript` | [`tree-sitter/tree-sitter-javascript`](https://github.com/tree-sitter/tree-sitter-javascript/tree/58404d8cf191d69f2674a8fd507bd5776f46cb11) | yes | `angular`, `comment`, `css`, `glimmer`, `graphql`, `groq`, `html`, `jsdoc`, `regex`, `styled`, from the source |
| `react-native-codepad-lang-json` | `json` | [`tree-sitter/tree-sitter-json`](https://github.com/tree-sitter/tree-sitter-json/tree/254c42a6476413b776221e03982ac8ae159eeb72) | no | `comment` |
| `react-native-codepad-lang-kotlin` | `kotlin` | [`fwcd/tree-sitter-kotlin`](https://github.com/fwcd/tree-sitter-kotlin/tree/1852ea17b7f60fb3f9d84e0b1555d56b46b39fb1) | yes | `comment`, `printf`, `regex` |
| `react-native-codepad-lang-markdown` | `markdown`, `markdown_inline` | [`tree-sitter-grammars/tree-sitter-markdown`](https://github.com/tree-sitter-grammars/tree-sitter-markdown/tree/a0a00f817d02412bd92c54d316f164d827b57b5c) | yes | `html`, `latex`, `markdown_inline`, `toml`, `yaml`, from the source |
| `react-native-codepad-lang-python` | `python` | [`tree-sitter/tree-sitter-python`](https://github.com/tree-sitter/tree-sitter-python/tree/293fdc02038ee2bf0e2e206711b69c90ac0d413f) | yes | `comment`, `printf`, `regex` |
| `react-native-codepad-lang-rust` | `rust` | [`tree-sitter/tree-sitter-rust`](https://github.com/tree-sitter/tree-sitter-rust/tree/77a3747266f4d621d0757825e6b11edcbf991ca5) | yes | `comment`, `re2c`, `regex`, `rust`, from the source |
| `react-native-codepad-lang-swift` | `swift` | [`alex-pinkus/tree-sitter-swift`](https://github.com/alex-pinkus/tree-sitter-swift/tree/82bb3a533e0801fd2bbaa11dc49676e10bf41948) | yes | `comment`, `regex` |
| `react-native-codepad-lang-tsx` | `tsx` | [`tree-sitter/tree-sitter-typescript`](https://github.com/tree-sitter/tree-sitter-typescript/tree/75b3874edb2dc714fb1fd77a32013d0f8699989f) | yes | `angular`, `comment`, `css`, `glimmer`, `graphql`, `groq`, `html`, `jsdoc`, `regex`, `styled`, from the source |
| `react-native-codepad-lang-typescript` | `typescript` | [`tree-sitter/tree-sitter-typescript`](https://github.com/tree-sitter/tree-sitter-typescript/tree/75b3874edb2dc714fb1fd77a32013d0f8699989f) | yes | `angular`, `comment`, `css`, `glimmer`, `graphql`, `groq`, `html`, `jsdoc`, `regex`, `styled`, from the source |
| `react-native-codepad-lang-yaml` | `yaml` | [`tree-sitter-grammars/tree-sitter-yaml`](https://github.com/tree-sitter-grammars/tree-sitter-yaml/tree/a1c4812a73ec5e089de8e441fdea3a921e8d5079) | yes | `bash`, `comment`, `promql` |

### Capture names

The token keys each grammar's highlight query produces. A theme styles them through the longest dotted prefix it defines, so `keyword.return` falls back to `keyword`.

#### `c`

`attribute`, `boolean`, `character`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `constant.macro`, `function`, `function.builtin`, `function.call`, `function.macro`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.directive`, `keyword.directive.define`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `number`, `operator`, `property`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `type`, `type.builtin`, `type.definition`, `variable`, `variable.builtin`, `variable.parameter`

#### `css`

`attribute`, `character.special`, `comment`, `constant`, `function`, `keyword`, `keyword.directive`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `module`, `number`, `number.float`, `operator`, `property`, `punctuation.bracket`, `punctuation.delimiter`, `spell`, `string`, `tag`, `tag.attribute`, `type`, `variable`

#### `go`

`boolean`, `character`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `constructor`, `function`, `function.builtin`, `function.call`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.coroutine`, `keyword.function`, `keyword.import`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `module`, `number`, `number.float`, `operator`, `property`, `punctuation.bracket`, `punctuation.delimiter`, `spell`, `string`, `string.escape`, `string.regexp`, `type`, `type.builtin`, `type.definition`, `variable`, `variable.member`, `variable.parameter`

#### `html`

`character.special`, `comment`, `constant`, `markup.heading`, `markup.heading.1`, `markup.heading.2`, `markup.heading.3`, `markup.heading.4`, `markup.heading.5`, `markup.heading.6`, `markup.italic`, `markup.link.label`, `markup.raw`, `markup.strikethrough`, `markup.strong`, `markup.underline`, `none`, `nospell`, `operator`, `spell`, `string`, `string.special.url`, `tag`, `tag.attribute`, `tag.delimiter`

#### `java`

`attribute`, `boolean`, `character`, `character.special`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `function.builtin`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.exception`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `number`, `number.float`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `type`, `type.builtin`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `javascript`

`attribute`, `boolean`, `character.special`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `constructor`, `function`, `function.builtin`, `function.call`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `markup.heading`, `markup.heading.1`, `markup.heading.2`, `markup.heading.3`, `markup.heading.4`, `markup.heading.5`, `markup.heading.6`, `markup.italic`, `markup.link.label`, `markup.raw`, `markup.strikethrough`, `markup.strong`, `markup.underline`, `module`, `module.builtin`, `none`, `number`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `string.special.url`, `tag`, `tag.attribute`, `tag.builtin`, `tag.delimiter`, `type`, `type.builtin`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `json`

`boolean`, `comment`, `conceal`, `constant.builtin`, `number`, `property`, `punctuation.bracket`, `punctuation.delimiter`, `spell`, `string`, `string.escape`

#### `kotlin`

`attribute`, `boolean`, `character`, `character.special`, `comment`, `comment.documentation`, `constant`, `constructor`, `function`, `function.builtin`, `function.call`, `keyword`, `keyword.conditional`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.modifier`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `module`, `none`, `number`, `number.float`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `type`, `type.builtin`, `type.definition`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `markdown`

`keyword.directive`, `label`, `markup.heading`, `markup.heading.1`, `markup.heading.2`, `markup.heading.3`, `markup.heading.4`, `markup.heading.5`, `markup.heading.6`, `markup.link.label`, `markup.link.url`, `markup.list`, `markup.list.checked`, `markup.list.unchecked`, `markup.quote`, `markup.raw.block`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string.escape`

#### `markdown_inline`

`character.special`, `conceal`, `markup.italic`, `markup.link`, `markup.link.label`, `markup.link.url`, `markup.raw`, `markup.strikethrough`, `markup.strong`, `nospell`

#### `python`

`attribute`, `attribute.builtin`, `boolean`, `character.special`, `comment`, `constant`, `constant.builtin`, `constructor`, `function`, `function.builtin`, `function.call`, `function.macro`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `module`, `module.builtin`, `none`, `nospell`, `number`, `number.float`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.documentation`, `string.escape`, `string.regexp`, `type`, `type.builtin`, `type.definition`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `rust`

`attribute`, `attribute.builtin`, `boolean`, `character`, `character.special`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `function`, `function.call`, `function.macro`, `keyword`, `keyword.conditional`, `keyword.coroutine`, `keyword.debug`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `module`, `number`, `number.float`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `type`, `type.builtin`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `swift`

`attribute`, `boolean`, `character.special`, `comment`, `comment.documentation`, `constant.builtin`, `constant.macro`, `constructor`, `function.call`, `function.macro`, `function.method`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `number`, `number.float`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `type`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `tsx`

`attribute`, `boolean`, `character.special`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `constructor`, `function`, `function.builtin`, `function.call`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `markup.heading`, `markup.heading.1`, `markup.heading.2`, `markup.heading.3`, `markup.heading.4`, `markup.heading.5`, `markup.heading.6`, `markup.italic`, `markup.link.label`, `markup.raw`, `markup.strikethrough`, `markup.strong`, `markup.underline`, `module`, `module.builtin`, `none`, `number`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `string.special.url`, `tag`, `tag.attribute`, `tag.builtin`, `tag.delimiter`, `type`, `type.builtin`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `typescript`

`attribute`, `boolean`, `character.special`, `comment`, `comment.documentation`, `constant`, `constant.builtin`, `constructor`, `function`, `function.builtin`, `function.call`, `function.method`, `function.method.call`, `keyword`, `keyword.conditional`, `keyword.conditional.ternary`, `keyword.coroutine`, `keyword.directive`, `keyword.exception`, `keyword.function`, `keyword.import`, `keyword.modifier`, `keyword.operator`, `keyword.repeat`, `keyword.return`, `keyword.type`, `label`, `module`, `module.builtin`, `none`, `number`, `operator`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `string.regexp`, `string.special.url`, `type`, `type.builtin`, `variable`, `variable.builtin`, `variable.member`, `variable.parameter`

#### `yaml`

`boolean`, `comment`, `constant.builtin`, `keyword.directive`, `label`, `number`, `property`, `punctuation.bracket`, `punctuation.delimiter`, `punctuation.special`, `spell`, `string`, `string.escape`, `type`

---

## Methods

Get the ref with `useRef<CodeEditorRef>(null)` and pass it as `ref`. Readers run on the JS thread and return at once. Writers return a promise that resolves once the change is applied. Offsets count UTF-16 code units, lines and columns start at 0, and ranges include the start but exclude the end. No method throws on bad input: ranges are clamped to the document and swapped when reversed.

### Readers

| Method | Returns | Notes |
| --- | --- | --- |
| `getText()` | `string` | The whole document. Tens of milliseconds on a multi megabyte file. |
| `getTextInRange(range)` | `string` | The text inside the range. |
| `getLength()` | `number` | The length in UTF-16 units. |
| `getLineCount()` | `number` | At least 1. |
| `getLine(index)` | `string` | An empty string out of range. |
| `getSelection()` | `Selection` | `head` is the caret. |
| `getRevision()` | `number` | 0 right after `initialValue` is loaded. |
| `offsetToPosition(offset)` | `Position` | The line and column of an offset. |
| `positionToOffset(pos)` | `number` | The offset of a line and column. |
| `getCursorRect()` | `Rect` or `null` | The caret in view coordinates, in dp. `null` before the first layout. |
| `getVisibleLines()` | `{ first, last }` | The range of lines on screen. |
| `canUndo()`, `canRedo()` | `boolean` | Refresh them from `onChange`. |
| `isFocused()` | `boolean` | Whether the editor has focus. |

### Writers

| Method | Notes |
| --- | --- |
| `setText(text, opts?)` | Replaces the document in one change with origin `api`. The selection resets to 0 and the scroll to the top. `opts.keepHistory` keeps the undo history. |
| `replaceRange(range, text)` | Replaces the range. The selection maps through the change. |
| `insertText(text)` | Replaces the selection and puts the caret after the text. This is the raw path: no auto close, no indentation, origin `api`. |
| `setSelection(sel)` | Sets the selection without scrolling. Call `revealSelection()` to show it. |
| `selectAll()` | Selects the whole document. |
| `scrollToLine(line, opts?)` | Puts the line at the top of the viewport. `opts.animated` animates the scroll. |
| `revealSelection()` | Scrolls the least amount that shows the caret. |
| `undo()`, `redo()` | Resolve as no-ops when there is nothing to undo or redo. |
| `indent()`, `outdent()` | Shift the selected lines by one level of `tabSize`, like Tab and Shift+Tab. |
| `cut()`, `copy()`, `paste()` | Use the system clipboard. A paste reports origin `input`. |
| `focus()`, `blur()` | `focus()` shows the keyboard unless `readOnly` is set. |

### Toolbar input

The keyboard path, for a key row built in JavaScript: origin `input`, typing coalesced into one undo group, and no-ops under `readOnly`.

| Method | Notes |
| --- | --- |
| `moveCaret(direction, opts?)` | Moves the caret in a `CaretDirection` from the [key table](/guides/hardware-keyboard/#the-same-table-from-javascript). `opts.select` extends the selection. Works under `readOnly`. |
| `typeText(text)` | Types the text as if from the keyboard: each character goes through the auto closer and a newline through the indenter. |
| `deleteBackward()` | Backspace: deletes one grapheme cluster, an empty auto closed pair in one go, or the selection first. |
| `deleteForward()` | Delete. |

### Search

Native keeps the query and paints the matches. See the [search guide](/guides/search/).

| Method | Notes |
| --- | --- |
| `setSearch(query)` | Sets a `SearchQuery` and resolves with the match count. Rejects when a regex does not compile. |
| `findNext()`, `findPrevious()` | Select the next or previous match, wrapping around, and reveal it. Resolve with a `SearchHit`, or `null` without a query or matches. |
| `replaceCurrent(text)` | Replaces the selected match and selects the next one. Resolves with `false` when the selection is not a match. |
| `replaceAll(text)` | Replaces every match in one undo group and resolves with the number of replacements. |
| `clearSearch()` | Drops the query and the highlights. |

---

## Props

`CodeEditor` takes every React Native `ViewProps` plus the props below. `style` sizes the editor like any other view. Style padding is ignored. `contentInsets` is the padding instead. The callbacks are on the [events page](/reference/events/).

### Document

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `initialValue` | `string` | `''` | Sets the initial text of the editor. It is read once, so use `setText()` to replace the document later. |
| `language` | `string` | undefined | The id of an installed [language package](/reference/languages/). Without the package the editor shows plain text. |
| `readOnly` | `boolean` | `false` | Makes the editor read only: no keyboard, and the toolbar methods that type or delete do nothing. Selection, copy and search still work. |

### Appearance

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `theme` | `Theme` | `githubLight` | The colors. Hoist the object, it is compared by identity. See [theme tokens](/reference/theme-tokens/). |
| `fontFamily` | `string` | `monospace` on Android, `Menlo` on iOS | The font, by name. Fonts linked with `react-native-asset` or `expo-font` resolve by name. |
| `fontSize` | `number` | `14` | In dp on Android and points on iOS. |
| `lineHeight` | `number` | `1.4` | A multiplier of the font size. The row height is `round(fontSize * lineHeight)`. |
| `lineNumbers` | `boolean` | `true` | Shows the line number gutter. |
| `softWrap` | `boolean` | `false` | Wraps long lines. Off means horizontal scrolling. |
| `highlightActiveLine` | `boolean` | `true` | Paints the line the caret is on. |
| `matchBrackets` | `boolean` | `true` | Paints the bracket pair at the caret. Brackets inside strings and comments are skipped. |
| `placeholder` | `string` | undefined | Text drawn while the document is empty. |

### Editing

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `tabSize` | `number` | `4` | The width of one indentation level. |
| `insertSpaces` | `boolean` | `true` | Indents with spaces. Off indents with tabs. |
| `autoIndent` | `boolean` | `true` | A newline keeps the indentation of the line before it and adds a level inside an open bracket. |
| `autoCloseBrackets` | `boolean` | `true` | Closes pairs as you type, skips over a closer you type yourself, wraps a selection, and removes an empty pair on Backspace. |
| `suggestions` | `Suggestions` | `'off'` | Controls what the keyboard offers. `off` asks for none, `forceOff` also kills composition on most Android keyboards and `on` allows autocorrect. On iOS `forceOff` is the same as `off`. |
| `autoFocus` | `boolean` | `false` | Focuses the editor and shows the keyboard once the view is attached. |

### Scrolling and keyboard

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `scrollEnabled` | `boolean` | `true` | Off lets a parent `ScrollView` scroll through the editor. |
| `contentInsets` | `ContentInsets` | all 0 | The padding inside the scrollable area, in dp on Android and points on iOS. A bottom inset keeps the caret above a toolbar. |
| `avoidKeyboard` | `boolean` | `false` | Adds the keyboard overlap to the bottom inset on every frame of the keyboard animation. See the [keyboard guide](/guides/keyboard/). |

---

## Theme tokens

A `Theme` is eleven editor colors plus `tokens`, a map from tree-sitter capture names to a `TokenStyle`. CodePad ships with three: `githubLight` (the default), `githubDark` and `oneDark`. The [themes guide](/guides/themes/) explains the lookup and shows a custom theme.

### Editor colors

| Key | githubLight | githubDark | oneDark |
| --- | --- | --- | --- |
| `background` | #ffffff | #0d1117 | #282c34 |
| `foreground` | #1f2328 | #e6edf3 | #abb2bf |
| `gutterBackground` | #ffffff | #0d1117 | #282c34 |
| `gutterForeground` | #8c959f | #6e7681 | #4b5263 |
| `gutterActiveForeground` | #1f2328 | #e6edf3 | #abb2bf |
| `activeLine` | #f6f8fa | #161b22 | #2c313c |
| `selection` | #0969da33 | #388bfd66 | #3e4451 |
| `cursor` | #1f2328 | #e6edf3 | #528bff |
| `matchingBracket` | #1f232833 | #3fb95059 | #3e445199 |
| `searchMatch` | #ffd33d66 | #9e6a0366 | #e5c07b55 |
| `searchMatchActive` | #ffb70099 | #d2992299 | #e5c07b99 |

`selection`, `matchingBracket`, `searchMatch` and `searchMatchActive` are drawn under the text, so they carry some alpha. `cursor` colors the caret and the selection handles on both platforms.

### Token keys

The keys are the capture names the highlight queries produce. The lookup takes the longest dotted prefix the theme defines, then falls back to `foreground`. The built-in themes cover every name the [language packages](/reference/languages/) produce.

| Key | githubLight | githubDark | oneDark |
| --- | --- | --- | --- |
| `attribute` | #0550ae | #79c0ff | #d19a66 |
| `boolean` | #0550ae | #79c0ff | #d19a66 |
| `character` | #0a3069 | #a5d6ff | #98c379 |
| `comment` | #59636e italic | #8b949e italic | #5c6370 italic |
| `constant` | #0550ae | #79c0ff | #d19a66 |
| `constant.builtin` | #0550ae | #79c0ff | #d19a66 |
| `constructor` | #8250df | #d2a8ff | #61afef |
| `function` | #8250df | #d2a8ff | #61afef |
| `function.builtin` | #8250df | #d2a8ff | #61afef |
| `function.call` | #8250df | #d2a8ff | #61afef |
| `function.method` | #8250df | #d2a8ff | #61afef |
| `keyword` | #cf222e | #ff7b72 | #c678dd |
| `keyword.function` | #cf222e | #ff7b72 | #c678dd |
| `keyword.operator` | #cf222e | #ff7b72 | #c678dd |
| `keyword.return` | #cf222e | #ff7b72 | #c678dd |
| `label` | #cf222e | #ffa657 | #e5c07b |
| `markup.heading` | #0550ae bold | #79c0ff bold | #e06c75 bold |
| `markup.italic` | #1f2328 italic | #e6edf3 italic | #abb2bf italic |
| `markup.link` | #0a3069 | #a5d6ff | #61afef |
| `markup.list` | #59636e | #8b949e | #5c6370 |
| `markup.quote` | #59636e italic | #8b949e italic | #5c6370 italic |
| `markup.raw` | #0a3069 | #a5d6ff | #98c379 |
| `markup.strikethrough` | #1f2328 | #e6edf3 | #abb2bf |
| `markup.strong` | #1f2328 bold | #e6edf3 bold | #abb2bf bold |
| `markup.underline` | #1f2328 | #e6edf3 | #abb2bf |
| `module` | #953800 | #ffa657 | #e5c07b |
| `number` | #0550ae | #79c0ff | #d19a66 |
| `operator` | #cf222e | #ff7b72 | #56b6c2 |
| `property` | #0550ae | #79c0ff | #e06c75 |
| `punctuation` | #1f2328 | #e6edf3 | #abb2bf |
| `punctuation.bracket` | #1f2328 | #e6edf3 | #abb2bf |
| `punctuation.delimiter` | #1f2328 | #e6edf3 | #abb2bf |
| `string` | #0a3069 | #a5d6ff | #98c379 |
| `string.escape` | #0a3069 | #a5d6ff | #56b6c2 |
| `string.special` | #0a3069 | #a5d6ff | #98c379 |
| `tag` | #116329 | #7ee787 | #e06c75 |
| `tag.attribute` | #0550ae | #79c0ff | #d19a66 |
| `type` | #953800 | #ffa657 | #e5c07b |
| `type.builtin` | #953800 | #ffa657 | #e5c07b |
| `variable` | #1f2328 | #e6edf3 | #abb2bf |
| `variable.builtin` | #cf222e | #ffa657 | #e5c07b |
| `variable.member` | #0550ae | #79c0ff | #e06c75 |
| `variable.parameter` | #1f2328 | #e6edf3 | #e06c75 |

---

## Types

All of these are exported from `react-native-codepad`. Offsets count UTF-16 code units, lines and columns start at 0, and ranges include the start but exclude the end.

| Type | Shape | Notes |
| --- | --- | --- |
| `Range` | `{ start: number; end: number }` | `[start, end)` |
| `Selection` | `{ anchor: number; head: number }` | `head` is the caret. |
| `Position` | `{ line: number; column: number }` | A line and a column. |
| `Rect` | `{ x: number; y: number; width: number; height: number }` | View coordinates, in dp. |
| `ContentInsets` | `{ top?: number; bottom?: number; left?: number; right?: number }` | In dp. |
| `ScrollEvent` | `{ x: number; y: number; contentWidth: number; contentHeight: number }` | In dp, without insets. |
| `SelectionChangeEvent` | `Selection & { revision: number }` | The selection plus its revision. |
| `ChangeOrigin` | `'input' \| 'api' \| 'undo' \| 'redo'` | Where a change came from. |
| `ChangeEvent` | `{ start: number; end: number; text: string; origin: ChangeOrigin; revision: number }` | `[start, end)` was replaced with `text`. |
| `ContentSizeEvent` | `{ width: number; height: number }` | The size at which nothing scrolls, insets included, in dp. |
| `CaretDirection` | `'left' \| 'right' \| 'wordLeft' \| 'wordRight' \| 'lineStart' \| 'lineEnd' \| 'documentStart' \| 'documentEnd' \| 'up' \| 'down' \| 'pageUp' \| 'pageDown'` | For `moveCaret()`. |
| `Suggestions` | `'off' \| 'forceOff' \| 'on'` | For the `suggestions` prop. |
| `SearchQuery` | `{ text: string; regex?: boolean; caseSensitive?: boolean; wholeWord?: boolean }` | ICU regex on both platforms. The replacement text is literal. |
| `SearchHit` | `{ index: number; total: number }` | The 0 based index of the selected match. |
| `TokenStyle` | `string \| { color: string; bold?: boolean; italic?: boolean }` | A color string is the shorthand. |
| `Theme` | see [theme tokens](/reference/theme-tokens/) | |
| `CodeEditorProps` | see [props](/reference/props/) | Extends React Native `ViewProps`. |
| `CodeEditorRef` | see [methods](/reference/methods/) | |

Colors accept `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`. Anything else paints magenta and logs a warning.

The module object `Codepad` has one method, `availableLanguages(): string[]`, which lists the grammar names installed in the app.

---

## Installation

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

### Requirements

- React Native 0.81+ with the New Architecture
- Android 7+ (API 24)
- iOS 17+

### Packages

Install the core, Nitro Modules and one package per language you want to highlight:

**npm**

```sh
npm install react-native-codepad react-native-nitro-modules react-native-codepad-lang-javascript
```

**pnpm**

```sh
pnpm add react-native-codepad react-native-nitro-modules react-native-codepad-lang-javascript
```

**yarn**

```sh
yarn add react-native-codepad react-native-nitro-modules react-native-codepad-lang-javascript
```

**bun**

```sh
bun add react-native-codepad react-native-nitro-modules react-native-codepad-lang-javascript
```

Language packages are named `react-native-codepad-lang-<id>`. The [language list](/reference/languages/) has all fifteen.

### Rebuild

The packages carry native code, so rebuild the app after adding or removing one.

**Expo**

Expo development builds only, not Expo Go. Set the iOS deployment target to 17.0, then prebuild and run:

```json title="app.json"
{
  "expo": {
    "plugins": [
      // diff-add-start
      ["expo-build-properties", { "ios": { "deploymentTarget": "17.0" } }]
      // diff-add-end
    ]
  }
}
```

```sh
npx expo prebuild
npx expo run:ios
npx expo run:android
```

**React Native**

Autolinking does the rest. Set the iOS deployment target in the Podfile, install the pods and run:

```ruby title="ios/Podfile"
# diff-remove
platform :ios, min_ios_version_supported
# diff-add
platform :ios, '17.0'
```

```sh
cd ios && pod install && cd ..
npm run ios
npm run android
```

---

## Introduction

React Native CodePad is a code editor for React Native with its own engine on each platform: Kotlin on Android, Swift on iOS. Highlighting is done with the help of tree-sitter, and each language comes as its own npm package. The view is bound through Nitro, so everything works in a blink of an eye.

No WebView, no `TextInput`. CodePad draws its own caret, selection handles and edit menu, natively.

### Features

- Editing: tap, double tap and long press selection with handles, the loupe and the edit menu, undo and redo, auto indent, auto closing pairs, Tab and Shift+Tab, bracket matching, an active line, a read only mode and a placeholder.
- Keyboards: soft keyboards with composition, the full [hardware key table](/guides/hardware-keyboard/), and a [toolbar API](/reference/methods/#toolbar-input) that drives the same paths from JavaScript.
- View: a line number gutter, soft wrap or horizontal scroll, scroll to line, the caret rect and the visible lines for toolbars, content insets, and an editor that [follows the keyboard](/guides/keyboard/).
- Search: literal or regex, case sensitive and whole word options, next and previous, replace one or all, with every match painted.
- Highlighting: fifteen [language packages](/reference/languages/), injections for fenced blocks, embedded script and style tags and tagged templates, and three themes.

---

## Quick start

This is a simple CodePad usage: one screen with the editor, an undo button on the ref and a status line fed by `onChange`.

```tsx
import { useRef, useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import { CodeEditor, type CodeEditorRef, githubDark } from 'react-native-codepad';

const INITIAL = ['export function greet(name) {', '  return `Hello, ${name}`;', '}'].join('\n');

// Object props are compared by identity; hoist them out of the render.
const INSETS = { bottom: 24 };

export function EditorScreen() {
  const editor = useRef<CodeEditorRef>(null);
  const [revision, setRevision] = useState(0);
  return (
    <View style={styles.screen}>
      <View style={styles.bar}>
        <Text style={styles.status}>revision {revision}</Text>
        <Button title="Undo" onPress={() => editor.current?.undo()} />
        <Button title="Log" onPress={() => console.log(editor.current?.getText())} />
      </View>
      <CodeEditor
        ref={editor}
        style={styles.editor}
        initialValue={INITIAL}
        language="javascript"
        theme={githubDark}
        contentInsets={INSETS}
        onReady={() => console.log('lines', editor.current?.getLineCount())}
        onChange={(e) => setRevision(e.revision)}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1, backgroundColor: '#0d1117' },
  bar: { flexDirection: 'row', alignItems: 'center', gap: 8, padding: 8 },
  status: { color: '#8b949e', flex: 1 },
  editor: { flex: 1 },
});
```

- The editor needs a height: `flex: 1` in a column, or an explicit `height`.
- `initialValue` sets the initial text of the editor. It is read once, so use `setText()` to replace the document later.
- `language` is the id of an installed language package. Without the package the editor shows plain text.
- `theme` defaults to `githubLight`. The [themes guide](/guides/themes/) has the other two and shows how to write your own.
- `onChange` gives you one delta per change. `onChangeText` gives you the whole text after every change, so keep it for small documents.
- The ref reads synchronously (`getText()`, `getSelection()`, `getCursorRect()`) and writes asynchronously (`setText()`, `replaceRange()`, `undo()`). Everything is valid from `onReady`.

Offsets count UTF-16 code units. Lines and columns start at `0`, and ranges include the start but exclude the end, just like JavaScript strings.