Code Editor

The Code Editor is used to edit or create code snippets.

Usage

When to use

• When providing an interactive environment for users to write and edit code.
• When syntax highlighting and code formatting are essential for the user experience.

When not to use

• As a simple display for static code snippets.
• As an embedded terminal or terminal emulator.

When to use a Code Editor vs. a Code Block

There is some overlap in the functionality of the Code Editor and the Code Block. Which to use generally comes down to the need for interactivity and user input.

Use a Code Editor:

• If editing or writing code is the primary purpose.

Use a Code Block:

• If viewing or displaying code is the primary purpose, and editing is not needed.
• If providing an example which consists of static code snippets or commands.

Header

Use a title and/or description in the header to provide additional information, instructions, or to label a Code Editor. Both of these yielded subcomponents are optional, but including them can help to provide additional context about a specific block of code.

When not to use a header

There can be an overlap between content that you may choose to include in the header as a title or description, and content that is part of the normal layout flow in a headline or paragraph. If it is necessary to elevate this content in the hierarchy of the page, we recommend including it in the normal layout flow, rather than as a title or description within the Code Editor.

How to use this component

The basic invocation doesn't require any arguments.

<Hds::CodeEditor />

Title and description

Optionally, you can pass a title and/or a description.

<Hds::CodeEditor
  @language="sql"
  @value="SELECT * FROM TABLE"
as |CE|>
  <CE.Title>
    CodeEditor title
  </CE.Title>
  <CE.Description>
    CodeEditor description
  </CE.Description>
</Hds::CodeEditor>

Title tag

The @tag argument changes the HTML element that wraps the [CE].Title content. When organizing the content on a webpage, the heading levels should reflect the structure of the page. For example, if a CodeEditor is within a subsection of the page below a heading level 2, the value should be "h3".

<div class="doc-code-block-demo-heading">
  <Hds::Text::Display @tag="h2" @size="300">Learn to write functions in JavaScript</Hds::Text::Display>
  <Hds::Text::Body @tag="p">Functions are a critical part of learning JavaScript. They are reusable chunks of code that can perform tasks like convert an object to an array.</Hds::Text::Body>
</div>
<Hds::CodeEditor
  @language="javascript"
  @value="function convertObjectToArray (obj) {
  let arr = Object
    .keys(obj)
    .map(key => {return [key, obj[key] ]})
    .flat()
    .sort()
  ;
  return arr;
}" as |CE|>
  <CE.Title @tag="h3">
    convertObjectToArray.js
  </CE.Title>
</Hds::CodeEditor>

Language

The language argument sets the syntax highlighting used. We only support the following languages: javascript, json, sql, and go. If you need additional languages contact the Design Systems Team

<Hds::CodeEditor
  @language="go"
  @value="package main
import fmt
func main() {
  fmt.Println(helloWorld)
}"
/>

Copy button

Set hasCopyButton to true to display a button for users to copy CodeEditor content to their computer clipboard.

<Hds::CodeEditor
  @language="javascript"
  @hasCopyButton={{true}}
  @value="let codeLang=`JavaScript`;
console.log(`I am ${codeLang} code`);"
/>

Component API

This component uses CodeMirror under the hood.

CodeEditor

Contextual components

[CB].Title

The CodeEditor::Title component, yielded as contextual component.

[CB].Description

The CodeEditort::Description component, yielded as contextual component.

Anatomy

Syntax highlighting

To aid in understanding how the highlighting theme is applied via Prism's tokens, we've provided a high-level, non-exhaustive list of token names and how they might be applied depending on the syntax.

Working directly with an engineering partner can reveal exactly how a snippet will render in the component and should be the first course of action when creating custom snippets.

If you have questions or need assistance creating custom examples, contact the Design Systems Team for support.

States

Focus with header content

Focus without header content

Conformance rating

When used as recommended, there should not be any WCAG conformance issues with this component.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.15.0

Added

Added the Hds::CodeEditor component.