Editable Code Block

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

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 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, 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.

Excerpts from the Monaco accessibility guide:

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>

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>

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>

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.