> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Cursor Editing

> Master multi-cursor editing in Fresh for simultaneous edits across multiple locations with VS Code-like workflows

Multi-cursor editing is one of Fresh's most powerful features, allowing you to edit multiple locations simultaneously. It works exactly like VS Code or Sublime Text, but in your terminal.

## What is Multi-Cursor Editing?

Multi-cursor editing lets you create multiple cursors in your document. Every action you perform — typing, deleting, moving, selecting — happens at all cursor positions simultaneously.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/your-demo-video" title="Multi-Cursor Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Creating Multiple Cursors

### Add Cursor at Next Match

The most common multi-cursor workflow: select a word and add cursors at each occurrence.

| Shortcut | Action                                     |
| -------- | ------------------------------------------ |
| `Ctrl+D` | Add cursor at next occurrence of selection |
| `Esc`    | Clear all secondary cursors                |

<Steps>
  <Step title="Select a word">
    Position cursor on a word (like a variable name) — if nothing is selected, `Ctrl+D` automatically selects the word under the cursor
  </Step>

  <Step title="Add cursors at matches">
    Press `Ctrl+D` repeatedly to add a cursor at each occurrence
  </Step>

  <Step title="Edit simultaneously">
    Type, delete, or move — all cursors respond in sync
  </Step>

  <Step title="Clear cursors">
    Press `Esc` to return to single cursor mode
  </Step>
</Steps>

<Tip>
  **No Selection Required**: If you press `Ctrl+D` without a selection, Fresh automatically selects the word under the cursor first, then finds the next match.
</Tip>

### Add Cursors Above/Below

Create a column of cursors for editing multiple consecutive lines:

| Shortcut     | Action                   |
| ------------ | ------------------------ |
| `Ctrl+Alt+↑` | Add cursor on line above |
| `Ctrl+Alt+↓` | Add cursor on line below |

<Steps>
  <Step title="Position initial cursor">
    Place your cursor where you want to start
  </Step>

  <Step title="Add vertical cursors">
    Press `Ctrl+Alt+↓` repeatedly to add cursors on each line below (or `Ctrl+Alt+↑` for above)
  </Step>

  <Step title="Edit all lines">
    All cursors maintain the same column position as you type
  </Step>
</Steps>

## Multi-Cursor Workflows

### Rename a Variable

The classic use case — rename all occurrences of a variable:

<CodeGroup>
  ```javascript Before theme={null}
  function calculate(value) {
    const result = value * 2;
    return result + value;
  }
  ```

  ```javascript After (using Ctrl+D) theme={null}
  function calculate(price) {
    const result = price * 2;
    return result + price;
  }
  ```
</CodeGroup>

<Steps>
  <Step title="Select first occurrence">
    Click on `value` or press `Ctrl+D` with cursor on it
  </Step>

  <Step title="Add all occurrences">
    Press `Ctrl+D` two more times to select all three occurrences
  </Step>

  <Step title="Type new name">
    Type `price` — all occurrences update simultaneously
  </Step>
</Steps>

### Edit Multiple Lines at Once

Add the same text to multiple lines:

<CodeGroup>
  ```javascript Before theme={null}
  apple
  banana
  cherry
  date
  ```

  ```javascript After theme={null}
  const apple = 'apple';
  const banana = 'banana';
  const cherry = 'cherry';
  const date = 'date';
  ```
</CodeGroup>

<Steps>
  <Step title="Position at line start">
    Move cursor to the beginning of `apple`
  </Step>

  <Step title="Add cursors below">
    Press `Ctrl+Alt+↓` three times to add cursors on each line
  </Step>

  <Step title="Type prefix">
    Type `const ` (with space)
  </Step>

  <Step title="Move to end">
    Press `End` to move all cursors to line ends
  </Step>

  <Step title="Add suffix">
    Type ` = ''` then press `←` and select each word with `Ctrl+Shift+←`, then type to fill in the quotes
  </Step>
</Steps>

### Select and Replace

Use multi-cursor with selection to replace multiple occurrences with different text:

