# Help block

> The help / success / error microcopy line that sits beneath a form control. Three tones, one primitive.

- Category: form
- Status: stable (since 0.1.0)
- Tokens: --foreground-muted, --success-foreground, --danger-foreground
- Playground: https://design.freecodecamp.org/playground#help-block
- npm dependencies: `react@>=18 <20`
- Registry dependencies: [theme](https://design.freecodecamp.org/registry/theme.md)
- Files:
  - `HelpBlock.tsx` → `src/ui/help-block/HelpBlock.tsx` (raw: https://design.freecodecamp.org/registry/help-block/HelpBlock.tsx)
  - `help-block.css` → `src/ui/help-block/help-block.css` (raw: https://design.freecodecamp.org/registry/help-block/help-block.css)

## Install (copy source)

1. Ensure the theme is installed once per project - tokens.css + base.css imported globally, fonts available. See https://design.freecodecamp.org/registry/theme.md and https://design.freecodecamp.org/registry/starter.md.
2. Copy the files below into `src/ui/help-block/` (adjust to your project layout) and import the CSS once from your global stylesheet, e.g. `@import './ui/help-block/help-block.css';`.
3. Colors, spacing and type come from tokens - tailor the component by editing the copied source; recolour by editing tokens.css, not the component CSS.

## Usage

`<HelpBlock>` is the tiny explanatory line that sits under a control.
The `variant` prop flips tone for success or error without changing
DOM shape - so `aria-describedby` wiring stays stable across states.

## Accessibility

Consumes a stable id from its parent `<FormControl>` (via context) and
joins that control's `aria-describedby` chain. When `variant="error"`,
the block adds `role="alert"` so screen readers announce the change
without a manual re-focus.

## Example

```tsx
import { HelpBlock } from './ui/help-block/HelpBlock';

<HelpBlock>We send one curriculum update per week.</HelpBlock>
<HelpBlock variant="success">Username available.</HelpBlock>
<HelpBlock variant="error">Username already in use.</HelpBlock>
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | no | `default` |  |

## Source: HelpBlock.tsx

```tsx
import React, { forwardRef } from 'react';

export type HelpBlockVariant = 'default' | 'error' | 'success';

export interface HelpBlockProps extends React.HTMLAttributes<HTMLParagraphElement> {
  variant?: HelpBlockVariant;
}

export const HelpBlock = forwardRef<HTMLParagraphElement, HelpBlockProps>(
  ({ variant = 'default', className = '', children, ...rest }, ref) => {
    const classes = [
      'form-help',
      variant !== 'default' && `form-help--${variant}`,
      className
    ]
      .filter(Boolean)
      .join(' ');
    return (
      <p ref={ref} className={classes} {...rest}>
        {children}
      </p>
    );
  }
);
HelpBlock.displayName = 'HelpBlock';
```

## Source: help-block.css

```css
.form-help {
  font-size: var(--fs-sm);
  color: var(--foreground-muted);
}
.form-help--error {
  color: var(--danger-color);
}
.form-help--success {
  color: var(--success-color);
}
```

## HTML / vanilla variant

```html
<p class="form-help">We send one curriculum update per week.</p>
<p class="form-help form-help--success">Username available.</p>
<p class="form-help form-help--error">Username already in use.</p>
```

Interactive behaviours for plain HTML come from the vanilla runtime (data-uikit-* attributes): https://design.freecodecamp.org/registry/vanilla.md - or download https://design.freecodecamp.org/cdn/uikit.global.js once and self-host it (do not hotlink).

## For coding agents

This library is distributed as copyable source, not an npm package. Start at https://design.freecodecamp.org/registry/starter.md, discover components via https://design.freecodecamp.org/llms.txt, and copy files into the consuming project. Keep token names intact; recolour by editing the copied tokens.css.