Code Block

Overview

Code Block displays multi-line code examples, terminal commands, configuration snippets, framework examples, and copyable technical content in a readable, token-styled surface. It keeps technical examples readable across Byteion documentation, installation guides, Tailwind config examples, Laravel starter-kit guides, React and Vue examples, API setup screens, and developer settings pages. Code Block is a Typography component available in both @byteion/react and @byteion/vue that renders a semantic <pre><code> block with token-based monospace styling and horizontal overflow support.

Why this exists

Without a shared Code Block pattern, documentation and product screens use inconsistent monospace surfaces — one page uses bg-gray-900 text-gray-100, another uses a themed card surface, a third uses inline text with no formatting at all. Syntax highlighting is applied ad-hoc or missing entirely, contrast fails in dark mode, long lines overflow awkwardly without horizontal scroll, and copy behavior is unreliable or absent. Code Block unifies all multi-line technical content into a single, accessible, token-based system with consistent background, border, font-family, text color, overflow handling, and optional copy support that adapts to light mode, dark mode, and branded themes without manual overrides.

Mental model

• Use Code Block when users need to read, copy, compare, or run code — commands they paste into a terminal, configurations they add to a file, API responses they inspect, or framework examples they adapt.
• Use Inline Code when the code fragment is part of a sentence — a package name, a class, a prop, a variable name. If it fits naturally inside a paragraph, it is Inline Code, not a Code Block.
• A Code Block preserves formatting, indentation, spacing, and line breaks — the <pre> element guarantees whitespace is rendered exactly as written. Never collapse or trim whitespace inside a Code Block.
• Code Block is read-copy oriented, not scan-and-continue — the reader stops, reads the snippet, copies if needed, then continues. This is different from Inline Code where the reader keeps reading through the sentence.
• If the content is shorter than one line, it might belong in Inline Code — use Code Block only when vertical space and formatting add value.

Code Block vs Inline Code vs Text vs KBD

When to use

• Installation commands — npm install @byteion/core @byteion/react
• Tailwind config examples — tailwind.config.js exports
• CSS variable theme overrides — variables.css snippets
• HTML component snippets — complete usage examples with tags
• React component snippets — imports, props, composition
• Vue component snippets — template, script setup, props
• API request and response examples — JSON, headers, status codes
• Terminal output — build logs, test results, error messages
• Environment and config examples — .env, tsconfig.json, vite.config.ts
• Any multi-line code users may need to copy, compare, or run

When not to use

• Do not use Code Block for short inline package names or classes — those belong in Inline Code inside a sentence.
• Do not use Code Block for normal prose — use Text or Paragraph for paragraphs, descriptions, and labels.
• Do not use Code Block for decorative monospace styling — if text just needs monospace for stylistic reasons, use Typography with variant="code" or apply font-mono directly.
• Do not put very wide snippets in narrow cards without horizontal scroll — always enable overflow-x-auto so content is accessible.
• Do not use Code Block when a table or step list communicates the information better — comparison tables and ordered instructions are not code.
• Do not show fake or outdated commands — every snippet must reflect real package APIs and CLI interfaces.
• Do not use Code Block as an Alert, Card, Badge, or Callout replacement — those components serve different visual purposes and have their own accessibility semantics.

Basic example

A minimal Code Block for an installation command. The <pre> preserves whitespace and the <code> applies monospace font.

npm install @byteion/core @byteion/react

Code block patterns

Code Block handles several common technical content patterns. The structure is identical — <pre><code> — but the content type, label, and surface suggestion varies.

Installation command

npm install @byteion/core @byteion/vue

Tailwind config