<CodeGroup>
  ```javascript Before theme={null}
  console.log("test");
  console.log("test");
  console.log("test");
  ```

  ```javascript After theme={null}
  console.log("debug");
  console.log("info");
  console.log("error");
  ```
</CodeGroup>

<Steps>
  <Step title="Create cursors">
    Use `Ctrl+D` to select all three `"test"` strings
  </Step>

  <Step title="Delete selection">
    The selected text is replaced when you start typing
  </Step>

  <Step title="Type first replacement">
    Type `"debug"` — wait, they all get the same text!
  </Step>

  <Step title="Undo and use different approach">
    For different replacements, undo and replace them one at a time, or use cursors on each line and navigate individually
  </Step>
</Steps>

<Note>
  **Same Text Limitation**: All cursors type the same text. For different text at each cursor, you'll need to use search and replace or edit each occurrence separately.
</Note>

## Advanced Multi-Cursor Techniques

### Working with Selections

When you create a cursor with `Ctrl+D`, Fresh preserves the selection:

<Steps>
  <Step title="Select text">
    Select a word with `Ctrl+W` or manually with `Shift+Arrow`
  </Step>

  <Step title="Add cursor at next match">
    Press `Ctrl+D` — the new cursor has the same selection
  </Step>

  <Step title="Extend selections">
    Use `Shift+→` to extend all selections simultaneously
  </Step>

  <Step title="Replace selections">
    Type to replace all selected text at once
  </Step>
</Steps>

### Column Editing with Multi-Cursor

Edit a vertical column of text:

<CodeGroup>
  ```text Before theme={null}
  | Name    | Age |
  | Alice   | 30  |
  | Bob     | 25  |
  | Charlie | 35  |
  ```

  ```text After (add checkmarks) theme={null}
  | Name    | Age | ✓ |
  | Alice   | 30  | ✓ |
  | Bob     | 25  | ✓ |
  | Charlie | 35  | ✓ |
  ```
</CodeGroup>

<Steps>
  <Step title="Position at end of first line">
    Move cursor after `Age |`
  </Step>

  <Step title="Add cursors down">
    Press `Ctrl+Alt+↓` three times
  </Step>

  <Step title="Type new column">
    Type ` ✓ |` — appears on all lines
  </Step>
</Steps>

### Multi-Cursor with Block Selection

