rich-text

What this skill does

# Rich Text in React Native

Software Mansion's production patterns for rich text editing and Markdown rendering in React Native.

There are two libraries that cover rich text use cases:

| Library | Component | Purpose |
|---------|-----------|---------|
| `react-native-enriched` | `EnrichedTextInput` | Rich text **editing** (input) |
| `react-native-enriched-markdown` | `EnrichedMarkdownText` | Markdown **rendering** (display) |

Both libraries require the React Native New Architecture (Fabric) and support iOS and Android.

## Choosing the right library

- **User needs to type/edit rich text** (bold, italic, mentions, links, inline images): use `react-native-enriched`
- **App needs to display Markdown content** (chat messages, documentation, AI responses): use `react-native-enriched-markdown`
- **Both editing and display**: use both libraries together

## react-native-enriched (Editor)

`EnrichedTextInput` is a native, uncontrolled rich text input. It directly interacts with platform-specific components for performance, meaning it does not use React state for its value.

```bash
npm install react-native-enriched
```

### Basic usage

```tsx
import { EnrichedTextInput } from 'react-native-enriched';
import type {
  EnrichedTextInputInstance,
  OnChangeStateEvent,
} from 'react-native-enriched';
import { useState, useRef } from 'react';
import { View, Button, StyleSheet } from 'react-native';

export default function RichEditor() {
  const ref = useRef<EnrichedTextInputInstance>(null);
  const [stylesState, setStylesState] = useState<OnChangeStateEvent | null>();

  return (
    <View style={styles.container}>
      <EnrichedTextInput
        ref={ref}
        onChangeState={(e) => setStylesState(e.nativeEvent)}
        style={styles.input}
      />
      <Button
        title={stylesState?.bold.isActive ? 'Unbold' : 'Bold'}
        color={stylesState?.bold.isActive ? 'green' : 'gray'}
        onPress={() => ref.current?.toggleBold()}
      />
    </View>
  );
}
```

### Key concepts

**Toggling styles via ref**: All formatting is applied imperatively through the ref. Call `ref.current?.toggleBold()`, `ref.current?.toggleItalic()`, etc.

**Style detection via onChangeState**: The `onChangeState` callback fires whenever the style state changes (e.g., cursor moves into bold text). Each style reports three properties:
- `isActive`: The style is applied at the current selection (highlight the toolbar button)
- `isBlocking`: The style is blocked by another active style (disable the toolbar button)
- `isConflicting`: The style conflicts with another active style (toggling it removes the conflicting style)

**Inline vs paragraph styles**:
- Inline styles (bold, italic, underline, strikethrough, inline code) apply to the exact character range selected. With no selection, they apply to the next characters typed.
- Paragraph styles (headings, codeblock, blockquote, lists) apply to entire paragraphs (text between newlines). If the selection spans multiple paragraphs, all are affected.

**HTML output**: Get HTML via `ref.current?.getHTML()` (on-demand, returns a Promise) or the `onChangeHtml` callback (continuous, has performance cost for large documents). Prefer `getHTML()` when you only need HTML at save time.

**Setting content**: Use `defaultValue` prop for initial HTML content, or `ref.current?.setValue(html)` to update imperatively.

### Supported styles

The `OnChangeStateEvent` key column shows the exact property name on the event object returned by `onChangeState`. Use these keys when reading style state (e.g. `stylesState.strikeThrough.isActive`). Note that casing varies (e.g. `strikeThrough` with capital T, `inlineCode` with capital C).

