---
title: "CodeEditor"
description: "A CodeMirror-based editor for configuration files and code."
category: Advanced
status: beta
since: 0.3.4
tags: [code, editor, json, yaml]
syncStatus: reviewed
verified: true
---

## Usage

### Languages
`language` selects the language. JSON and YAML get formatting and linting; the others get highlighting and basic editing only.
::::TuffDemoWrapper{demo="CodeEditorCodeEditorDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const jsonValue = ref('{"name":"Tuffex","version":1}')
  const yamlValue = ref('name: Tuffex\nversion: 1\n')
  </script>

  <template>
    <TxCodeEditor v-model="jsonValue" language="json" />
    <TxCodeEditor v-model="yamlValue" language="yaml" />
  </template>
---
::::

### Toolbar
The `toolbar` slot exposes the editor methods; `TxCodeEditorToolbar` provides the standard button layout.
::::TuffDemoWrapper{demo="CodeEditorToolbarDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const actions = [
    { key: 'format', label: 'Format', icon: 'i-carbon-code' },
    { key: 'search', label: 'Search', icon: 'i-carbon-search', shortcut: '⌘F' },
    { key: 'copy', label: 'Copy', icon: 'i-carbon-copy' },
  ]
  </script>

  <template>
    <TxCodeEditor v-model="value" language="json">
      <template #toolbar="editor">
        <TxCodeEditorToolbar :actions="actions" compact @action="(key) => runAction(key, editor)" />
      </template>
    </TxCodeEditor>
  </template>
---
::::

### Best Practices

- Use JSON or YAML for configuration that needs validation and formatting; TOML, INI, and JavaScript suit highlighting and basic editing only.
- Leave `formatOnBlur` off when users may keep invalid syntax mid-edit.
- Show generated output and examples with `readOnly`, not inside disabled form fields.
- Use the toolbar for discoverability, and keep the keyboard shortcuts.
- Keep custom `extensions` narrow: they are appended after the built-ins and affect the whole editor.

## API Reference

### TxCodeEditor

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `modelValue` | `string` | `''` | The document, bound with `v-model`. |
| `language` | `'json' \| 'yaml' \| 'toml' \| 'ini' \| 'javascript' \| 'js'` | `'json'` | Language; `js` is an alias of `javascript`. |
| `theme` | `'auto' \| 'light' \| 'dark' \| 'github' \| 'dracula' \| 'monokai'` | `'auto'` | Palette; `auto` follows the page theme. |
| `readOnly` | `boolean` | `false` | Blocks editing and disables formatting. |
| `lineNumbers` | `boolean` | `true` | Shows line numbers and highlights the active line's number. |
| `lineWrapping` | `boolean` | `false` | Wraps long lines. |
| `placeholder` | `string` | `''` | Text shown while the document is empty. |
| `tabSize` | `number` | `2` | Indent width; invalid values fall back to `2`, others are rounded. |
| `formatOnBlur` | `boolean` | `false` | Runs `format()` on blur. |
| `formatOnInit` | `boolean` | `false` | Runs `format()` once after the editor mounts. |
| `lint` | `boolean` | `true` | Shows diagnostics when the language has a linter. |
| `search` | `boolean` | `true` | Enables the search panel and its shortcuts. |
| `completion` | `boolean` | `true` | Enables autocompletion, bracket closing, and their shortcuts. |
| `extensions` | `Extension[]` | `[]` | CodeMirror extensions appended after the built-ins. |

#### Events

| Event | Payload | Description |
|------|---------|-------------|
| `update:modelValue` | `string` | Fires when editing or formatting changes the document. |
| `change` | `string` | Fires together with `update:modelValue`. |
| `focus` | `()` | Fires when the editor gains focus. |
| `blur` | `()` | Fires when the editor loses focus. |
| `format` | `{ value: string; language: CodeEditorLanguage }` | Fires when formatting changes the document. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `toolbar` | `{ format, openSearch, foldAll, unfoldAll, copy, getValue }` | Toolbar above the editor, rendered once the runtime mounts. |

#### Exposed Methods

| Method | Type | Description |
|------|------|-------------|
| `focus()` | `() => void` | Focuses the editor. |
| `blur()` | `() => void` | Blurs the editor. |
| `format()` | `() => boolean` | Formats JSON/YAML; returns `false` when it can't or nothing changes. |
| `openSearch()` | `() => boolean` | Opens the search panel when `search` is on. |
| `foldAll()` | `() => boolean` | Folds every block. |
| `unfoldAll()` | `() => boolean` | Unfolds every block. |
| `copy()` | `() => Promise<boolean>` | Copies the document through `navigator.clipboard`. |
| `getValue()` | `() => string` | The current document; `modelValue` before the runtime mounts. |
| `getView()` | `() => EditorView \| null` | The CodeMirror `EditorView`; `null` before mount. |

### TxCodeEditorToolbar

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `actions` | `CodeEditorToolbarAction[]` | built-in actions | Buttons; when empty, `format`, `search`, `foldAll`, `unfoldAll`, and `copy`. |
| `compact` | `boolean` | `false` | Tightens button padding. |

#### Events

| Event | Payload | Description |
|------|---------|-------------|
| `action` | `CodeEditorToolbarActionKey` | Fires when an enabled button is clicked. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `leading` | - | Content before the buttons. |
| `trailing` | - | Content after the buttons. |

### Types

#### CodeEditorToolbarAction

| Field | Type | Description |
|------|------|-------------|
| `key` | `'format' \| 'search' \| 'foldAll' \| 'unfoldAll' \| 'copy'` | Id emitted with `action` on click. |
| `label` | `string` | Button text; falls back to a built-in English label. |
| `icon` | `TxIconSource \| string` | A `TxIcon` source or icon name. |
| `active` | `boolean` | Applies the active style. |
| `disabled` | `boolean` | Disables the button and suppresses `action`. |
| `shortcut` | `string` | Shortcut text shown after the label. |

## Overview

- The runtime editor loads dynamically after mount. Until then, exposed methods return safe fallbacks and the `toolbar` slot does not render.
- `theme="auto"` reads `data-theme` and the `dark` / `light` classes on `html` / `body`, and follows changes on `html`.
- Only JSON and YAML format and lint; indentation follows `tabSize`.
- Writing `modelValue` from outside replaces the whole document without emitting `update:modelValue` or `change`.
- `Cmd/Ctrl+Shift+F` runs `format()`. The shortcut is always intercepted, so it is swallowed even for languages without a formatter.

## Technologies

- JSON formats through `JSON.stringify` and YAML through the `yaml` package; TOML and INI highlight with local stream parsers.
- Source: `packages/tuffex/packages/components/src/code-editor/`.

<TuffDocSourceLink />

## Customization

| CSS variable | Used for |
|------|------|
| `--tx-code-editor-bg` | Shell and editor background. |
| `--tx-code-editor-border` | Shell border and toolbar divider. |
| `--tx-code-editor-toolbar-bg` | Toolbar background. |
| `--tx-code-editor-text` | Toolbar text. |
| `--tx-code-editor-focus` | Focus border and ring. |

The resolved `theme` writes these variables on the root. Prefer `theme` for palettes; override only when a host theme must tune the shell.