# Headline

> A section's big two-tone headline: the claim in full ink, then the rest in gray.

- Name: `headline`
- Status: beta
- Categories: heading, section, marketing
- Files: the install writes `headline.tsx`, and any part files named `headline-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Other registry items: `@arbokui/dither`. The install adds them.
- Gallery: https://arbokui.com/website/headline
- Registry item: https://arbokui.com/r/headline.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the website component. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @arbokui/headline
   ```

## Use it for

- Above each section of a landing page, like a bento grid, pricing, or a FAQ.
- Put the claim in \`title\` and the payoff in \`muted\`, so the eye reads the claim first.
- Keep it to one sentence that fits on two lines at 1280px.
- Use \`as="h1"\` only when it is the top of the page and there is no Hero.
- Pass texture="dither" for a short, loud title, like two or three words over a dark section.
- The headline is set in the theme's \`font-headline\`. Load Geist Serif as \`--font-geist-serif\`, like \`geist/font/serif/variable\` in Next.js, or it falls back to the system serif.

## Avoid it for

- The top of a page with a product preview. Use Hero, which has the bigger size.
- Headings inside an app's own screens. Use Section Header.
- A long paragraph in \`description\`. Keep it to two lines, and put the rest in the section.

## Props

- `title`: `ReactNode`. The words that land first, in full ink.
- `muted`: `ReactNode`. The words that follow in gray, on the same line.
- `description`: `ReactNode`. A line or two under the headline.
- `align`: `"center" | "start"`. Default `"center"`. Where the text sits.
- `as`: `"h1" | "h2" | "h3"`. Default `"h2"`. The heading level. A page has one h1, usually the hero's.
- `size`: `"md" | "lg"`. Default `"md"`. "lg" sets the title a step bigger, from 36 to 48px, for a page's own title over its section headlines.
- `texture`: `"flat" | "dither"`. Default `"flat"`. "dither" draws the title as dots in the first chart color, with a glow on dark pages. Only this prop turns it on, never a Dither around it.
- `className`: `string`. Extra classes on the root, which holds the container query.

## Accessibility

- It renders a real heading, h2 by default. Pick \`as\` so the page's heading levels go in order.
- The gray part is inside the same heading, so screen readers hear one sentence.
- The gray is muted-foreground, which the theme checks at 4.5:1 on the page.
- A dithered title keeps its text, so screen readers hear the same sentence. Its dots are the first chart color, which the theme checks at 3:1 on the page, and only a big title should use it.

## Examples

### Above a section

```tsx
<Headline title="Start with your people," muted="then organize the week." />
```

### A page's own title, a step bigger than its section headlines

```tsx
<Headline as="h1" size="lg" align="start" title="The blog." muted="What we ship, and how we work." />
```

### Left-aligned, with a line under it

```tsx
<Headline
  align="start"
  title="Questions people ask."
  description="Can't find yours? Email us and we answer within a day."
/>
```