# Icon

Use the icon shortcode to add a Font Awesome or custom icon with ease.

## Overview

Added in v0.8.0

Hinode includes support for [Font Awesome](https://fontawesome.com/) by default. This library provides both a free icon set, as well as utility functions to modify the appearance. You can also provide custom icons in the svg (Scalable Vector Graphics)
 format. Use the `icon` shortcode to quickly add a Font Awesome or custom icon to your content. You can also use `fa` for regular icons, `fab` for brand icons, and `fas` for solid icons.

### Relative sizing

Font Awesome includes a range of t-shirt based sizes that are relative to the browser's default font size of 16px. The icons align to the inline text. The following example illustrates the available relative sizes.

```markdown
{{< fas mug-saucer fa-2xs >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-xs >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-sm >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-md >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-lg >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-xl >}} When my six o’clock alarm buzzes, I require a pot of good java.

{{< fas mug-saucer fa-2xl >}} When my six o’clock alarm buzzes, I require a pot of good java.
```

The table below illustrates the relative sizing classes and their equivalent relative and absolute font size.

| Relative Sizing Class | Font Size | Equivalent in Pixels |
|-----------------------|----------:|---------------------:|
| `fa-2x`               |   0.625em |                 10px |
| `fa-xs`               |    0.75em |                 12px |
| `fa-sm`               |   0.875em |                 14px |
| `fa-md`               |       1em |                 16px |
| `fa-lg`               |    1.25em |                 20px |
| `fa-xl`               |     1.5em |                 24px |
| `fa-2xl`              |       2em |                 32px |

### Absolute sizing

Font Awesome also supports absolute sizing on a scale of 1x to 10x. The icons do not necessarily align to their surrounding text. The following example illustrates the various absolute sizes.

```markdown
{{< fas star fa-1x >}}
{{< fas star fa-2x >}}
{{< fas star fa-3x >}}
{{< fas star fa-4x >}}
{{< fas star fa-5x >}}
{{< fas star fa-6x >}}
{{< fas star fa-7x >}}
{{< fas star fa-8x >}}
{{< fas star fa-9x >}}
{{< fas star fa-10x >}}
```

The table below illustrates the absolute sizing classes and their equivalent font size.

| Absolute Sizing Class | Font Size |
|-----------------------|----------:|
| `fa-1x`               |       1em |
| `fa-2x`               |       2em |
| `fa-3x`               |       3em |
| `fa-4x`               |       4em |
| `fa-5x`               |       5em |
| `fa-6x`               |       6em |
| `fa-7x`               |       7em |
| `fa-8x`               |       8em |
| `fa-9x`               |       9em |
| `fa-10x`              |      10em |

### Responsive sizing

Hinode supports responsive sizing of icons using so-called containers. Add `fa-fluid` as attribute to the icon class and add `fa-wrapper` to the wrapper. The icon will scale to fill the available space.

> [!NOTE]
>
> - [Font Awesome v7](https://docs.fontawesome.com/upgrade/whats-changed/) introduced several changes to the icons and stylesheets. You may experience some subtle differences regarding whitespace and positioning compared to older versions.
> - Container support is a relatively new CSS feature that is not supported by all browsers yet. See this [browser compatibility overview](https://caniuse.com/?search=%40container) to check the current browser support. Hinode uses a fixed-size icon with a `font-size` of `5rem` as fallback.
>

The following example demonstrates a centered, responsive icon. The icon keeps its original aspect ratio, so the wrapper may have some whitespace. Use `mx-auto` to center the container.

```markdown
{{< fas icon="rocket bg-body-tertiary fa-fluid" wrapper="col-3 fa-wrapper mx-auto" >}}
```

### Fixed width

Add `fa-fw` to the class of the HTML element referencing your icon to apply a fixed width. This ensures icons of varying icon width are properly aligned to each other. The following example illustrates how this works.

```markdown
{{< fas person-skating fa-fw bg-body-tertiary >}} Skating
{.fa-3x}

{{< fas person-skiing fa-fw bg-body-tertiary >}} Skiing
{.fa-3x}

{{< fas person-skiing-nordic fa-fw bg-body-tertiary >}} Nordic Skiing
{.fa-3x}

{{< fas person-snowboarding fa-fw bg-body-tertiary >}} Snowboarding
{.fa-3x}

{{< fas snowplow fa-fw bg-body-tertiary >}} Snowplow
{.fa-3x}
```

### Lists

Use the classes `.fa-ul` and `.fa-li` to replace default bullets in unordered lists. The following example illustrates how this works.

```markdown
- {{< fas icon="circle-check" wrapper="fa-li" >}}List icons can
- {{< fas icon="square-check" wrapper="fa-li" >}}be used to
- {{< fas icon="spinner fa-pulse" wrapper="fa-li" >}} replace bullets
- {{< fa icon="square" wrapper="fa-li" >}} in lists
{.fa-ul}
```

### Rotating icons

Use specific classes to rotate the icon with a specific degree. The following example illustrates how this works.

```markdown
{{< fas person-snowboarding fa-3x >}}
{{< fas person-snowboarding fa-3x fa-rotate-90 >}}
{{< fas person-snowboarding fa-3x fa-rotate-180 >}}
{{< fas person-snowboarding fa-3x fa-rotate-270 >}}
{{< fas person-snowboarding fa-3x fa-flip-horizontal >}}
{{< fas person-snowboarding fa-3x fa-flip-vertical >}}
{{< fas person-snowboarding fa-3x fa-flip-both >}}
```

The following classes are available:

| Class                | Details                                          |
|----------------------|--------------------------------------------------|
| `fa-rotate-90`       | Rotates an icon 90°                              |
| `fa-rotate-180`      | Rotates an icon 180°                             |
| `fa-rotate-270`      | Rotates an icon 270°                             |
| `fa-flip-horizontal` | Mirrors an icon horizontally                     |
| `fa-flip-vertical`   | Mirrors an icon vertically                       |
| `fa-flip-both`       | Mirrors an icon both vertically and horizontally |

### Animating icons

Font Awesome supports various animations by simply adding a animation class to the HTML element. The following example illustrates the available basic animations. Add custom styles to your Sass files to apply additional [animation utilities](https://fontawesome.com/docs/web/style/animate).

```markdown
{{< fas heart fa-3x fa-beat >}}
{{< fas triangle-exclamation fa-3x fa-fade >}}
{{< fas circle-info fa-3x fa-beat-fade >}}
{{< fas basketball fa-3x fa-bounce >}}
{{< fas camera-rotate fa-3x fa-flip >}}
{{< fas bell fa-3x fa-shake >}}
{{< fas arrows-rotate fa-3x fa-spin >}}
```

The following table describes the available basic animation classes.

| Class          | Details                                      |
|----------------|----------------------------------------------|
| `fa-beat`      | Scales an icon up or down                    |
| `fa-fade`      | Fades an icon in and out                     |
| `fa-beat-fade` | Scales and pulses an icon in and out         |
| `fa-bounce`    | Bounces an icon up and down                  |
| `fa-flip`      | Rotates an icon about the Y axis 180 degrees |
| `fa-shake`     | Shakes an icon back and forth                |
| `fa-spin`      | Rotates an icon                              |

### Bordered and pulled icons

Use `fa-border` and `fa-pull-right` or `fa-pull-left` for easy pull quotes or article icons. The following example illustrates a quote.

```markdown
{{< icon icon="fas quote-left fa-2x fa-pull-left" spacing=false >}}
Gatsby believed in the green light, the orgastic future that year by year recedes before us.
It eluded us then, but that’s no matter — tomorrow we will run faster, stretch our arms further...
And one fine morning — So we beat on, boats against the current, borne back ceaselessly into the past.
```

The following table describes the available classes.

| Class           | Details                                                                 |
|-----------------|-------------------------------------------------------------------------|
| `fa-border`     | Creates a border with border-radius and padding applied around an icons |
| `fa-pull-left`  | Pulls an icon by floating it left and applying a margin-right           |
| `fa-pull-right` | Pulls an icon by floating it right and applying a margin-left           |

### Stacking icons

Use the `fa-stack` class on the parent HTML element of the two icons you want to stack. Then add the `fa-stack-1x` class for the regularly sized icon and add the `fa-stack-2x` class for the larger icon. `fa-inverse` can be added to the icon with the `fa-stack-1x` to help with a knock-out looking effect. Add a theme color such as `text-primary` to change the color of the icon. The following example illustrates the available options.

```markdown
{{< fas square fa-stack-2x >}}
{{< fab x-twitter fa-stack-1x fa-inverse >}}
{.fa-stack .fa-2x}

{{< fas circle fa-stack-2x >}}
{{< fas flag fa-stack-1x fa-inverse >}}
{.fa-stack .fa-2x}

{{< fas camera fa-stack-1x >}}
{{< fas ban fa-stack-2x text-danger >}}
{.fa-stack .fa-2x}

{{< fas square fa-stack-2x >}}
{{< fas terminal fa-stack-1x fa-inverse >}}
{.fa-stack .fa-4x}
```

The following table describes the available classes.

| Class         | Details                                                              |
|---------------|----------------------------------------------------------------------|
| `fa-stack`    | Used on a parent HTML element of the two icons to be stacked         |
| `fa-stack-1x` | Used on the icon which should be displayed at base size when stacked |
| `fa-stack-2x` | Used on the icon which should be displayed larger when stacked       |
| `fa-inverse`  | Inverts the color of the icon displayed at base size when stacked    |

## Specifying an icon family

Added in v2.0.0

Hinode provides support for multiple icon providers since release Added in v2.0.0
. All icons are compatible with [Font Awesome](https://fontawesome.com) styling. The following providers are available:

- [Bootstrap Icons](https://icons.getbootstrap.com) - import [mod-bootstrap-icons](https://github.com/gethinode/mod-bootstrap-icons)
- [Flat Icon](https://www.flaticon.com) - import [mod-flaticon](https://github.com/gethinode/mod-flaticon) (private module, license required)
- [Font Awesome](https://fontawesome.com) - import [mod-fontawesome](https://github.com/gethinode/mod-fontawesome) (imported by default)

Many providers offer multiple icon sets and styles. For example, Font Awesome supports the following styles:

- `fa` and `far` - regular style
- `fab` - brands
- `fas` - solid

You can configure a default style by setting `defaultFamily` in your site parameters:

```toml
[modules.fontawesome]
  defaultFamily = "bi"
```

The `icon` shortcode uses the default value when no family is provided. The following shortcodes are all equivalent:

```markdown
{{< icon heart >}}

{{< icon bi heart >}}

{{< bi heart >}}
```

## Adding custom icons

Added in v0.20.5

> [!NOTE]
> Hinode removes any embedded `height` and `width` attributes from the icon data to ensure the icon is responsive. The `viewBox` attribute is kept.

You can reference a custom family and icon stored in the local `assets` folder. The icon shortcode uses the path `assets/svgs/{family}/{icon}.svg`, replacing `{family}` and `{icon}` with the specified values. You can mix the custom icon with Font Awesome styling directives (such as `fa-4x`, although animations are typically not supported). The following example shows an icon called `activity` of the `custom` family of size `fa-4x`.

```markdown
{{< icon custom activity fa-4x >}}
```

## Configuration

> [!IMPORTANT]
> Webfonts (`inline = false`) require [Dart Sass](https://sass-lang.com/dart-sass/) to function correctly. See the [Hugo documentation](https://gohugo.io/functions/css/sass/#dart-sass) for installation instructions.

The [Font Awesome module](https://github.com/gethinode/mod-fontawesome) supports the following site parameters (using `params.modules` in `config.toml` or `hugo.toml`):

| Setting                   | Default | Description |
|---------------------------|---------|-------------|
| `fontawesome.mode`       | 'symbols'    | Added in v2.0.0
 Specifies the rendering mode of the icons, either [`webfonts`, `svg`, or `symbols`]. When using symbols, all icons on the same page a grouped in a symbol map and are referenced by name. |
| `fontawesome.debug`       | true    | If set, prints the original code `<i class="[...]" style=[...]></i>` as comments next to the inline vector image. |
| `fontawesome.skipMissing` | false   | If set, displays a warning when an icon cannot be found. The missing icon is replaced with a dummy. By default, Hinode exits with an error when an icon is missing. |
| `fontawesome.embed`       | true    | Deprecated in v2.0.0
 **Use `mode=symbols` instead**. |
| `fontawesome.inline`      | true    | Deprecated in v2.0.0
 **Use `mode=svg` instead**. |

## Arguments

> [!IMPORTANT]
> When using inline vector icons, be sure to use the main name of the icon. The shortcode **does not recognize the aliases** of the icons and will throw an error or warning. For example, use `{{< fas house >}}` instead of `{{< fas home >}}` to add a house icon.

The shortcode supports both unnamed arguments and named arguments. When using unnamed arguments, all attributes are mapped to the `class` argument, separated by spaces.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `class` | string |  |  | Modifier classes for styling and animation (e.g., `fa-2x`, `fa-spin`, `fa-beat`). Reintroduced in v2.0.0 after being deprecated in v1.0.0. Previously used for full icon specification (family, name, styling); now exclusively for modifier classes. When using family-specific shortcodes with positional arguments, all arguments after the icon name are joined as modifier classes. |
| `icon` | string |  |  | Icon to include. You can use shorthand notation such as `fas sort` to include a Font Awesome icon. The argument also supports files with an `.svg` extension. Inline type definition overrides global for position support. |
| `inline-style` | string |  |  | Custom style of the element, e.g. `--fa-animation-duration: 2s;`. Please note that Hinode disables inline styles by default, review the Content Security Policy for more details. |
| `spacing` | bool |  | `true` | Flag to add spacing to the inline element. |
| `src` | string |  |  | Source of the icon file. If set, loads the icon from this path instead of using the icon name. |
| `wrapper` | string |  |  | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |