font_awesomex

Build Status

A library to render Font Awesome markup. Integrates seamlessly with your Phoenix application.

:warning: This repository does not contain any Font Awesome assets. :warning:

Prerequisites

Installation

Add font_awesomex to your list of dependencies in mix.exs:

def deps do
  [{:font_awesomex, "~> 4.0.0"}]
end

Usage

Plain Ol' Elixir

iex> icon = FontAwesome.icon(:stop_circle, outline: true, size: 3)
%FontAwesome{name: "stop-circle", outline: true, size: 3, ...}

iex> to_string(icon)
"<i class=\"fa fa-stop-circle-o fa-size-3x\"></i>"

Following options are available:

Name Description Values CSS Classes
:outline Renders the outline variant (only some icons) true, false name suffixed with -o

| :direction | Defines the direction (only some icons) | :left, :right, :up, :down | name suffixed with -left, -right, ... | :fixed_width | Fixes the icon width (may be configured globally) | true, false | fa-fw | | :size | Scales the icon | :lg, 2, 3, 4 | fa-lg, fa-2x | | :rotate | Rotates the icon | 0, 90, 180, 270 | fa-rotate-90 | | :flip | Flips the icon horizontally or vertically | :horizontal, :vertical | fa-flip-vertical | | :animate | Adds an animation to the icon | :spin, :pulse | fa-spin, fa-pulse | | :list | Treats the icon as list bullet | true, false | fa-li | | :border | Adds a border to the icon | true, false | fa-border | | :pull | Aligns the icon :left or :right | true, false | fa-pull-left | | :stacked | Indicates whether the icon is used in a stack | true, false | fa-stack |

Phoenix Framework

To integrate the icon helpers with Phoenix views and templates you simply need to use it on top of your file:

defmodule MyApp.PageView do
  use MyApp.Web, :view
  use FontAwesome

  def hello_world do
    content_tag :div do
      [
        icon(:smile, outline: true, animate: :spin, size: 3),
        "Hello World"
      ]
    end
  end
end

If you want to add the helper to all views and templates, you can use or import it in the view/0 function of your web/web.ex file:

defmodule MyProject.Web do
  def view do
    quote do
      # Provides the icon/1 and icon/2 functions to all views and templates
      use FontAwesome
    end
  end
end

There may be cases when the default name (icon) conflicts with your existing implementation. In these cases you can define a name when using the module:

defmodule MyApp.PageView do
  use MyApp.Web, :view
  use FontAwesome, as: :fa_icon

  def scroll_down do
    [
      fa_icon(:arrow, direction: :down),
      "Scroll Down"
    ]
  end
end

Global Configuration

Alternatively, the helper name may be defined globally right from the start. So everytime you use FontAwesome, it generates a helper with the name you defined. Add this line to your config/config.exs:

config :font_awesome, helper_name: :fa_icon

To make all icons have a fixed width by default, add the following line.

config :font_awesome, fixed_width: true

The value can still be overridden per-icon.

What's missing

Contribution