@viamrobotics/prime-editor
@viamrobotics/prime-editor is a CodeMirror 6 code editor for Svelte 5. It highlights with Viam’s code tokens, so it follows the light and dark themes, and it can show a diff against another text.
CodeEditor, one editor with a bindablevalue.- Six languages: TypeScript, JavaScript, JSON, Python, Go, and SQL.
- Optional line numbers, line wrapping, a placeholder, and readonly and disabled modes.
- Search and code folding from the keyboard.
- A unified or split diff view that opens when
originalis set. - An invalid state through
aria-invalid.
Installation
Section titled “Installation”-
Install the package and its peer. The
sveltepeer is^5.29.0.Terminal window pnpm add @viamrobotics/prime-editor @viamrobotics/tailwind-configTerminal window npm install @viamrobotics/prime-editor @viamrobotics/tailwind-configTerminal window yarn add @viamrobotics/prime-editor @viamrobotics/tailwind-config -
Import the stylesheet once, after Tailwind. Tailwind skips
node_moduleswhen it scans for classes, so the package’s stylesheet points it at the compiled components.@import "tailwindcss";@import "@viamrobotics/prime-editor/styles.css";
Every editor needs a name. Pass aria-label, or aria-labelledby with the id of a visible label. In a split diff the original side reads as the name followed by “original”, so the two textboxes are told apart: aria-label becomes <name>, original, and aria-labelledby adds a hidden original label after yours.
Two-way binding
Section titled “Two-way binding”bind:value holds the document. Typing writes it, and assigning it from outside replaces the document.
length: 17
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor";
let value = $state(`{\n "speed": 5\n}\n`);</script>
<div class="not-content flex w-full flex-col gap-3"> <CodeEditor aria-label="JSON config" class="max-h-48 w-full overflow-auto" language="json" bind:value /> <p class="text-sm text-subtle-2">length: <code>{value.length}</code></p> <button type="button" class="button self-start" onclick={() => (value = "{}\n")}> Reset from outside </button></div>Function binding
Section titled “Function binding”A function binding receives each edit and decides what value becomes. This one refuses an edit past 60 characters by not assigning, and transforms every other edit to uppercase. The editor reads value back after each edit, so a refused edit is undone and a transformed one replaces what was typed.
length: 21 of 60
refused edits: 0
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor";
const MAX_LENGTH = 60;
let value = $state("SELECT * FROM robots;"); let refused = $state(0);</script>
<div class="not-content flex w-full flex-col gap-3"> <CodeEditor aria-label="SQL limited to 60 characters" class="max-h-48 w-full overflow-auto" language="sql" bind:value={ () => value, (next) => { if (next.length > MAX_LENGTH) { refused += 1; return; } value = next.toUpperCase(); } } /> <p class="text-sm text-subtle-2">length: <code>{value.length}</code> of {MAX_LENGTH}</p> <p class="text-sm text-subtle-2">refused edits: <code>{refused}</code></p></div>Languages
Section titled “Languages”language picks the grammar that highlights and indents the document. Omit it for plain text.
Code
<script lang="ts"> import { CodeEditor, type CodeEditorLanguage } from "@viamrobotics/prime-editor";
import { snippets } from "./snippets.ts";
const languages = Object.keys(snippets) as CodeEditorLanguage[];</script>
<div class="not-content grid w-full gap-4 sm:grid-cols-2"> {#each languages as language (language)} <CodeEditor aria-label={`${language} example`} class="max-h-48 overflow-auto" {language} value={snippets[language].after} readonly /> {/each}</div>Readonly
Section titled “Readonly”readonly blocks edits. The document stays focusable, selectable, and copyable.
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor"; import { Checkbox, Field, Label } from "@viamrobotics/prime-ui";
let readonly = $state(true);</script>
<div class="not-content flex w-full flex-col gap-3"> <Field class="flex items-center gap-2"> <Checkbox bind:checked={readonly} /> <Label>Readonly</Label> </Field> <CodeEditor aria-label="Python snippet" class="max-h-48 w-full overflow-auto" language="python" value={`print("select this text and copy it")\n`} {readonly} /></div>Disabled and placeholder
Section titled “Disabled and placeholder”disabled turns the editor off. Unlike readonly, it takes no focus and no selection, it leaves the tab order, and the textbox is marked aria-disabled. placeholder is the text shown while the document is empty.
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor"; import { Checkbox, Field, Label } from "@viamrobotics/prime-ui";
let disabled = $state(true); let value = $state("");</script>
<div class="not-content flex w-full flex-col gap-3"> <Field class="flex items-center gap-2"> <Checkbox bind:checked={disabled} /> <Label>Disabled</Label> </Field> <CodeEditor aria-label="Query" class="max-h-64 w-full overflow-auto" language="sql" placeholder="SELECT * FROM readings" {disabled} bind:value /></div>Unified diff
Section titled “Unified diff”Set original to open the diff view. value is compared against it, and the deleted and inserted lines share one editor.
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor";
const original = `const greeting = "hello there";\nconst unused = true;\nconsole.log(greeting);\n`; let value = $state(`const greeting = "hello, world";\nconsole.log(greeting.toUpperCase());\n`);</script>
<div class="not-content w-full"> <CodeEditor aria-label="Unified diff" class="max-h-64 w-full overflow-auto" language="javascript" {original} diff="unified" bind:value /></div>Split diff
Section titled “Split diff”Set diff="split" to put original beside value. The original side is readonly. Switching between unified and split rebuilds the editor, and every other prop change reconfigures it in place.
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor";
const original = `const greeting = "hello there";\nconst unused = true;\nconsole.log(greeting);\n`; let value = $state(`const greeting = "hello, world";\nconsole.log(greeting.toUpperCase());\n`);</script>
<div class="not-content w-full"> <CodeEditor aria-label="Split diff" class="max-h-64 w-full overflow-auto" language="javascript" {original} diff="split" bind:value /></div>A long diff is mostly unchanged lines. collapseUnchanged folds each run of them into one row that expands on click, and keeps three lines of context around every change. Changing it rebuilds the editor.
Validation
Section titled “Validation”The editor does not validate the document. Check value yourself, then set aria-invalid to paint the error border and mark the textbox invalid. Point aria-describedby at the message so a screen reader reads it with the editor’s name. Every aria-* attribute goes to the textbox, so aria-errormessage and aria-required work the same way. Every other attribute, such as id, class, or an event handler, goes to the editor’s outer element.
Expected double-quoted property name in JSON at position 16 (line 3 column 1)
Code
<script lang="ts"> import { CodeEditor } from "@viamrobotics/prime-editor";
let value = $state(`{\n "speed": 5,\n}\n`);
const error = $derived.by(() => { try { JSON.parse(value); return undefined; } catch (cause) { return cause instanceof Error ? cause.message : "The config is not valid JSON."; } });</script>
<div class="not-content flex w-full flex-col gap-1"> <span id="config-label" class="text-sm font-medium">Config</span> <CodeEditor aria-labelledby="config-label" aria-describedby="config-error" aria-invalid={error !== undefined} class="max-h-64 w-full overflow-auto" language="json" bind:value /> <p id="config-error" aria-live="polite" class="min-h-4 text-xs text-danger-dark">{error}</p></div>Keyboard
Section titled “Keyboard”| Input | Action |
|---|---|
| Ctrl + F, or Cmd + F on macOS | Open the search panel |
| Enter / Shift + Enter in the search field | Go to the next or previous match |
| Escape | Close the search panel |
| Ctrl + Shift + [, or Cmd + Alt + [ on macOS | Fold the block at the cursor |
| Ctrl + Shift + ], or Cmd + Alt + ] on macOS | Unfold the block at the cursor |
| Click a fold marker in the gutter | Fold or unfold that block |
The search panel also replaces, unless the editor is readonly. The fold markers share the gutter with the line numbers, so lineNumbers={false} hides both and folding stays on the keyboard. Tab moves focus out of the editor and never indents.
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | string | '' | The document. Bind it with bind:value, or with a function binding to veto or transform
an edit. |
language | CodeEditorLanguage | The grammar that highlights and indents the document. Omit it for plain text. | |
readonly | boolean | false | Blocks edits. The document stays focusable, selectable, and copyable. |
disabled | boolean | false | Turns the editor off. The document cannot be edited, focused, or selected, and the
editing surface is marked aria-disabled. It wins over readonly. |
placeholder | string | Text shown while the document is empty. | |
lineNumbers | boolean | true | Shows the gutter, which holds the line numbers and the fold markers. |
wrapLines | boolean | false | Wraps long lines instead of scrolling them horizontally. |
original | string | The text value is compared against. Setting it opens the diff view. | |
diff | CodeEditorDiff | 'unified' | The diff view's layout while original is set. |
collapseUnchanged | boolean | false | Folds each long run of unchanged lines in the diff view into one row that expands on click. Changing it rebuilds the editor. |
aria-label | string | The accessible name of the editing surface. A split diff names the original side <name>, original. | |
aria-labelledby | string | The ids of the elements that name the editing surface. A split diff adds a hidden
original label after them on the original side. | |
aria-invalid | HTMLAttributes<HTMLDivElement>['aria-invalid'] | Marks the document invalid, and paints the error border. |
Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children'>, spread onto the element.
Requires one of aria-label or aria-labelledby.