HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
SandboxView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorAn editable source pane paired with a live preview.StableSince 0.1.0ToolingUsageimport'@fusion.dev/helix/sandbox'import'@fusion.dev/helix-sandbox/editor'// Sandbox EditorPreview
API ReferenceRoothelix-sandboxAn editable source pane paired with a live preview.
PropTypeDescriptioncornerLabelstringDefault"Resize panes and panel"The name of the corner handle that moves both dividers at once, read by
screen readers.defaultPanelSizenumberDefault160The panel height a reset restores, in pixels.defaultSplitnumberDefault50Where a reset puts the divider between the panes.filestringThe name of the source pane shown, where the sandbox holds several.filesLabelstringDefault"Files"The name of the file tabs, read by screen readers.lead"source"|"preview"Default"source"Which pane comes first, before the divider.modifiedLabelstringDefault"Modified"The description of a file tab whose pane holds an edit, read by screen
readers after the file's name.orientation"horizontal"|"vertical"Whether the panes sit side by side or stacked.panelCollapsedSizenumberDefault0The panel's height when it is closed.panelLabelstringDefault"Resize panel"The name of the panel's divider, read by screen readers.panelSizenumberDefault160Height of the panel, in pixels.previewDelaynumberDefault300How long typing rests before the preview runs the new source, in
milliseconds, as Sandpack's recompileDelay does. The preview reloads its
frame on each run, so a word typed runs it once. 0 runs it on every
edit.separatorLabelstringDefault"{pane, select, preview {Resize preview pane} other {Resize source pane}}"The name of the divider between the panes, read by screen readers.
{pane} is the lead pane, source or preview, whose share the
divider's value is, so each is a whole sentence: "Resize source pane" or
"Resize preview pane".splitnumberDefault50Percentage of the sandbox given to the lead pane: the source, unless lead
is preview.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptionpanelA panel under both panes, usually a console.previewThe live preview. It comes second unless lead is preview.sourceThe editable source pane. It comes first unless lead is preview.statusA status bar, spanning both panes at the bottom.toolbarA bar across the top, spanning both panes.
EventTypeDescriptionchangeEventA file tab showed its pane, whose namefile now holds.helix-before-changeHelixBeforeChangeEventFired before a file tab shows its pane, with the pane's name. Cancelable: cancel it to keep the pane shown.helix-before-editHelixBeforeEditEventFired before the source is edited. The source pane dispatches it, and you can listen for it on the sandbox. Cancelable: cancel it to keep the source unchanged.helix-before-panel-resizeHelixBeforePanelResizeEventFired before the panel's divider is released, with the panel's height in pixels. A panel dragged closed reports panel-collapsed-size, its smallest height. Cancelable: cancel it to keep the current height.helix-before-splitHelixBeforeSplitEventFired before the panes' divider is released, with the lead pane's share. Cancelable: cancel it to keep the current split.helix-caretHelixCaretEventFired when the cursor moves in the source. The source pane dispatches it, and you can listen for it on the sandbox.helix-consoleHelixConsoleEventFired once per console call in the preview frame. The preview pane dispatches it.helix-editHelixEditEventFired after the source was edited, with the new source. The source pane dispatches it, and you can listen for it on the sandbox.helix-panel-resizeHelixPanelResizeEventFired after the panel's divider settled at a new height, with the height in pixels.helix-resizeHelixResizeEventFired by the preview pane when the height of the frame's content changes, with the new height.helix-splitHelixSplitEventFired after the panes' divider settled somewhere new, with the lead pane's share.
MethodTypeDescriptionreset() => voidPuts every source pane back to the source it was given: through the
pane's own reset() where it has one, which sends an edit the previews
take, and otherwise by setting its value and writing it into the
previews.
PartDescriptionbodyThe splitter holding the panes above the panel. ::part(body):state(dragging) matches while its divider is held.cornerThe handle where the two dividers cross.fileOne file tab, aria-selected while its pane is shown.file-modifiedA file tab whose pane holds an edit.filesThe file tabs over the source panes, where there are several.paneEither pane.panelThe box that holds the slotted panel.panesThe splitter holding the source and preview panes. ::part(panes):state(dragging) matches while its divider is held.separatorEither divider.
CSS PropertyDescription--sandbox-grabThe invisible width of a divider's drag target.--sandbox-min-block-sizeMinimum height of the sandbox.--sandbox-separator-colorColor of the divider.
Custom stateDescriptionmodifiedWhile a source pane holds an edit, until reset().panel-collapsedWhile there is a panel and it is no taller than panel-collapsed-size.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Consolehelix-sandbox-consoleA panel that shows what the previewed example wrote to the console.
PropTypeDescriptionclearLabelstringDefault"Clear"The clear button's text, under controls.controlsbooleanDefaultfalseShows a level filter and a clear button above the log.emptyLabelstringDefault"Nothing written to the console yet."Text shown before anything has been written, and while the level filter
hides every line.labelstringDefault"Console output"The log's name, read by screen readers.levelConsoleLevelThe quietest level shown: info hides plain logs, warn shows warnings
and errors, and error shows errors only. Absent shows every line.levelLabelstringDefault"Levels shown"The level filter's name, read by screen readers, under controls.levelWordsPartial<Record<ConsoleLevel, string>>Default{ error: "Errors", info: "Info and above", log: "All levels", warn: "Warnings and errors", }What each choice of the level filter reads, for a page in another
language, keyed by level, such as { warn: '…' }. A level left out keeps
its English words. As an attribute it is that object as JSON, and JSON
that does not parse is no words.spokenWordsPartial<Record<ConsoleLevel, string>>Default{ error: "Error:", info: "Info:", warn: "Warning:", }What a screen reader hears before a new line at each level, keyed by
level, such as { warn: 'Warnung:' }. A plain log hears nothing before
its text, and nor does a line whose text already starts with its words,
such as Error: Boom from console.error(error). As an attribute it is
that object as JSON.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionchangeEventFired after the reader chose another level in the filter. level holds it.helix-before-changeHelixBeforeChangeEventFired before the level filter changes, with the level chosen, log for every level. Cancelable: cancel it to keep the current level.
MethodTypeDescriptionclear() => voidEmpties the console.write(detail: ConsoleDetail) => voidAdds a line, which the log folds into the one above where they are the
same, and tells a screen reader, unless it repeats the line before it.
PartDescriptionclearThe button that empties the console, under controls.clear-buttonThe clear button's inner button.clear-liveThe clear button's live region, which speaks while the button is pending.clear-spinnerThe ring the clear button turns while it is pending.clear-textThe clear button's words.controlsThe row holding the level filter and the clear button, under controls.filterThe level filter, a native select, under controls.liveWhere screen readers hear each new line. Visually hidden.outputThe Log the lines are drawn in.output-afterThe log's after part.output-beforeThe log's before part.output-droppedThe log's dropped part.output-emptyThe log's empty part.output-group-contentThe log's group-content part.output-group-durationThe log's group-duration part.output-group-headingThe log's group-heading part.output-group-markThe log's group-mark part.output-group-statusThe log's group-status part.output-group-summaryThe log's group-summary part.output-group-summary-doneThe log's group-summary-done part.output-group-summary-failedThe log's group-summary-failed part.output-group-summary-pendingThe log's group-summary-pending part.output-group-summary-runningThe log's group-summary-running part.output-group-summary-skippedThe log's group-summary-skipped part.output-lineThe log's line part.output-line-countThe log's line-count part.output-line-count-labelThe log's line-count-label part.output-line-debugThe log's line-debug part.output-line-errorThe log's line-error part.output-line-groupedThe log's line-grouped part.output-line-levelThe log's line-level part.output-line-markedThe log's line-marked part.output-line-matchThe log's line-match part.output-line-numberThe log's line-number part.output-line-runThe log's line-run part.output-line-run-boldThe log's line-run-bold part.output-line-run-dimThe log's line-run-dim part.output-line-run-italicThe log's line-run-italic part.output-line-run-strikeThe log's line-run-strike part.output-line-run-underlineThe log's line-run-underline part.output-line-selectedThe log's line-selected part.output-line-textThe log's line-text part.output-line-timeThe log's line-time part.output-line-warnThe log's line-warn part.output-liveThe log's live part.output-loadingThe log's loading part.output-logThe log's log part.output-resumeThe log's resume part.output-resume-buttonThe log's resume-button part.output-resume-markThe log's resume-mark part.output-rowThe log's row part.output-toolbarThe log's toolbar part.
CSS PropertyDescription--sandbox-console-sizeHeight of the console.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Editorhelix-sandbox-editorExperimentalAn editable pane of source, with highlighting and line numbers.
PropTypeDescriptionfieldLabelstringDefault"Example source"Accessible name for the editable region.language"css"|"html"|"javascript"|"js"|"jsx"|"mjs"|"sh"|"ts"|"tsx"Default"html"The language of the source, which decides how it is highlighted. A name
the editor does not read draws the source plain.namestringDefault"html"Which source this pane holds, echoed in every change.readOnlybooleanDefaultfalseWhether the text can be changed.valuestringDefault""The source being edited.
ReadTypeDescriptioncaretCaretDetailWhere the cursor is, counted from one, as an editor reports it.modifiedbooleanWhether the source differs from the source the editor was given: its
first value, or the last one set from outside.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-before-editHelixBeforeEditEventFired before the source is edited. Cancelable: refusing it takes the decision and nothing moves.helix-caretHelixCaretEventFired when the cursor moves, with its line and column.helix-editHelixEditEventFired after the source was edited, with the new source.
MethodTypeDescriptionfocus() => voidMoves focus into the text, not onto the host.reset() => voidPuts back the source the editor was given, as an edit: helix-before-edit
is sent first and can refuse it, and a sandbox passes it to its preview.
PartDescriptioneditorThe element CodeMirror is mounted into.
Custom stateDescriptionmodifiedWhile the source differs from the source the editor was given, until reset() or a new value.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Previewhelix-sandbox-previewA frame that renders sandbox source in a separate document.
PropTypeDescriptioncdnstringDefault"https://esm.sh/"The address the packages in dependencies load from, which the name, an
@ and the version follow.colorMode"dark"|"light"The color mode the frame renders in.controlsbooleanDefaultfalseWhether the preview draws a reload button and a button that opens the
example in a new tab, in its corner.dependenciesRecord<string, string>The npm packages an example can import by name in the built-in document,
each name to a version or a range, as a package.json lists them. Each
loads from cdn. Set it as JSON in the attribute or as an object. Not
read where src is set.direction"rtl"Writing direction inside the frame.importsRecord<string, string>The packages an example can import by name in the built-in document,
each mapped to the address of an ES module, as an import map's imports.
Set it as JSON in the attribute or as an object. Not read where src is
set.labelstringDefault"Preview"The frame's name, read by screen readers.layout"padded"|"centered"|"fullscreen"|"hug"How the example is placed in the frame.modulesRecord<string, string>Module files an example imports by a relative path in the built-in
document, each path, such as utils.js, to its source. Not read where
src is set.openLabelstringDefault"Open preview in a new tab"The name of the button that opens the example in a new tab, under
controls.relaystringDefault""Path prefixes the frame may ask this page to fetch for it, separated by
spaces, each starting and ending with a slash, such as /sandbox/ /fonts/.
Empty relays nothing.reloadLabelstringDefault"Reload preview"The name of the button that reloads the frame's document, under
controls.scriptstringDefault""A script to run as a module after the markup, on every render of new
source. A sandbox writes its js pane here.sourcestringDefault""Markup to render.srcstringDefault""The document the frame loads. It provides the styles and the elements.
Empty loads the built-in document, which defines no element.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-consoleHelixConsoleEventFired once per console call in the frame.helix-resizeHelixResizeEventFired when the height of the frame's content changes, with the new height.
MethodTypeDescriptionopen() => Window | nullOpens the example in a new tab, and returns the tab's window, or null
where the browser refused to open one.reload() => voidLoads the frame's document again, and re-sends the example to it.
PartDescriptioncontrolsThe buttons in the preview's corner, under controls.errorThe error the example threw and did not catch, shown over it while the preview is failed.frameThe iframe.openThe button that opens the example in a new tab, under controls.reloadThe button that reloads the frame's document, under controls.
Custom stateDescriptionblankFrom the moment the frame's document starts loading until it has drawn an example. The styled tier keeps the frame transparent meanwhile, so a document that has not yet drawn in the page's color mode does not show as a white flash.failedSince the example threw an error it did not catch, until the next source is sent.loadingWhile the frame's document loads, until it can take the example.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Sourcehelix-sandbox-sourceAn editable source pane for a sandbox preview.
PropTypeDescriptioncloseBracketsbooleanDefaultfalseWhether typing an opening bracket or quote types its closing one too, and
a bracket typed with text selected goes around it.completebooleanDefaultfalseWhether the pane offers completions for the word before the caret, from
the words of the source and of completions.completionsreadonlystring[]Default[]Words the pane offers under complete beside the words of the source,
such as tag and attribute names. manifestWords reads them from a custom
elements manifest. Set it as JSON in the attribute or as an array.completionsLabelstringDefault"Completions"The name of the list of completions, read by screen readers.fieldLabelstringDefault"Example source"The editable region's name, read by screen readers.fieldNameLabelstringDefault"{field}, {name}"The editable region's name where the pane has a label, so each file's
field says which file it holds. {field} is field-label and {name}
the pane's label.keysDescriptionstringDefault"Tab inserts two spaces. To leave, press Escape and then Tab, or press Shift+Tab to go back."The field's description, read by screen readers while Tab indents.labelstringDefault""The pane's file name, such as index.html, on its tab where a sandbox
holds several panes. Empty puts the pane's name on the tab.lineNumbersbooleanDefaultfalseWhether each line of the source is numbered, in a gutter beside it.matchBracketsbooleanDefaultfalseWhether the bracket beside the caret and its pair are marked while the
field has focus.namestringDefault"html"Which source this pane holds. Every helix-before-edit event includes it.readOnlybooleanDefaultfalseWhether the source is read only: it can be selected and copied, and not
edited, as Sandpack's readOnly file is. Tab moves focus out of a field
that is read only.tabIndentsbooleanDefaulttrueWhether Tab indents the source. When it is off, Tab moves focus.tokenizeSandboxTokenizerColors the source: a function from the source and the pane's name to
runs of text, each with an optional kind, such as
[{ text: '<' }, { kind: 'tag', text: 'p' }, { text: '>' }].valuestringDefault""The source being edited.
ReadTypeDescriptionmodifiedbooleanWhether the source differs from the source the pane was given: its first
value, or the last one set from outside.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-before-editHelixBeforeEditEventFired before the source is edited. Cancelable: cancel it to keep the source unchanged.helix-caretHelixCaretEventFired when the cursor moves.helix-editHelixEditEventFired after the source was edited, with the new source.
MethodTypeDescriptionreset() => voidPuts back the source the pane was given, as an edit: helix-before-edit
is sent first and can refuse it, and the sandbox passes it to its preview.
PartDescriptionbracketThe bracket beside the caret and its pair, under match-brackets.bracket-unmatchedA bracket beside the caret with no pair, under match-brackets.completionOne word in the list of completions, under complete.completion-activeThe word chosen in that list, which Enter or Tab takes.completionsThe list of completions under the word being typed, under complete.fieldThe box that scrolls the field and its colors together, under tokenize, line-numbers, match-brackets or complete.highlightThe colored copy of the source drawn under the field, under tokenize, line-numbers, match-brackets or complete.lineOne line of that copy, under line-numbers, numbered in the gutter by its ::before.sourceThe editable region.tokenOne run of the source that has a kind, under tokenize.
CSS PropertyDescription--sandbox-source-background-colorFill behind the source.--sandbox-source-bracket-colorFill behind a matched bracket, under match-brackets. Defaults to --helix-color-accent-subtle.--sandbox-source-callable-colorColor of a callable run, under tokenize. Defaults to --helix-color-syntax-callable.--sandbox-source-comment-colorColor of a comment run, under tokenize. Defaults to --helix-color-syntax-comment.--sandbox-source-completions-border-widthWidth of the edge of the list of completions, under complete. Defaults to --helix-border-floating.--sandbox-source-completions-shadowShadow under the list of completions, under complete. Defaults to --helix-shadow-floating.--sandbox-source-constant-colorColor of a constant run, under tokenize. Defaults to --helix-color-syntax-constant.--sandbox-source-invalid-colorColor of an invalid run, under tokenize. Defaults to --helix-color-syntax-invalid.--sandbox-source-keyword-colorColor of a keyword run, under tokenize. Defaults to --helix-color-syntax-keyword.--sandbox-source-line-number-colorColor of the line numbers, under line-numbers. Defaults to --helix-color-foreground-muted.--sandbox-source-min-block-sizeMinimum height of the pane.--sandbox-source-name-colorColor of a name run, under tokenize. Defaults to --helix-color-syntax-name.--sandbox-source-string-colorColor of a string run, under tokenize. Defaults to --helix-color-syntax-string.--sandbox-source-tag-colorColor of a tag run, under tokenize. Defaults to --helix-color-syntax-tag.
Custom stateDescriptionmodifiedWhile the source differs from the source the pane was given, until reset() or a new value.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
StatusBarhelix-sandbox-status-barA bar that shows the cursor position and the language being edited.
PropTypeDescriptioncolumnnumberOne-based column of the cursor.languagestringThe language being edited, as a name or one the editor knows.linenumberOne-based line of the cursor.positionLabelstringDefault"Ln {line}, Col {column}"How the cursor's place reads. {line} and {column} are the line and
the column, written as an editor writes them, without grouping.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Items at the start of the bar.endItems after the readouts, at the end of the bar.
PartDescriptioncaretThe line and column readout.languageThe language readout.
CSS PropertyDescription--sandbox-status-bar-colorColor of the bar's text.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Toolbarhelix-sandbox-toolbarThe bar across the top of a sandbox.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)Items at the start, usually the files.endItems at the end, usually menus.
CSS PropertyDescription--sandbox-toolbar-gapSpace between items.--sandbox-toolbar-sizeThe bar's height. Defaults to the height of a large control.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionA Live PreviewThe preview frame, which runs its source inside a sandboxed document.Editing AidsA source pane that closes brackets, marks the pair beside the caret, and completes words.EventsThe events for an edit, a cursor move, two dividers, and a console log.FilesSeveral source panes as files under a row of tabs, and a preview with reload and open buttons.Highlighted SourceA source pane colored by a highlighter you bring.PreviewSource beside a preview, with a toolbar over both and a status bar under them.Preview LeadingThe preview first, stacked above the source pane, which takes the smaller share.Sized PanesPanes that open at set sizes, such as sizes a workbench restores from a previous visit.With A PanelA third pane under both, sized and collapsible, with a name for every divider.