iced-code-editor 0.3.11

A custom code editor widget for the Iced GUI framework with syntax highlighting, line numbers, and scrolling support.
Documentation

Logo

Iced Code Editor

A high-performance, canvas-based code editor widget for Iced.

Crates.io Documentation License: MIT Downloads Build Status

Overview

This crate provides a fully-featured code editor widget with syntax highlighting, line numbers, text selection, and comprehensive keyboard navigation for the Iced GUI framework.

Screenshot of the demo application:

Demo App

Features

  • Syntax highlighting for multiple programming languages via syntect
  • Line numbers with styled gutter
  • Text selection via mouse drag and keyboard shortcuts
  • Clipboard operations (copy, paste)
  • Undo/Redo with smart command grouping and configurable history
  • Custom scrollbars with themed styling
  • Focus management for multiple editors
  • Native Iced theme support - Automatically adapts to all 23+ built-in Iced themes
  • Line wrapping to split long lines
  • Code folding to collapse/expand indentation-based blocks
  • High performance canvas-based rendering
  • Search and replace text
  • Language Server Protocol (LSP) support
  • Auto indentation with custom indent style
  • Multiple cursors for simultaneous editing at multiple positions
  • Move and duplicate lines with keyboard shortcuts
  • Toggle comment on the current line or selection (Ctrl+/)
  • Visible whitespace rendering — spaces shown as ·, tabs as →
  • Optional Vim mode with Normal, Insert, Visual, and Visual Line modes

Planned features

  • Auto-closing brackets/quotes
  • Find references / Rename symbol
  • Command palette
  • Minimap

Quick Start

Add this to your Cargo.toml:

[dependencies]
iced = "0.14"
iced-code-editor = "0.3"

Basic Example

Here's a minimal example to integrate the code editor into your Iced application:

Note: CodeEditor does not automatically lose focus when another widget is clicked. You must call editor.lose_focus() whenever another interactive widget is activated. The pattern below uses mouse_area to detect clicks on sibling widgets.

use iced::widget::{column, container, mouse_area, text_input};
use iced::{Element, Task};
use iced_code_editor::{CodeEditor, Message as EditorMessage};

struct MyApp {
    editor: CodeEditor,
    input_value: String,
}

#[derive(Debug, Clone)]
enum Message {
    EditorEvent(EditorMessage),
    InputChanged(String),
    InputClicked,
}

impl Default for MyApp {
    fn default() -> Self {
        let code = r#"fn main() {
    println!("Hello, world!");
}
"#;

        Self {
            editor: CodeEditor::new(code, "rust"),
            input_value: String::new(),
        }
    }
}

impl MyApp {
    fn update(&mut self, message: Message) -> Task<Message> {
        match message {
            Message::EditorEvent(event) => {
                self.editor.update(&event).map(Message::EditorEvent)
            }
            Message::InputChanged(value) => {
                self.input_value = value;
                self.editor.lose_focus(); // required: transfer focus away from editor
                Task::none()
            }
            Message::InputClicked => {
                self.editor.lose_focus(); // required: transfer focus away from editor
                Task::none()
            }
        }
    }

    fn view(&self) -> Element<'_, Message> {
        let input = mouse_area(
            text_input("Type something...", &self.input_value)
                .on_input(Message::InputChanged)
                .padding(8),
        )
        .on_press(Message::InputClicked); // detect click to trigger lose_focus

        container(
            column![input, self.editor.view().map(Message::EditorEvent)]
                .spacing(10)
                .height(iced::Fill),
        )
        .padding(20)
        .into()
    }
}

fn main() -> iced::Result {
    iced::run(MyApp::update, MyApp::view)
}

Vim Mode

Vim behavior is disabled by default and configured independently for each CodeEditor instance. Enabling it enters Normal mode and collapses any multi-cursor state to the primary cursor:

use iced_code_editor::{CodeEditor, VimMode};

let mut editor =
    CodeEditor::new("fn main() {}", "rs").with_vim_enabled(true);
assert!(editor.vim_enabled());
assert_eq!(editor.vim_mode(), Some(VimMode::Normal));

editor.set_vim_enabled(false);
assert_eq!(editor.vim_mode(), None);

With the editor focused, press Ctrl+Alt+V (or Command+Alt+V on macOS) to switch between Vim and standard editing. Enabling Vim always starts in Normal mode. The regular Ctrl/Command+V system-paste shortcut is unchanged.

The MVP supports these keys:

