Code Editor

The Code Editor is used to edit formatted code. It supports syntax highlighting, auto-closing brackets and quotes, and a custom yielded section for additional functions.

Usage

When to use

• When a user needs to create code from scratch.
• When code requires modification from an existing source.

When not to use

• As a read-only reference for code, use the Code Block instead.

Standalone

The isStandalone property increases the portability of the Code Editor to ensure that it can be used in different contexts. For example, a common use case of the Code Editor is in a “standalone” context, which can be part of a form or multi-step process and is generally a part of the normal layout flow.

Sometimes it may be necessary to use the Code Editor in a more dense layout or nested within another component.

Header

An optional header is available within the Code Editor. It consists of three sections that can be toggled as needed:

• the text content that includes the title and description
• an actions container for secondary actions
• a custom content section for adding primary actions

When to use a title and description

A title and description provides additional contextual information for the Code Editor. An accessible name is mandatory and can either be provided by the title or by an external text element.

Secondary actions

The secondary actions section supports two optional buttons: the Copy Button, and a “full screen” button. The Copy Button copies the content of the Code Editor to the clipboard, while the full screen button toggles the size of the Code Editor from inline view to full screen.

Custom actions

This space is intended for custom primary actions. Primary actions are those which are necessary for the user to complete their work.

Here is an example of a custom action to reveal secrets.

External elements

Some elements or functions outside the Code Editor may affect the content within the Code Editor. In this case, we recommend turning off the header to visually couple the editor with the nearby controlling elements.

Active line highlighting

When a user edits a line of code, a highlight will display to show their location within the Code Editor.

When a user selects a piece of code, the active line highlight no longer displays although the line number of the last line of the selection will be highlighted.

Bracket highlighting

The Code Editor automatically closes open quotes and brackets as the user types. When the user’s cursor is next to a bracket, the bracket will highlight to show the start and end of the pair.

Language

Language determines how syntax highlighting is applied and formatted within the editor but is handled a bit differently between the Ember and Figma components.

The Ember component uses CodeMirror to handle syntax highlighting and comes with a pre-defined set of languages.

In Figma we provide a handful of example languages intended as visual examples. Syntax highlighting in Figma is a non-trivial process and requires the manual application of color styles to each “type” of code. You are still able to add a custom code snippet to the Figma component by typing/pasting into the text layer, but syntax highlighting will not be automatically applied.

Applying syntax highlighting

If you wish to create custom examples using the Code Editor, we publish all of the relevant syntax highlighting variables in the HDS Components v2.0 library. However, due to the number of languages supported by the component, the color variables use a generic naming schema (e.g., cyan, red, purple) to remain as agnostic as possible when being applied to different languages. For more details around syntax, visit the specifications.

How to use this component

The code editor is provided as both a CodeEditor component and as an hds-code-editor Ember modifier. To use this component, you must either include the yielded Title component, provide an @ariaLabel, or specify an @ariaLabelledBy.

<Hds::CodeEditor @ariaLabel="Basic usage" />

Ember modifier

An Ember modifier is available if your use case does not require a visible title, description, or any additional interactivity beyond editing code.

Modifier used on a div

<div {{hds-code-editor ariaLabel="Ember modifier usage"}} />

Title and description

Optionally, you can pass a title and/or a description using the [CE].Title and [CE].Description components yielded by the Code Editor component.

<Hds::CodeEditor @value="Hello, world" 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 Code Editor is within a subsection of the page below a heading level 2, the value should be "h3".

<div class="doc-code-editor-demo-heading">
  <Hds::Text::Display @tag="h2" @size="300">Learn to write functions in Go</Hds::Text::Display>
  <Hds::Text::Body @tag="p">Functions are a critical part of learning Go. They are reusable chunks of code that can perform tasks like convert an object to an array.</Hds::Text::Body>
</div>
<Hds::CodeEditor
  @language="go"
  @value={{this.goCode}}
  as |CE|>
  <CE.Title @tag="h3">
    convertObjectToArray.js
  </CE.Title>
</Hds::CodeEditor>

Language

The language argument sets the syntax highlighting used. We support the following languages: ruby, sentinel, shell, go, hcl, json, sql, and yaml. If you need additional languages, contact the Design Systems Team.

<Hds::CodeEditor
  @ariaLabel="language"
  @language="go"
  @value={{this.goCode}}
/>

Copy button

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

<Hds::CodeEditor @ariaLabel="copy button" @hasCopyButton={{true}} @value={{this.loremIpsum}} />

Full screen mode

Set hasFullScreenButton to true to display a button for users to toggle between a full screen view and normal placement within the page.

<Hds::CodeEditor @ariaLabel="full screen mode" @hasFullScreenButton={{true}} @value={{this.loremIpsum}} />

Component API

This component uses CodeMirror 6 under the hood.

CodeEditor

Contextual components

[CE].Title

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

[CE].Description

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

[CE].Generic

A generic container, yielded as contextual component.

Anatomy

Syntax highlighting

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

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.