| Style | Toggle method | `OnChangeStateEvent` key | Type |
|-------|--------------|--------------------------|------|
| Bold | `toggleBold()` | `bold` | Inline |
| Italic | `toggleItalic()` | `italic` | Inline |
| Underline | `toggleUnderline()` | `underline` | Inline |
| Strikethrough | `toggleStrikeThrough()` | `strikeThrough` | Inline |
| Inline code | `toggleInlineCode()` | `inlineCode` | Inline |
| H1 | `toggleH1()` | `h1` | Paragraph |
| H2 | `toggleH2()` | `h2` | Paragraph |
| H3 | `toggleH3()` | `h3` | Paragraph |
| H4 | `toggleH4()` | `h4` | Paragraph |
| H5 | `toggleH5()` | `h5` | Paragraph |
| H6 | `toggleH6()` | `h6` | Paragraph |
| Code block | `toggleCodeBlock()` | `codeBlock` | Paragraph |
| Block quote | `toggleBlockQuote()` | `blockQuote` | Paragraph |
| Ordered list | `toggleOrderedList()` | `orderedList` | Paragraph |
| Unordered list | `toggleUnorderedList()` | `unorderedList` | Paragraph |
| Checkbox list | `toggleCheckboxList(checked)` | `checkboxList` | Paragraph |

### Links

Links are detected automatically (customizable via `linkRegex` prop) or applied manually:

```tsx
// Set link on selected text
ref.current?.setLink(selection.start, selection.end, selectedText, url);

// Remove link
ref.current?.removeLink(start, end);
```

Use `onChangeSelection` to get selection position and `onLinkDetected` to detect when the cursor is near a link.

### Mentions

Mentions support custom indicators (default: `@`). Set custom indicators via the `mentionIndicators` prop.

```tsx
<EnrichedTextInput
  ref={ref}
  mentionIndicators={['@', '#']}
  onStartMention={(indicator) => { /* show picker */ }}
  onChangeMention={({ indicator, text }) => { /* filter list */ }}
  onEndMention={(indicator) => { /* hide picker */ }}
/>

// Complete the mention when user selects from picker
ref.current?.setMention('@', 'John Doe', { userId: '123' });
```

### Inline images

```tsx
ref.current?.setImage(imageUri, width, height);
```

Images are inserted at the cursor position (or replace selected text) and affect line height. You are responsible for providing correct dimensions.

For the full API (all props, ref methods, events, HtmlStyle customization, context menu items), webfetch the [react-native-enriched README](https://github.com/software-mansion/react-native-enriched/blob/main/README.md).

---

## react-native-enriched-markdown (Renderer)

`EnrichedMarkdownText` renders Markdown as fully native text (no WebView). It uses [md4c](https://github.com/mity/md4c) for high-performance CommonMark-compliant parsing.

```bash
npm install react-native-enriched-markdown
```

### Basic usage

```tsx
import { EnrichedMarkdownText } from 'react-native-enriched-markdown';
import { Linking } from 'react-native';

const markdown = `
# Welcome

This is **bold**, *italic*, and [a link](https://reactnative.dev).

- List item one
- List item two
`;

export default function MarkdownDisplay() {
  return (
    <EnrichedMarkdownText
      markdown={markdown}
      onLinkPress={({ url }) => Linking.openURL(url)}
    />
  );
}
```

### Flavors

| Flavor | Features | Layout |
|--------|----------|--------|
| `commonmark` (default) | All CommonMark elements, inline math (`$...$`) | Single TextView |
| `github` | CommonMark + GFM tables, task lists, block math (`$$...$$`) | Segmented layout (separate TextViews + table views) |

```tsx
<EnrichedMarkdownText
  flavor="github"
  markdown={markdown}
  onLinkPress={({ url }) => Linking.openURL(url)}
/>
```

### Tables (GFM)

Tables require `flavor="github"` and support column alignment, rich text in cells, horizontal scrolling, header styling, alternating row colors, and a long-press context menu.

```tsx
<EnrichedMarkdownText
  flavor="github"
  markdown={tableMarkdown}
  markdownStyle={{
    table: {
      fontSize: 14,
      borderColor: '#E5E7EB',
      borderRadius: 8,
      headerBackgroundColor: '#F3F4F6',
      cellPaddingHorizontal: 12,
      cellPaddingVertical: 8,
    },
  }}
/>
```

### Task lists (GFM)

Task lists require `flavor="github"`. Handle checkbox taps with `onTaskListItemPress`:

```tsx
<EnrichedMarkdownText
  flavor="github"
  markdown={`- [x] Done\n- [ ] Todo`}
  onTaskListItemPress={({ index, checked, text }) => {
    console.log(`Task ${index}: ${checked ? 'checked' : 'unch