Context Keys Behavior
Normal/Visual motion h, j, k, l Move left, down, up, or right
Normal/Visual motion w, b, e Move to the next word, previous word, or word end
Normal/Visual motion 0, ^, $ Move to line start, first non-blank, or line end
Normal/Visual motion gg, G Move to document start or end when no count is given
Normal/Visual motion [count]gg, [count]G Jump to the 1-based logical line, e.g. 5G or 5gg jumps to line 5
Enter Insert i, a, I, A Insert before/after the cursor, at first non-blank, or at line end
Enter Insert o, O Open line(s) below or above
Select v, V Enter character-wise Visual or Visual Line mode
Operators d{motion}, c{motion}, y{motion} Delete, change, or yank through any supported motion
Line operators [count]dd, [count]cc, [count]yy Delete, change, or yank consecutive lines, e.g. 5yy yanks five lines
Visual operators d, c, y Apply the operator to the Visual selection
Direct edits x, p, P Delete characters; paste after or before from the unnamed register
History u, Ctrl+R Undo or redo
Search /pattern, then Enter Search forward from the cursor and wrap at the end
Search repeat n, N Repeat the last search forward or backward
Go to line :N, then Enter Jump to 1-based logical line N, clamped to the document
Save :w, then Enter Request that the host save the current document
Exit Vim mode :q, then Enter Disable Vim behavior for the current editor
Save and exit Vim mode :wq, then Enter Request a save and disable Vim behavior
Command line Backspace, Escape Edit or cancel the active / or : input
Mode exit Escape Return to Normal mode and clear pending prefixes/selections
Count prefix 1–9, then 0 Repeat motions, line operators, x, paste, undo, or opened lines; operator and motion counts multiply

When Vim mode is enabled, a fixed status line below the editor shows the current mode. While entering /pattern or :N, it shows the command and current input; otherwise it shows pending Normal-mode keys such as 5d or 3g. The status line remains visible while the document scrolls.

j and k move by visible display lines, so they follow wrapped lines and skip folded content. Vim mode is intentionally single-cursor; attempts to add extra cursors are ignored while it is enabled.

Vim d, c, y, x, p, and P use an unnamed register stored inside that editor instance. It distinguishes character-wise and line-wise content and does not access the system clipboard. Platform Ctrl/Command clipboard shortcuts (C, X, and V) keep their existing system-clipboard behavior and take priority over Vim parsing.

Because the editor does not own a file path or perform disk I/O, :w, :wq, and Ctrl/Command+S emit Message::WriteRequested. Hosts should intercept that message and save the corresponding document. The demo app binds all three inputs to its existing Save/Save As flow.

This is a focused MVP, not full Vim compatibility. Apart from the supported :N line jump and :q/:w/:wq commands, it does not implement Ex commands. It also does not implement regex search, search history, text objects, macros, named registers, marks, . repeat, or configurable key mappings.

Keyboard Shortcuts

The editor supports a comprehensive set of keyboard shortcuts:

Navigation

Shortcut Action
Arrow Keys (Up, Down, Left, Right) Move cursor
Shift + Arrows Move cursor with selection
Home / End Jump to start/end of line
Shift + Home / Shift + End Select to start/end of line
Ctrl + Home / Ctrl + End Jump to start/end of document
Page Up / Page Down Scroll one page up/down

Editing

Shortcut Action
Backspace Delete character before cursor (or delete selection if text is selected)
Delete Delete character after cursor (or delete selection if text is selected)
Shift + Delete Delete selected text (same as Delete when selection exists)
Enter Insert new line
Tab Insert indent
Alt + Up/Down Move current line (or selected lines) up/down
Shift + Alt + Up/Down Duplicate current line (or selected lines) above/below
Ctrl + / Toggle line comment on current line (or selected lines)

Clipboard

Shortcut Action
Ctrl + C or Ctrl + Insert Copy selected text
Ctrl + V or Shift + Insert Paste from clipboard

Undo/Redo

Shortcut Action
Ctrl + Z Undo last operation
Ctrl + Y Redo last undone operation

The editor features smart command grouping - consecutive typing is grouped into single undo operations, while navigation or deletion actions create separate undo points.

Multiple Cursors

Shortcut Action
Alt + Click Add a cursor at the clicked position
Ctrl + Alt + Up Add a cursor on the line above
Ctrl + Alt + Down Add a cursor on the line below
Ctrl + D Select the next occurrence of the current word/selection
Escape Collapse all cursors back to one (when search dialog is closed)

