Skip to contentSkip to navigationSkip to topbar
Figma
Star

Editable Code Block

Version 2.1.0GithubStorybook

An Editable Code Block is a text field that allows users to enter formatted code.

<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Typescript Example</EditableCodeBlockHeader>
  <EditableCodeBlock
    height="45vh"
    defaultLanguage="typescript"
    defaultValue={TypeScriptExample}
  />
</EditableCodeBlockWrapper>

Guidelines

Guidelines page anchor

About Editable Code Block

About Editable Code Block page anchor

Editable Code Block allows basic text input features for code-editing experiences on the web. To help users differentiate this from a static Code Block, Editable Code Block enables line numbers, code folding, and indentation guides by default.

This component is built on top of the Paste Code Editor library, which wraps the Monaco Editor(link takes you to an external page) used by Visual Studio Code. If you’re looking for more functionality than what’s provided through Editable Code Block, use the Code Editor library instead.

This component uses the Night Owl theme(link takes you to an external page), an accessible theme by Sarah Drasner for people with colorblindness and low vision situations.

Because Editable Code Block takes text input, it follows similar labeling accessibility guidelines as other form elements:

  • Include a label on all Editable Code Blocks. Use one of these ways to label an Editable Code Block:
    • Editable Code Block Header (preferred). Use the correct heading level in Editable Code Block Header.
    • Visible label (for example, a page heading) that's associated to the input with aria-labelledby
    • Visible label with Label
    • Label directly using aria-label
  • Each label must use the htmlFor prop that equals the id of the associated Input.

Since Editable Code Block takes up more vertical space than typical form elements, any help or error content should appear before the component by using an introductory Paragraph or Error Callout.

Keyboard interaction

Keyboard interaction page anchor

Excerpts from the Monaco accessibility guide(link takes you to an external page):

ActionKeyboard shortcutDescription
Open the Command PaletteF1 or Alt+F1Provides “an exhaustive list of commands in the Command Palette…, so you can use the editor without using the mouse.”
Insert Tab characterTab“Inserts the Tab character (or spaces depending on the indentation setting) and does not navigate to the next focusable element on the page.”
Toggle tab trappingCtrl+Shift+M or Ctrl+M“Subsequent Tab keys will move focus out of the editor.”
Go to Next Error or WarningF8
Go to Previous Error or WarningShift+F8
Show accessibility helpOption+F1, Alt+F1, or Ctrl+F1Shows a “dialog…to find out the current position in the editor and to check the state of various accessibility options. The editor can be dynamically optimized for screen reader software from this dialog.”

The default Editable Code Block includes:

  • An Editable Code Block Header: Contains a logical label at the correct heading level that describes what users need to put in the code block and/or the language used.
  • Line numbers: Helps users identify errors and cross-reference with existing code. Use line numbers when the expected input is longer than 5 lines.
  • Indentation guides and code folding: Helps users read long blocks of code and troubleshoot errors.
<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Typescript Example</EditableCodeBlockHeader>
  <EditableCodeBlock
    height="45vh"
    defaultLanguage="typescript"
    defaultValue={TypeScriptExample}
  />
</EditableCodeBlockWrapper>

Simple Editable Code Block

Simple Editable Code Block page anchor

Remove line numbers, indentation guides, and code folding from Editable Code Block only when:

  • Your page layout makes it visually clear to the user that the code block is editable, and
  • The expected code input is simple, like a short snippet of JSON.
<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Simple Editable Code Block</EditableCodeBlockHeader>
  <EditableCodeBlock
    height="45vh"
    defaultLanguage="typescript"
    lineNumbers="off"
    folding={false}
    indentationGuide={false}
    defaultValue={TypeScriptExample}
  />
</EditableCodeBlockWrapper>

Editable Code Block with minimap

Editable Code Block with minimap page anchor

For large files, use a minimap to help users navigate the code block.

<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Minimap example</EditableCodeBlockHeader>
  <EditableCodeBlock height="45vh" defaultLanguage="typescript" showMinimap defaultValue={TypeScriptExample} />
</EditableCodeBlockWrapper>

Monaco Editor will detect and show syntax errors out of the box.

<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Syntax error example</EditableCodeBlockHeader>
  <EditableCodeBlock
    height="45vh"
    defaultLanguage="typescript"
    defaultValue={CodeStringWithSyntaxError}
  />
</EditableCodeBlockWrapper>

Custom line-specific errors

Custom line-specific errors page anchor

Show line-specific errors to help users pinpoint what line of code they need to fix.

For additional guidance on how to compose error messages, refer to the error state pattern.

<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>Custom inline error example (try hovering it)</EditableCodeBlockHeader>
  <EditableCodeBlock
    height="45vh"
    onChange={(value) => console.log(value)}
    inlineErrorRange={{
      startLineNumber: 3,
      endLineNumber: 3,
      startColumn: 7,
      endColumn: 13,
    }}
    inlineErrorIsWholeLine={false}
    inlineErrorHoverMessage={{value: '"id" can only be a string type.'}}
    defaultLanguage="typescript"
    defaultValue={TypeScriptExample}
  />
</EditableCodeBlockWrapper>

If there’s an error that can’t be traced to specific line numbers, use a Callout.

For additional guidance on how to compose error messages, refer to the error state pattern.

<Stack orientation="vertical" spacing="space40">
  <Callout variant="error">
    <CalloutHeading as="h3">401 Unauthorized Request</CalloutHeading>
    <CalloutText>Please provide a valid API key.</CalloutText>
  </Callout>
  <EditableCodeBlockWrapper>
    <EditableCodeBlockHeader>Generic error example</EditableCodeBlockHeader>
    <EditableCodeBlock height="45vh" defaultLanguage="typescript" defaultValue="const API_KEY = null;" />
  </EditableCodeBlockWrapper>
</Stack>

Only if the user doesn't have permission to edit the code, use the readOnly prop to make the Editable Code Block read-only. In most cases, use the Code Block component instead to show static code.

<EditableCodeBlockWrapper>
  <EditableCodeBlockHeader>ReadOnly Example</EditableCodeBlockHeader>
  <EditableCodeBlock height="45vh" readOnly defaultLanguage="typescript" defaultValue={TypeScriptExample} />
</EditableCodeBlockWrapper>

Ensure the surrounding page contains any information required to successfully use the editor. For example, include the expected language or any input constraints.

Supporting content can be placed before or next to an Editable Code Block by using an introductory Paragraph, Callout, or Card.

When to use Editable Code Block

When to use Editable Code Block page anchor
Do

Use Editable Code Block for a multi-line code input.

Don't

Don’t use Textarea for a multi-line code input. The monospace formatting and line numbers of Editable Code Block can help a user check that their code is entered correctly.

Do

Pair Editable Code Block with a visible label. This can be the Editable Code Block Header, an associated page Heading, or Label.

Don't

Don’t use an Editable Code Block without clear, contextual guidance or links to documentation. Provide immediate feedback or code previews when possible.