You can combine [block selection](/features/editing#block-selection) with multi-cursor:

<Steps>
  <Step title="Create block selection">
    Use `Alt+Shift+↓` and `Alt+Shift+→` to select a rectangular region
  </Step>

  <Step title="Type or edit">
    When you type, Fresh converts the block selection to multi-cursor automatically
  </Step>

  <Step title="Each line gets a cursor">
    You now have one cursor per line in the block, ready for more editing
  </Step>
</Steps>

## Multi-Cursor Behavior Details

### Cursor Synchronization

All cursors maintain synchronized offsets:

<Accordion title="What does synchronized mean?">
  When you create multiple cursors with `Ctrl+D`, Fresh ensures they all point to the same relative position within their selections. If the first cursor is at the start of its selection, all other cursors are also at the start of their selections.

  This matters when you create selections with `Shift+Left` (backward selection) vs `Shift+Right` (forward selection) — `Ctrl+D` preserves the direction.
</Accordion>

### Movement with Multiple Cursors

All cursor movement commands work with multiple cursors:

| Action              | Behavior with Multiple Cursors                      |
| ------------------- | --------------------------------------------------- |
| Arrow keys          | All cursors move in sync                            |
| `Home` / `End`      | All cursors jump to their respective line start/end |
| `Ctrl+←` / `Ctrl+→` | All cursors move by word                            |
| `PgUp` / `PgDn`     | All cursors scroll together                         |

### Editing with Multiple Cursors

All editing operations work with multiple cursors:

* **Typing**: Characters appear at all cursor positions
* **Backspace/Delete**: Removes characters at all cursors
* **Paste**: Inserts clipboard content at all cursors
* **Cut/Copy**: Captures text from all selections

<Note>
  **Undo Atomicity**: All changes made with multiple cursors are treated as a single operation. One `Ctrl+Z` undoes all the simultaneous edits and restores all cursor positions.
</Note>

## Multi-Cursor Status Indicator

The status bar shows how many cursors are active:

```
Line 10, Col 5 | 3 cursors | UTF-8 | JavaScript
```

This helps you stay aware of multi-cursor mode.

## Common Pitfalls and Solutions

<AccordionGroup>
  <Accordion title="Cursor positions are misaligned after Ctrl+D">
    **Issue**: When selecting with `Shift+Left` and then pressing `Ctrl+D`, cursors appear at different offsets (one at start, one at end).

    **Solution**: This was a bug in earlier versions and has been fixed. Update to the latest version of Fresh. All cursors now maintain synchronized positions.
  </Accordion>

  <Accordion title="Can't create cursors on lines with different lengths">
    **Issue**: Using `Ctrl+Alt+↓` on lines of varying lengths causes cursors to appear at different column positions.

    **Solution**: This is expected behavior. Each cursor maintains the same column number from the original position. Shorter lines will have cursors at their end. Use `End` key to move all cursors to their respective line ends if needed.
  </Accordion>

  <Accordion title="Lost all my cursors by accident">
    **Issue**: Pressed `Esc` or clicked the mouse and lost all secondary cursors.

    **Solution**: Use `Ctrl+Z` (undo) to restore your cursor state. Fresh's undo system tracks cursor positions.
  </Accordion>

  <Accordion title="Want to skip one occurrence when using Ctrl+D">
    **Issue**: Pressing `Ctrl+D` adds cursors sequentially, but you want to skip one match.

    **Solution**: Currently, you can't skip matches with `Ctrl+D`. Instead, use search and replace, or manually place cursors with `Ctrl+Alt+↓` and individual clicks.
  </Accordion>
</AccordionGroup>

## Multi-Cursor vs Other Tools

### When to Use Multi-Cursor

<CardGroup cols={2}>
  <Card title="Use Multi-Cursor When" icon="check">
    * Renaming a variable in a small scope
    * Adding/removing the same text on multiple lines
    * Formatting multiple similar lines
    * Making the same edit in several places you can see
  </Card>

  <Card title="Use Other Tools When" icon="xmark">
    * Renaming across many files → Use LSP rename
    * Complex pattern matching → Use regex search/replace
    * Different text at each location → Use search/replace or macros
    * Project-wide changes → Use git grep and replace
  </Card>
</CardGroup>

## Performance Notes

<Tip>
  **No Cursor Limit**: Fresh handles hundreds of cursors efficiently. However, very large numbers of cursors (1000+) may slow down rendering on some terminals.
</Tip>

<Note>
  Multi-cursor editing works efficiently even in large files (multi-gigabyte). Fresh's architecture ensures low latency regardless of file size.
</Note>

## Keyboard Reference

Quick reference for all multi-cursor shortcuts:

| Shortcut     | Action                                                                      |
| ------------ | --------------------------------------------------------------------------- |
| `Ctrl+D`     | Add cursor at next occurrence of selection (or select word if no selection) |
| `Ctrl+Alt+↑` | Add cursor on line above                                                    |
| `Ctrl+Alt+↓` | Add cursor on line below                                                    |
| `Esc`        | Clear all secondary cursors (return to single cursor)                       |
| `Ctrl+Z`     | Undo all multi-cursor edits as one operation                                |

## Related Documentation

<CardGroup cols={3}>
  <Card title="Editing Features" icon="pen-to-square" href="/features/editing">
    Learn about all editing capabilities
  </Card>

  <Card title="Search & Replace" icon="magnifying-glass" href="/features/search-replace">
    Find and replace with regex
  </Card>

  <Card title="Block Selection" icon="table-cells" href="/features/editing#block-selection">
    Rectangular selection mode
  </Card>
</CardGroup>