> ## Documentation Index
> Fetch the complete documentation index at: https://phiki.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Decorations

Decorations allow you to apply custom classes to specific elements in the generated HTML. This is useful if you want to style certain regions of your code blocks differently, such as focusing attention on specific lines or adding custom colors.

## Pre decorations

To add additional classes to the `<pre>` element that wraps the entire code block, you can pass a `PreDecoration` instance to the `PendingHtmlOutput::decoration()` method.

```php theme={null}
use Phiki\Transformers\Decorations\PreDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        PreDecoration::make()->class('pre-class'),
    );
```

This will add the `pre-class` class to the `<pre>` element.

## Code decorations

To add additional classes to the `<code>` element that wraps the entire code block, you can pass a `CodeDecoration` instance to the `PendingHtmlOutput::decoration()` method.

```php theme={null}
use Phiki\Transformers\Decorations\CodeDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        CodeDecoration::make()->class('code-class'),
    );
```

## Line decorations

To add additional classes to line elements, you can pass a `LineDecoration` instance to the `PendingHtmlOutput::decoration()` method.

```php theme={null}
use Phiki\Transformers\Decorations\LineDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        LineDecoration::forLine(0)->class('focus'),
    );
```

This will add the `focus` class to the first line of the code block, since lines are zero-indexed.

## Gutter decorations

To add additional classes to the gutter element that contains line numbers, you can pass a `GutterDecoration` instance to the `PendingHtmlOutput::decoration()` method.

```php theme={null}
use Phiki\Transformers\Decorations\GutterDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->withGutter()
    ->decoration(
        GutterDecoration::make()->class('gutter-class'),
    );
```

This will add the `gutter-class` class to the gutter element.

## Substring decorations

At the time of writing, you can only decorate entire lines.

There are plans to support substring decorations in a future release, which will allow you to apply classes to specific parts of a line. This is quite an involved feature so it may take some time to implement.