# Table of Content

> Part of mCSS (mcss.dev). Rendered page: https://mcss.dev/components/toc

<div class="prose">
  The `.toc` component is an "Astro only" client-side rendered component. It creates a table of content from the headings on the page it's on:

</div>

<Toc id="example1" class="mb-sm2" />

<div class="prose">

By default, the TOC includes `H2`s and `H3`s (customizable via props) that have an ` id` attribute and links to them.

It's possible to add multiple TOC on the same page, but this will duplicate Javascript and it's not recommended. If you do need to include more than one TOC, you'll need to add a unique `id` to each instance of the component.

<div class="docs_oversizedTable">

| File                | Description | Source      |
| ------------------- | ----------- | ----------- |
| `component.toc.css` | All TOC styles (`.toc`) | [Github][1] |

</div>

[1]: https://github.com/minimaldesign/mCSS/blob/main/src/styles/framework/component.toc.css

</div>

## HTML

This component's main functionality is to create a table of content via JavaScript. It just renders a nested `ul` and it's most useful as an Astro component.

### Custom properties

The following custom properties are available in [`settings.ui.css`](/docs/tokens#interface-tokens):

| Property            | Color                     |
| ------------------- | ------------------------- |
| `--toc-color`       | Links color.              |
| `--toc-color-hover` | Links hover color.        |
| `--toc-spacing`     | Links padding.            |
| `--toc-icon-size`   | Icon size.                |
| `--toc-indentation` | Nested lists indentation. |

## Astro component

<div class="docs_oversizedTable prose">

| Prop           | Type      | Default       | Description                                                 |
| -------------- | --------- | ------------- | ----------------------------------------------------------- |
| `id`           | `string`  | `toc`         | Needed to add more than one TOC.                            |
| `selector`     | `string`  | `main`        | HTML element to scan for headings.                          |
| `headings`     | `array`   | `['h2','h3']` | Heading levels to include.                                  |
| `baseUrl`      | `string`  | `''`          | Optional URL to prepend `#id` with.                         |
| `scrollOffset` | `integer` | `0`           | Scroll position offset from the top..                       |
| `description`  | `string`  | `undefined`   | Text above the TOC.                                         |
| `icon`         | `string`  | `''`          | Optional inline SVG. (See example.)                         |
| `class`   | `string`  | `undefined`   | Additional CSS classes, useful for [helper classes](/docs/helpers). |

</div>

## Examples

<ul class="docs_examples">

<li>

### TOC with only H2s

<Toc
  id="example2"
  selector=".docs"
  headings={["h2"]}
  scrollOffset={800}
  description={"Just H2s"}
/>

```astro
---
import Toc from "../../components/Toc.astro";
---
<Toc
  id="example2"
  selector=".docs"
  headings={["h2"]}
  scrollOffset={80}
  description={"Just H2s"}
/>
```

</li>
<li>

### TOC with H2 — h4 and a ♥︎ icon

#### A H4 just as an example

<Toc
  id="example3"
  selector=".docs"
  headings={["h2", "h3", "h4"]}
  scrollOffset={80}
  icon={heart}
/>

```astro
---
import heart from "../../assets/icons/arrow-right-small.svg?raw";
import Toc from "../../components/Toc.astro";
---
<Toc
  id="example3"
  selector=".docs"
  headings={["h2", "h3", "h4"]}
  scrollOffset={80}
  icon={heart}
/>
```

</li>
</ul>