All editing operations (typing, backspace, delete, enter, tab, paste) apply simultaneously to every cursor. Copy with multiple selections joins all selected texts with newlines. Paste with the same number of clipboard lines as cursors pastes one line per cursor.

Search and Replace

Shortcut Action
Ctrl + F Open search dialog
Ctrl + H Open search and replace dialog
F3 Find next match
Shift + F3 Find previous match
Escape Close search dialog

Code Folding

These shortcuts are active only when code folding is enabled:

Shortcut Action
Ctrl + . Toggle fold of the block at the cursor
Ctrl + K Fold all blocks
Ctrl + J Unfold all blocks

You can also click the fold chevrons (▼ / ▶) in the gutter to collapse or expand a block.

LSP Completion

These shortcuts are active only when the LSP completion menu is visible:

Shortcut Action
Arrow Up Navigate to previous completion item
Arrow Down Navigate to next completion item
Enter Confirm and apply selected completion
Escape Close completion menu
Arrow Left / Arrow Right Clear completion menu

Usage Examples

Custom context menu

Custom context-menu actions are identified by stable strings chosen by your application. Custom entries appear before the built-in editing actions:

use iced_code_editor::{CodeEditor, ContextMenuEntry};

let editor = CodeEditor::new("fn main() {}", "rust")
    .with_custom_context_menu_entries(vec![
        ContextMenuEntry::item(
            "app.format_document",
            "Format document",
        )
        .with_shortcut("Ctrl+Shift+F"),
        ContextMenuEntry::separator(),
        ContextMenuEntry::item("app.rename_symbol", "Rename symbol")
            .with_enabled(false),
    ])
    .with_default_context_menu_enabled(true);

The editor automatically adds a separator between the custom and built-in groups. Pass false to with_default_context_menu_enabled to replace the built-in menu completely. At runtime, use set_custom_context_menu_entries and set_default_context_menu_enabled to update the same configuration.

Handle custom actions in the outer application before forwarding other editor messages to CodeEditor::update:

match event {
    EditorMessage::CustomContextMenuAction(id) => {
        match id.as_str() {
            "app.format_document" => format_document(),
            "app.rename_symbol" => rename_symbol(),
            unknown => {
                eprintln!(
                    "Ignoring unknown context-menu action: {unknown}"
                );
            }
        }
        Task::none()
    }
    other => editor.update(&other).map(Message::EditorEvent),
}

Unknown IDs should be ignored or logged explicitly. The editor emits custom action IDs unchanged and does not interpret or execute them internally.

The built-in labels follow the language configured with set_language. Custom-entry labels are supplied by the host application, so localize those strings before passing them to the editor.

Applications with a real filesystem path can opt into the built-in reveal request:

editor.set_reveal_in_file_manager_enabled(file_path.is_some());

match event {
    EditorMessage::RevealInFileManager => {
        reveal_file(file_path.as_deref());
        Task::none()
    }
    other => editor.update(&other).map(Message::EditorEvent),
}

The menu label is platform-specific: Reveal in Finder on macOS, Reveal in File Explorer on Windows, and Open Containing Folder on other desktop platforms. The editor only emits the request; the host is responsible for invoking the operating system and reporting failures. The demo enables this item for tabs backed by a desktop path and keeps it hidden for untitled tabs and WebAssembly.

Changing Themes

The editor uses TokyoNightStorm as the default theme. It automatically adapts to any Iced theme. All 23+ built-in Iced themes are supported:

use iced_code_editor::theme;

// Apply any built-in Iced theme
editor.set_theme(theme::from_iced_theme(&iced::Theme::TokyoNightStorm));
editor.set_theme(theme::from_iced_theme(&iced::Theme::Dracula));
editor.set_theme(theme::from_iced_theme(&iced::Theme::Nord));
editor.set_theme(theme::from_iced_theme(&iced::Theme::CatppuccinMocha));
editor.set_theme(theme::from_iced_theme(&iced::Theme::GruvboxDark));

// Or use any theme from Theme::ALL
for theme in iced::Theme::ALL {
    editor.set_theme(theme::from_iced_theme(theme));
}

Getting and Setting Content

// Get current content
let content = editor.content();

// Check if content has been modified
if editor.is_modified() {
    println!("Editor has unsaved changes");
}

// Mark content as saved (e.g., after saving to file)
editor.mark_saved();

Enable/disable search/replace

