# Heading

> Semibold titles in three levels. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/heading/

:::tip[In plain words]
A title: bigger, bolder text that names a page or a section.
:::

A semibold title. `level=1` (default), `2` or `3` pick the size, so headings stay consistent across screens.

`ui.heading` · Category: [Display](https://albakore.github.io/pyzed/library/#display) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#heading)

**Code:**

```python
pz.column([
    ui.heading("Heading 1"),
    ui.heading("Heading 2", level=2),
    ui.heading("Heading 3", level=3),
    ui.muted("Body text below the headings."),
], spacing=6)
```

## When to use

- For the title of a page, a dialog section or a settings group.
- For a small uppercase list title, use [List header](https://albakore.github.io/pyzed/library/list-header/).

## Usage

```python
import pyzed as pz
from pyzed import ui

pz.column([
    ui.heading("Heading 1"),
    ui.heading("Heading 2", level=2),
    ui.heading("Heading 3", level=3),
    ui.muted("Body text below the headings."),
], spacing=6)
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Level

```python
ui.heading("Project settings")
```

```python
ui.heading("Project settings", level=2)
```

```python
ui.heading("Project settings", level=3)
```

```python
ui.heading("Project settings", level=4)
```

### Color

```python
ui.heading("Welcome back", level=2, color="accent")
```

```python
pz.column([ui.heading("Billing", level=2), ui.muted("Invoices and payment methods.")], spacing=4)
```

## Events

Heading has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `ui.heading`

```python
heading(content, *, level=1, theme=None, **kwargs)
```

A semibold heading.

| Property | Default | Description |
| --- | --- | --- |
| `content` | *required* | Content: a `Widget`, a string or a number (converted to text). |
| `level` | `1` | 1 (26 px), 2 (20 px), 3 (16 px) or 4 (13.5 px). |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |
| `**kwargs` | — | Same as `label`. |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#heading)

## Related

- [Label](https://albakore.github.io/pyzed/library/label/): Text with a theme color, size and weight; `muted` for secondary text.
- [Card](https://albakore.github.io/pyzed/library/card/): A bordered surface with an optional title and actions.