# Heading

Source: /tuil/docs/reference/components/typography-status/heading
Locale: en

Heading component API, behavior, and executable example.





{/* Generated by tooling/docs/generate-reference.ts. */}

<PublishedStory storyId="component-acceptance" variant="Text" />

## API and events [#api-and-events]

Render styled terminal copy, hierarchy, separators, labels, and compact status signals with semantic metadata.

```tsx
export function Heading({
  level = 1,
  children,
  ...props
}: HeadingProps): ReactNode;
```

### Props, functions, and events [#props-functions-and-events]

| Member            | Type                                                                                                                                                         | Required | Description                                                                                                                                                                                                                                                                                                                                                                                             | Related types                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `level`           | `1 \| 2 \| 3 \| 4 \| undefined`                                                                                                                              | No       | The `level` member uses the `1 \| 2 \| 3 \| 4 \| undefined` contract.                                                                                                                                                                                                                                                                                                                                   | —                                                                                                                                              |
| `aria-label`      | `string \| undefined`                                                                                                                                        | No       | A label for the element for screen readers.                                                                                                                                                                                                                                                                                                                                                             | —                                                                                                                                              |
| `aria-hidden`     | `boolean \| undefined`                                                                                                                                       | No       | Hide the element from screen readers.                                                                                                                                                                                                                                                                                                                                                                   | —                                                                                                                                              |
| `color`           | `LiteralUnion<keyof import("../../../../../../../packages/ink/node_modules/chalk/source/vendor/ansi-styles/index.js").ForegroundColor, string> \| undefined` | No       | Change text color. Ink uses Chalk under the hood, so all its functionality is supported.                                                                                                                                                                                                                                                                                                                | —                                                                                                                                              |
| `backgroundColor` | `LiteralUnion<keyof import("../../../../../../../packages/ink/node_modules/chalk/source/vendor/ansi-styles/index.js").ForegroundColor, string> \| undefined` | No       | Same as `color`, but for the background.                                                                                                                                                                                                                                                                                                                                                                | —                                                                                                                                              |
| `dimColor`        | `boolean \| undefined`                                                                                                                                       | No       | Dim the color (make it less bright).                                                                                                                                                                                                                                                                                                                                                                    | —                                                                                                                                              |
| `bold`            | `boolean \| undefined`                                                                                                                                       | No       | Make the text bold.                                                                                                                                                                                                                                                                                                                                                                                     | —                                                                                                                                              |
| `italic`          | `boolean \| undefined`                                                                                                                                       | No       | Make the text italic.                                                                                                                                                                                                                                                                                                                                                                                   | —                                                                                                                                              |
| `underline`       | `boolean \| undefined`                                                                                                                                       | No       | Make the text underlined.                                                                                                                                                                                                                                                                                                                                                                               | —                                                                                                                                              |
| `strikethrough`   | `boolean \| undefined`                                                                                                                                       | No       | Make the text crossed out with a line.                                                                                                                                                                                                                                                                                                                                                                  | —                                                                                                                                              |
| `inverse`         | `boolean \| undefined`                                                                                                                                       | No       | Inverse background and foreground colors.                                                                                                                                                                                                                                                                                                                                                               | —                                                                                                                                              |
| `wrap`            | `"wrap" \| "hard" \| "truncate-end" \| "truncate" \| "truncate-middle" \| "truncate-start" \| undefined`                                                     | No       | This property tells Ink to wrap or truncate text if its width is larger than the container. If `wrap` is passed (the default), Ink will wrap text and split it into multiple lines. If `hard` is passed, Ink will fill each line to the full column width, breaking words as necessary. If `truncate-*` is passed, Ink will truncate text instead, resulting in one line of text with the rest cut off. | —                                                                                                                                              |
| `children`        | `React.ReactNode`                                                                                                                                            | No       | The `children` member uses the `React.ReactNode` contract.                                                                                                                                                                                                                                                                                                                                              | —                                                                                                                                              |
| `variant`         | `string \| undefined`                                                                                                                                        | No       | The `variant` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                           | —                                                                                                                                              |
| `size`            | `"sm" \| "md" \| "lg" \| undefined`                                                                                                                          | No       | The `size` member uses the `"sm" \| "md" \| "lg" \| undefined` contract.                                                                                                                                                                                                                                                                                                                                | —                                                                                                                                              |
| `unstyled`        | `boolean \| undefined`                                                                                                                                       | No       | The `unstyled` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `className`       | `string \| undefined`                                                                                                                                        | No       | The `className` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `layout`          | `Partial<Omit<LayoutNodeInput, "children" \| "id" \| "semantics">> \| undefined`                                                                             | No       | The `layout` member uses the `Partial<Omit<LayoutNodeInput, "children" \| "id" \| "semantics">> \| undefined` contract.                                                                                                                                                                                                                                                                                 | —                                                                                                                                              |
| `id`              | `string \| undefined`                                                                                                                                        | No       | The `id` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                                | —                                                                                                                                              |
| `testId`          | `string \| undefined`                                                                                                                                        | No       | The `testId` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                            | —                                                                                                                                              |
| `role`            | `SemanticRole \| undefined`                                                                                                                                  | No       | The `role` member uses the `SemanticRole \| undefined` contract.                                                                                                                                                                                                                                                                                                                                        | [`SemanticRole`](/tuil/docs/reference/packages/core/api/semantic-role)                                                                              |
| `label`           | `string \| undefined`                                                                                                                                        | No       | The `label` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                             | —                                                                                                                                              |
| `description`     | `string \| undefined`                                                                                                                                        | No       | The `description` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                       | —                                                                                                                                              |
| `disabled`        | `boolean \| undefined`                                                                                                                                       | No       | The `disabled` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `readOnly`        | `boolean \| undefined`                                                                                                                                       | No       | The `readOnly` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `selected`        | `boolean \| undefined`                                                                                                                                       | No       | The `selected` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `checked`         | `boolean \| undefined`                                                                                                                                       | No       | The `checked` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                          | —                                                                                                                                              |
| `expanded`        | `boolean \| undefined`                                                                                                                                       | No       | The `expanded` member uses the `boolean \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `valueText`       | `string \| undefined`                                                                                                                                        | No       | The `valueText` member uses the `string \| undefined` contract.                                                                                                                                                                                                                                                                                                                                         | —                                                                                                                                              |
| `slots`           | `Partial<SlotComponents<&#123; root: import("ink").TextProps; &#125;>> \| undefined`                                                                         | No       | The `slots` member uses the `Partial<SlotComponents<&#123; root: import("ink").TextProps; &#125;>> \| undefined` contract.                                                                                                                                                                                                                                                                              | [`SlotComponents`](/tuil/docs/reference/packages/theme/api/slot-components), [`TextProps`](/tuil/docs/reference/components/typography-status/text-props) |
| `slotProps`       | `Partial<SlotProps<&#123; root: import("ink").TextProps; &#125;, object>> \| undefined`                                                                      | No       | The `slotProps` member uses the `Partial<SlotProps<&#123; root: import("ink").TextProps; &#125;, object>> \| undefined` contract.                                                                                                                                                                                                                                                                       | [`SlotProps`](/tuil/docs/reference/packages/theme/api/slot-props), [`TextProps`](/tuil/docs/reference/components/typography-status/text-props)           |

No events are emitted.

Callback props run after the documented input is accepted. Callbacks are not cancellable unless their return type or description states otherwise.

## Interaction and capabilities [#interaction-and-capabilities]

Read-only presentation; accessibility lives in semantic role and label metadata.

The published manifest records keyboard, focus, pointer, theme, terminal, semantic, event, and dependency requirements.

## Complete import [#complete-import]

```tsx
import { Heading } from "@/components/tuil/data-display/text";
```