The search/replace functionality is enabled by default. It can be toggled on or off. When disabled, search shortcuts (Ctrl+F, Ctrl+H, F3) are ignored and the search dialog is hidden:

// Disable search/replace functionality
editor.set_search_replace_enabled(false);

// Or use builder pattern during initialization
let editor = CodeEditor::new("code", "rs")
    .with_search_replace_enabled(false);

// Check current state
if editor.search_replace_enabled() {
    println!("Search and replace is available");
}

This is useful for read-only editors or when you want to provide your own search interface.

Open search/replace from your own buttons

Besides keyboard shortcuts, you can open or close the dialogs via API:

// Open search dialog (same as Ctrl+F)
let task = editor.open_search_dialog();

// Open search+replace dialog (same as Ctrl+H)
let task = editor.open_search_replace_dialog();

// Close dialog (same as Esc)
let task = editor.close_search_dialog();

Return these tasks from your app update function after mapping to your message type.

Enable/disable line wrapping

Line wrapping is enabled by default at viewport width. Long lines can be wrapped automatically at the viewport width or at a fixed column:

// Enable line wrapping at viewport width
editor.set_wrap_enabled(true);

// Wrap at a fixed column (e.g., 80 characters)
let editor = CodeEditor::new("code", "rs")
    .with_wrap_enabled(true)
    .with_wrap_column(Some(80));

// Disable wrapping
editor.set_wrap_enabled(false);

// Check current state
if editor.wrap_enabled() {
    println!("Line wrapping is active");
}

When enabled, wrapped lines show a continuation indicator (↪) in the line number gutter.

Enable/disable code folding

Code folding is enabled by default. Foldable regions are detected from indentation: a line is a fold header when the following non-blank line is more deeply indented (language-agnostic, works for Rust, Python, YAML, etc.). When enabled, a fold margin with clickable chevrons (▼ expanded, ▶ collapsed) is shown in the gutter, and a ⋯ marker appears after a collapsed block header.

// Disable code folding (chevrons hidden, all lines shown)
editor.set_folding_enabled(false);

// Or use builder pattern during initialization
let editor = CodeEditor::new("code", "rs")
    .with_folding_enabled(false);

// Check current state
if editor.folding_enabled() {
    println!("Code folding is active");
}

Folds can also be driven programmatically (useful for your own buttons or commands):

// Toggle the fold of the block whose header is a given logical line
editor.toggle_fold(0);

// Toggle / fold / unfold the innermost block containing a line
editor.toggle_fold_at(line);
editor.fold_at(line);
editor.unfold_at(line);

// Fold or unfold every block at once
editor.fold_all();
editor.unfold_all();

// Query whether a header line is collapsed
if editor.is_folded(0) {
    println!("Block at line 0 is collapsed");
}

When folding is disabled, the collapsed state is preserved (so re-enabling restores the previously collapsed blocks) but no lines are hidden.

Enable/disable line numbers

Line numbers are displayed by default. They can be hidden to maximize space for code:

// Hide line numbers
editor.set_line_numbers_enabled(false);

// Or use builder pattern during initialization
let editor = CodeEditor::new("code", "rs")
    .with_line_numbers_enabled(false);

// Show line numbers (default behavior)
editor.set_line_numbers_enabled(true);

// Check current state
if editor.line_numbers_enabled() {
    println!("Line numbers are visible");
}

When disabled, the gutter is completely removed (0px width), providing more horizontal space for code display.

Visible whitespace rendering

Whitespace rendering is enabled by default. Spaces are displayed as · and tab characters as → (with · fill to preserve alignment), both drawn in a dimmed color that blends with the active theme.

// Disable whitespace rendering
editor.set_show_whitespace(false);

// Re-enable it
editor.set_show_whitespace(true);

// Check current state
if editor.show_whitespace() {
    println!("Whitespace is visible");
}

The whitespace color is derived automatically from the active theme via Style::whitespace_color and can be overridden in a custom Style.

Indentation

Auto-indentation is enabled by default: pressing Enter copies the leading whitespace of the current line to the new line. The indentation style (spaces or tab) is 4 spaces by default and controls what is inserted when pressing Tab.

// Disable auto-indentation on Enter
editor.set_auto_indent_enabled(false);

// Check current state
if editor.auto_indent_enabled() {
    println!("Auto-indentation is active");
}

use iced_code_editor::IndentStyle;

// Use 2 spaces per indent level
editor.set_indent_style(IndentStyle::Spaces(2));

// Use tabs instead of spaces
editor.set_indent_style(IndentStyle::Tab);