// tailwind.config.js
module.exports = {
  content: [
    './node_modules/@byteion/core/**/*.js',
    './node_modules/@byteion/react/**/*.js',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

CSS variable theme override

:root {
  --primary: 222 47% 11%;
  --primary-foreground: 210 40% 98%;
  --radius: 0.75rem;
}

.dark {
  --primary: 210 40% 98%;
  --primary-foreground: 222 47% 11%;
}

HTML snippet

<button class="inline-flex items-center justify-center rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90">
  Submit
</button>

React snippet

import { Button } from '@byteion/react';

export default function SaveButton() {
  return (
    <Button tone="primary" onClick={() => console.log('saved')}>
      Save
    </Button>
  );
}

Vue snippet

<script setup lang="ts">
import { Button } from '@byteion/vue';
</script>

<template>
  <Button tone="primary" @click="handleSave">
    Save
  </Button>
</template>

Terminal output

$ npm install @byteion/core @byteion/react
+ @byteion/core@0.2.0-beta.1
+ @byteion/react@0.2.0-beta.1
added 2 packages in 3.2s

API request/response

GET /api/users HTTP/1.1
Host: api.byteion.io
Authorization: Bearer <token>

{
  "users": [
    { "id": 1, "name": "Ada Lovelace", "role": "Engineer" },
    { "id": 2, "name": "Linus Torvalds", "role": "Maintainer" }
  ]
}

Copy and overflow behavior

Code Block supports optional copy and overflow handling depending on the context:

• Copy button: When a copy action is present, the button should be keyboard-focusable and have aria-label="Copy code". A brief "Copied" confirmation is helpful.
• Horizontal scroll: Code Block uses overflow-x-auto to handle long lines. The scroll container must be keyboard-accessible — users should be able to tab into the block and scroll with arrow keys.
• Whitespace preservation: The <pre> element ensures all whitespace, indentation, and line breaks are preserved exactly. Do not add white-space: normal or trim trailing spaces.

Variants and composition

Code Block itself renders a single surface, but it is commonly composed with other elements to provide context:

• Terminal command: A single-line or multi-line command prefixed with $ for shell commands.
• Configuration snippet: A named file block with a filename label (e.g., tailwind.config.js) rendered above or inside the block.
• HTML example: A complete or partial HTML snippet with tags, attributes, and classes.
• React example: A component example with imports, props, JSX, and event handlers.
• Vue example: A component example with template, script setup, and style sections.
• Scrollable long snippet: A block wider than its container with horizontal scroll enabled.
• Copyable snippet: A block paired with a copy trigger for commands users should paste.
• Output or log block: Terminal output, build logs, test results, or error messages.

Anatomy

Code Block is a single-element composition. Optional companions add context or interaction.

1. Container surface — bg-muted, border border-border, rounded-xl, p-4
2. Pre element — preserves whitespace, enables overflow-x-auto
3. Code element — applies font-mono, text-sm, leading-relaxed
4. Filename label (optional) — text-xs text-muted-foreground above the block
5. Copy button (optional) — aria-label="Copy code", keyboard focusable
6. Language tag (optional) — bash, js, tsx, html, css, etc.

Usage guidelines

• Use real package names and versions — every command should work if a reader copies and pastes it.
• Keep examples short enough to scan — a block should show the relevant lines. Use comments or ellipsis to indicate omitted sections.
• Add a filename or language label when the context is not immediately obvious from surrounding text.
• Test every command in a fresh environment before publishing documentation.
• Use token-based colors — bg-muted for the surface, text-foreground for code text. Do not hardcode bg-gray-900 or text-white.
• Avoid extremely long lines — break long commands or URL strings at logical points with a trailing backslash or pipe.

Do and Don't

Accessibility

• Semantic markup: Code Block uses <pre> and <code> elements, which convey their meaning to assistive technology. Do not replace them with <div> or styled <p>.
• No keyboard behavior by itself: A plain Code Block has no interactive elements. Readers can navigate the text with standard cursor keys.
• Copy button: If a copy button is present, it must be keyboard-focusable (tabindex="0" or a native <button>) and have an accessible label such as aria-label="Copy code".
• Horizontal scroll: If the block is wider than its container, keyboard and touch users must be able to access the full width. Use overflow-x-auto on the <pre> so scroll is available via arrow keys or swipe.
• Syntax contrast: Syntax highlighting must maintain readable contrast (WCAG AA 4.5:1) in light mode, dark mode, and any branded theme. Do not use low-contrast colors like #999 on #f5f5f5.
• Do not rely on color alone: If lines are highlighted, added, removed, or otherwise differentiated, use a non-color indicator (icon, label, or pattern) in addition to color.
• Screen reader announcements: Copy buttons should announce "Copied" or be paired with a visible change after activation.

Customization

Code Block should be customized through design tokens, not one-off overrides:

• Monospace font family — controlled by the font-mono utility
• Code surface background — bg-muted for a subtle surface; optionally bg-card for a contained card look
• Text color — text-foreground for readable code; text-muted-foreground for terminal output
• Border color — border-border for visible delimitation
• Radius — rounded-xl for a standard container radius
• Spacing — p-4 for comfortable padding
• Syntax highlight colors — should be defined in your theme variables, not hardcoded per block
• Focus ring for copy buttons — use focus-visible:ring-2 focus-visible:ring-primary if a copy action is present

HTML example

<div class="space-y-6">
  <!-- Filename label -->
  <p class="text-xs text-muted-foreground font-mono">terminal</p>

  <!-- Code Block -->
  <pre class="p-4 bg-muted rounded-xl overflow-x-auto text-sm font-mono leading-relaxed border border-border">
    <code>npm install @byteion/core @byteion/react</code>
  </pre>

  <!-- Another block for config -->
  <p class="text-xs text-muted-foreground font-mono">tailwind.config.js</p>

  <pre class="p-4 bg-muted rounded-xl overflow-x-auto text-sm font-mono leading-relaxed border border-border">
    <code>module.exports = {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  theme: { extend: {} },
  plugins: [],
};</code>
  </pre>
</div>

React example

export default function InstallBlock() {
  return (
    <div className="space-y-2">
      <p className="text-xs text-muted-foreground font-mono">npm</p>
      <pre className="p-4 bg-muted rounded-xl overflow-x-auto text-sm font-mono leading-relaxed border border-border">
        <code>npm install @byteion/core @byteion/vue</code>
      </pre>
    </div>
  );
}

Vue example

<script setup lang="ts">
// No additional logic needed for static code display
</script>

<template>
  <div class="space-y-2">
    <p class="text-xs text-muted-foreground font-mono">npm</p>
    <pre class="p-4 bg-muted rounded-xl overflow-x-auto text-sm font-mono leading-relaxed border border-border">
      <code>npm install @byteion/core @byteion/vue</code>
    </pre>
  </div>
</template>

API Reference

Code Block is rendered as <pre><code> in HTML. The component accepts no special props — all styling is applied through token-based utility classes. Below are the recommended classes for a consistent Code Block:

Developer tips

• Use real package names and commands. Every Code Block should reflect actual package APIs. Prefer @byteion/react over fictional examples.
• Keep examples short enough to scan. A block should show the essential lines. Use comments like // ... other config for omitted sections.
• Use Code Block when copy/paste matters. If the reader will copy the content, ensure it is in a Code Block, not Inline Code.
• Add filenames or language labels when the context is not immediately clear from surrounding text — especially in multi-file examples.
• Test horizontal scrolling on mobile. Long lines should not break the layout or hide content at small viewport sizes.
• Keep docs examples aligned with actual package APIs. When a component prop changes, update every code block that references it.
• Use bg-muted for a subtle code surface and reserve bg-card for when the block sits inside a larger card layout.

Common mistakes

• Using Inline Code for long commands — multi-line or lengthy commands belong in a Code Block with horizontal scroll.
• Using Code Block for normal prose — paragraphs, labels, and descriptions should use Text or Paragraph, not a monospace block.
• Outdated install commands — showing npm install byteion instead of the correct npm install @byteion/core confuses readers.
• Missing horizontal scroll for long lines — code overflow without scroll clips content and makes it inaccessible.
• Syntax colors with poor contrast — color choices like #888 on a light background fail WCAG AA.
• Fake examples that do not run — every snippet should be tested or at minimum reflect real, working API patterns.
• Missing accessible label on copy buttons — a bare icon button without aria-label is invisible to screen readers.
• Hardcoding dark-only surfaces — bg-gray-900 text-white looks correct in dark mode but broken in light mode.

Production usage tips

• Test dark mode contrast — verify that code text, line numbers, and syntax highlights all meet WCAG AA against the code surface.
• Test mobile overflow — ensure all blocks are scrollable on small viewports and that the scroll container is reachable by keyboard.
• Verify all commands still work — package versions and CLI flags change. Re-test commands every release cycle.
• Verify copy buttons with keyboard and screen readers — Tab to the button, press Enter, confirm "Copied" is announced.
• Keep React and Vue examples aligned with package exports — if @byteion/react renames or removes an export, update every related Code Block.
• Avoid exposing secrets, API keys, or real credentials — use placeholder tokens like <token> or YOUR_API_KEY.
• Group related blocks — when showing multiple files (e.g., component + config + route), consider using Tabs to switch between them.

Premium examples

Advanced patterns available in Pro extend Code Block with toolbar interactions, diffs, tabbed examples, and contextual output blocks.

• Copyable code block with toolbar — sticky toolbar at the top of the block with a copy button, language badge, and line count.
• Filename and language label — a small label bar above the block showing the file path and language for context.
• Highlighted lines — specific lines are visually emphasized with a tinted left border or background to draw attention.
• Diff view — side-by-side or inline diff with green additions and red deletions, labeled with +/- gutter markers.
• Terminal output block — dark-themed block with a terminal-style header bar (~ $ prefix) showing command output.
• Framework tabbed examples — a Tabs container with individual Code Blocks for HTML, React, and Vue — users can switch by framework.
• API request/response example block — a two-block pair showing the HTTP request (method, URL, headers) and the JSON response body with syntax highlighting.

Related components

• Inline Code — short code fragments inside prose: package names, classes, props, CSS variables
• Text — body copy, helper text, captions, and inline semantic text
• Paragraph — readable body copy for descriptions, documentation, and prose
• Tabs — switch between framework-specific Code Block examples
• Button — trigger actions, including copy-to-clipboard from a Code Block
• Card — surface container for grouping a Code Block with related content
• Alert — contextual messages that may accompany or explain a Code Block

API Reference

Related components

Pair this component with adjacent Byteion primitives from the same workflow: form controls for data entry, feedback components for validation, and layout primitives for spacing.

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX