# Custom Icons

You can provide custom sidebar & header icons for your stories.
Page stories can also provide iconized navigation tabs.

PhxLiveStorybook gives you the ability to render icons with 2 different providers:

- [FontAwesome](https://fontawesome.com) which offers a decent set of free icons and a lot of
  additional styles with paid plans
- [HeroIcons](https://heroicons.com) wich offer hundreds of free high quality icons

## Declaring an icon

Whenever you provide an icon to the storybook, you should follow the following structure:
`{:icon_provider, icon_name, :icon_style, additional_css_classes}`.

The two last tuple elements are optional.

```elixir
{:fa, "book"} # note that the FontAwesome icon name omits the fa- prefix
{:fa, "book", :solid} # same than previous one, :solid is the default style
{:fa, "skull", :duotone} # only for FontAwesome paid users
{:fa, "skull", :duotone, "px-2"}
{:hero, "cake"} # for all HeroIcons
{:hero, "cake", :outline} # same than previous one, :outline is the default style
{:hero, "cake", :outline, "w-2 h-2"}
```

## FontAwesome icons

PhxLiveStorybook is built with a very small subset of FontAwesome free icons. If you want to use
other FontAwesome icons you need to provide a valid **FontAwesome kit id**.

It can be either free or paid, so you also need to configure your FontAwesome plan.

```elixir
# lib/my_app_web/storybook.ex
defmodule MyAppWeb.Storybook do
  use PhxLiveStorybook,
    otp_app: :my_app,
    font_awesome_plan: :pro, # default value is :free
    font_awesome_kit_id: "foo8b41bar4625",
end
```

## HeroIcons

PhxLiveStorybook delegates icon rendering to [heroicons_elixir](https://github.com/mveytsman/heroicons_elixir).
Make sure to add their dependency in your `mix.exs` file.

```elixir
defp deps do
  [
    {:heroicons, "~> 0.5.0"}
  ]
end
```

You can now use whichever HeroIcon icon you want, based on the library function names.