// Restore the default (4 spaces)
editor.set_indent_style(IndentStyle::Spaces(4));

// Check current style
match editor.indent_style() {
    IndentStyle::Spaces(n) => println!("Indenting with {n} spaces"),
    IndentStyle::Tab => println!("Indenting with tabs"),
}

Available styles via IndentStyle::ALL: Spaces(2), Spaces(4), Spaces(8), Tab.

Language Server Protocol (LSP)

LSP support provides hover documentation, auto-completion, and go-to-definition. It requires the lsp-process feature (not available on WASM):

[dependencies]
iced-code-editor = { version = "0.3", features = ["lsp-process"] }

Enable/disable LSP on an editor

// Enable LSP (attach a client and open the document)
editor.set_lsp_enabled(true);

// Disable LSP (detach the client)
editor.set_lsp_enabled(false);

Connecting an LSP server

use std::sync::mpsc;
use iced_code_editor::{LspProcessClient, LspEvent, LspDocument};

// Create a channel to receive LSP events
let (tx, rx) = mpsc::channel::<LspEvent>();

// Start the server (e.g., lua-language-server)
let client = LspProcessClient::new_with_server(
    "file:///path/to/project",
    tx,
    "lua-language-server",
)?;

// Attach the client to an editor with a document URI
editor.attach_lsp(
    Box::new(client),
    LspDocument::new("file:///path/to/file.lua", "lua"),
);

Rendering the overlay (hover + completion)

Use LspOverlayState to hold display state and view_lsp_overlay to render it:

use iced_code_editor::{LspOverlayState, LspOverlayMessage, view_lsp_overlay};

struct App {
    editor: CodeEditor,
    overlay: LspOverlayState,
}

#[derive(Clone)]
enum Message {
    LspOverlay(LspOverlayMessage),
    // ...
}

fn view(app: &App) -> Element<'_, Message> {
    // Stack the overlay on top of the editor
    stack![
        app.editor.view().map(Message::EditorEvent),
        view_lsp_overlay(
            &app.overlay,
            &app.editor,
            &app.theme,
            14.0,    // font size
            20.0,    // line height
            Message::LspOverlay,
        ),
    ].into()
}

Poll LspEvents from the channel on each tick and update the overlay state:

// On LspEvent::Hover
overlay.show_hover(text);

// On LspEvent::Completion
overlay.set_completions(items, cursor_position);

Supported servers

Out of the box, the following servers are supported (the binary must be on $PATH):

Server key Language
rust-analyzer Rust
pyright Python
typescript-language-server JS / TS
lua-language-server Lua
gopls Go

Changing font

The default font of the editor is iced::Font::MONOSPACE. It can be changed with one of the default iced font or by loading a specific font:

let font = iced::font::Family::SansSerif;
editor.set_font(font);

The editor support CJK font.

The default font size is 14px. It can be changed:

editor.set_font_size(12.0, true);

Themes

The editor natively supports all built-in Iced themes with automatic color adaptation.

Each theme automatically provides:

  • Optimized background and foreground colors
  • Adaptive gutter (line numbers) styling
  • Appropriate text selection colors
  • Themed cursor appearance
  • Custom scrollbar styling
  • Subtle current line highlighting

The editor intelligently adapts colors from the Iced theme palette for optimal code readability.

Demo Screenshot Dark Theme Demo Screenshot Light Theme

Supported Languages

The editor supports syntax highlighting for numerous languages via the syntect crate:

  • Rust ("rs" or "rust")
  • Python ("py" or "python")
  • JavaScript/TypeScript ("js", "javascript", "ts", "typescript")
  • Lua ("lua")
  • C/C++ ("c", "cpp", "c++")
  • Java ("java")
  • Go ("go")
  • HTML/CSS ("html", "css")
  • Markdown ("md", "markdown")
  • And many more...

For a complete list, refer to the syntect documentation.

Demo Application

A full-featured demo application is included in the demo-app directory, showcasing:

  • File operations (open, save, save as)
  • Theme switching
  • Modified state tracking
  • Clipboard operations
  • Full keyboard navigation

Run it with:

cargo run --package demo-app --release

Simple Example

A minimal standalone example is available in the simple-example directory. It demonstrates the basic integration pattern with a text_input sibling widget and focus management:

cargo run --package simple-example

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Check docs\DEV.md for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Built with Iced - A cross-platform GUI library for Rust
  • Syntax highlighting powered by syntect