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 creates code from scratch, or requires modification from an existing source.

When not to use

• As a read-only reference for page content, 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, 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. In this circumstance, setting isStandalone to false ensures that the Code Editor fits alongside other elements, in a split view, or as part of a larger layout mechanism.

Header

The header is optionally available within the Code Editor. It consists of three sections that each can be toggled as needed: The text content that’s inclusive of the title and description, an actions container for secondary actions, and a custom yielded section of primary actions.

When to use a title and description

A title and description help provide additional contextual information for the Code Editor. Keep in mind that 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 is for two individually optional buttons: CopyButton and FullScreenButton. The CopyButton copies the content of the CodeEditor to clipboard (more details can be found in the CopyButton guidelines), while the FullScreenButton maximizes and minimizes the Code Editor view from inline to full screen (and back again). These actions are considered supporting functions that are less vital to the user’s work but are useful from time to time.

Custom yielded elements

This space is reserved for primary custom yielded elements. Primary elements are defined as useful or even necessary for the user to do their work.

Currently, the Code Editor has very limited support for dark mode styles (only exposed styles are for buttons) and requires independent maintenance until a dark mode theme is released.

External elements

There may be elements or functions outside the Code Editor component that affect the content within the Code Editor. In circumstances like this, turning off the header and only keeping the code content visible helps unify the editor with other elements on the page.

Active line highlighting

When a user is editing code on a single line, a highlight will be present to emphasize their location in the Code Editor.

When a user selects code (even if it’s within a single line), the active line highlight will no longer be present, however, the line number on the left will remain highlighted. The highlighted number will be present wherever the cursor is located.

Bracket highlighting

The Code Editor will automatically close quotes and brackets as the user writes their code. When the user’s cursor is next to a bracket, that 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 that are intended to be representative of the end result in production. Syntax highlighting in Figma is a non-trivial process and requires the manual application of color styles to each "type" of code. Despite this, creating a custom code snippet with the Code Editor is supported 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 basic invocation doesn't require any arguments.

<Hds::CodeEditor />

Title and description

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

<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 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 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 only support the following languages: json, sql, go, hcl. If you need additional languages contact the Design Systems Team

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

Copy button

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

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

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 CodeEditor::Description component, yielded as contextual component.

Anatomy

Syntax highlighting

To aid in understanding how the highlighting theme is applied via CodeMiror'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

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.