<p align="center">
<img src="assets/logo.png" height="128">
<h1 align="center">PhxFontawesome</h1>
<p align="center">
A simple Mix task that generates Phoenix Components from Font Awesome SVG files.
</p>
</p>
## Installation
This package is [available in Hex](https://hex.pm/packages/phx_fontawesome), and can be installed
by adding `phx_fontawesome` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:phx_fontawesome, "~> 1.1.1"}
]
end
```
## Generate Heex components
**Step 1 - Install desired font set**
In your Phoenix project, install desired font set using `npm` or `yarn`. Please consult the Font Awesome
[documentation](https://fontawesome.com/docs/web/setup/packages) if you run into any trouble here.
```shell
$ cd assets/
$ yarn add @fortawesome/fontawesome-free
# or
$ yarn add @fortawesome/fontawesome-pro # needs a license
```
**Step 2 - Choose font set types to generate**
In your `config.exs`, you may choose which types to generate `heex` components for. Defaults to `regular` and `solid`.
```elixir
config :phx_fontawesome,
types: ["regular", "solid"]
```
**Step 3 - Generate component files**
From your project root, run `mix phx_fontawesome.generate` to create components. Generated files will be available in your
`lib/phx_fontawesome` directory.
```shell
$ mix phx_fontawesome.generate
[info] Successfully wrote /path/to/my_project/lib/phx_fontawesome/fontawesome_free/regular.ex (containing 162 SVG components).
[info] Successfully wrote /path/to/my_project/lib/phx_fontawesome/fontawesome_free/solid.ex (containing 1385 SVG components).
```
## Usage
Once generated, the `heex` components are part of your project, and can be used as a regular `Phoenix.Component`.
Icon name can be the function or passed in as a type.
```html
<PhxFontawesome.Free.Solid.angle_up />
<PhxFontawesome.Free.Regular.render icon="angle_up" />
<!-- override default classes -->
<PhxFontawesome.Free.Solid.angle_up class="my-custom-class" />
<!-- pass extra properties -->
<PhxFontawesome.Free.Solid.angle_up title="Font Awesome angle-up icon" />
```
If you would like to apply the default styling for SVG elements, simply include the Font Awesome CSS in your `app.css` file.
```css
@import "@fortawesome/fontawesome-free/css/all.css";
@import "@fortawesome/fontawesome-free/css/svg-with-js.css";
```
Keep in mind that if you're using the non-free version of Font Awesome, make sure that you don't publish the
generated components as that would be a licensing breach.
Consider adding `/lib/phx_fontawesome/` to your `.gitignore` file, and use `mix phx_fontawesome.generate` in your deployment
pipeline to build SVG components for deployed applications.
### Credits
- Heavily inspired by the [Petal Components](https://github.com/petalframework/petal_components) project.
- Logo comes from the [Font Awesome](https://commons.wikimedia.org/wiki/File:Font_Awesome_5_brands_phoenix-framework.svg) project.
