Usage

1import { CodeBlock } from '@raystack/apsara'

Component Structure

The CodeBlock component uses a composite pattern, providing modular sub-components for flexible code display:

• CodeBlock - Root container that manages state and context
• CodeBlock.Header - Optional header section for labels and controls
• CodeBlock.Content - Main content area containing code blocks
• CodeBlock.Label - Text label displayed in the header
• CodeBlock.Code - Individual code block with syntax highlighting
• CodeBlock.CopyButton - Copy functionality (floating or inline variants)
• CodeBlock.LanguageSelect - Language selection dropdown container
• CodeBlock.LanguageSelectTrigger - Button to open language selection
• CodeBlock.LanguageSelectContent - Language select content container
• CodeBlock.LanguageSelectItem - Individual language option
• CodeBlock.CollapseTrigger - Button to expand/collapse long code blocks

API Reference

CodeBlock Props

CodeBlock.Header Props

CodeBlock.Content Props

CodeBlock.Label Props

CodeBlock.LanguageSelect Props

CodeBlock.LanguageSelectTrigger Props

CodeBlock.CopyButton Props

CodeBlock.Code Props

CodeBlock.CollapseTrigger Props

Examples

Basic Usage

The most basic usage using CodeBlock with CodeBlock.Code for displaying code content with a floating copy button.

1<CodeBlock>
2  <CodeBlock.Content>
3    <CodeBlock.Code language="jsx">
4      {`function add(a, b) {
5  return a + b;
6}`}
7    </CodeBlock.Code>
8  </CodeBlock.Content>
9</CodeBlock>

With Header

Add a structured header with labels and controls using CodeBlock.Header, CodeBlock.Label, and CodeBlock.CopyButton for better organization and user experience.

1<CodeBlock>
2  <CodeBlock.Header>
3    <CodeBlock.Label>Header Example</CodeBlock.Label>
4    <CodeBlock.CopyButton />
5  </CodeBlock.Header>
6  <CodeBlock.Content>
7    <CodeBlock.Code language="jsx">
8      {`function add(a, b) {
9  return a + b;
10}`}
11    </CodeBlock.Code>
12  </CodeBlock.Content>
13</CodeBlock>

Language Switcher

Support multiple programming languages by including multiple CodeBlock.Code components with different language values. Use CodeBlock.LanguageSelect to provide a dropdown for users to switch between languages. The component automatically displays the code block matching the selected language value, which can be controlled programmatically using the value and onValueChange props.

1<CodeBlock>
2  <CodeBlock.Header>
3    <CodeBlock.Label>Code</CodeBlock.Label>
4    <CodeBlock.LanguageSelect>
5      <CodeBlock.LanguageSelectTrigger />
6      <CodeBlock.LanguageSelectContent>
7        <CodeBlock.LanguageSelectItem value="jsx">
8          JSX
9        </CodeBlock.LanguageSelectItem>
10        <CodeBlock.LanguageSelectItem value="tsx">
11          TSX
12        </CodeBlock.LanguageSelectItem>
13      </CodeBlock.LanguageSelectContent>
14    </CodeBlock.LanguageSelect>
15  </CodeBlock.Header>
16  <CodeBlock.Content>
17    <CodeBlock.Code language="tsx">{`function add(a, b) {
18  return a + b;
19}`}</CodeBlock.Code>
20    <CodeBlock.Code language="jsx">{`function add(a: number, b: number): number {
21  return a + b;
22}`}</CodeBlock.Code>
23  </CodeBlock.Content>
24</CodeBlock>

No Line Numbers

Hide line numbers by setting the hideLineNumbers prop to true on the root CodeBlock component for a cleaner appearance.

1<CodeBlock hideLineNumbers>
2  <CodeBlock.Content>
3    <CodeBlock.Code language="jsx">
4      {`function add(a, b) {
5  return a + b;
6}`}
7    </CodeBlock.Code>
8  </CodeBlock.Content>
9</CodeBlock>

Collapsible Code

For long code snippets, use the maxLines prop to create collapsible code blocks. When the code exceeds the specified number of lines, a CodeBlock.CollapseTrigger button appears, allowing users to expand or collapse the content.

1<CodeBlock maxLines={10}>
2  <CodeBlock.Content>
3    <CodeBlock.Code language="jsx">
4      {`<Dialog>
5  <Dialog.Trigger asChild>
6    <Button>Basic Dialog</Button>
7  </Dialog.Trigger>
8  <Dialog.Content
9    width={300}
10    ariaLabel="Basic Dialog"
11    ariaDescription="A simple dialog example"
12  >
13    <Dialog.Header>
14      <Dialog.Title>A simple dialog example</Dialog.Title>
15      <Dialog.CloseButton />
16    </Dialog.Header>
17    <Dialog.Body>
18      <Dialog.Description>
19        This is a basic dialog with title and description.
20      </Dialog.Description>
21    </Dialog.Body>
22    <Dialog.Footer>
23      <Button>OK</Button>
24      <Dialog.Close asChild>
25        <Button color="neutral">Cancel</Button>
26      </Dialog.Close>

Copy Button Variants

The CodeBlock.CopyButton component offers two placement options:

• Floating: Overlays on the code block using variant="floating"
• Inline: Positioned within the header alongside other controls

1<CodeBlock>
2  <CodeBlock.Content>
3    <CodeBlock.Code language="jsx">
4      {`function add(a, b) {
5  return a + b;
6}`}
7    </CodeBlock.Code>
8    <CodeBlock.CopyButton variant="floating" />
9  </CodeBlock.Content>
10</CodeBlock>

Accessibility

The CodeBlock component is built with accessibility in mind:

• Keyboard Navigation: All interactive elements support keyboard navigation
• Screen Reader Support: Proper ARIA labels and semantic roles for screen readers
• Focus Management: Clear visual focus indicators for keyboard users
• Color Contrast: Meets WCAG guidelines for sufficient text contrast ratios