lattyware / elm-fontawesome / FontAwesome

Rendering icons for use in HTML.

This library is designed with a pipeline style, at its simplest:

icon |> view

More complex pipelines can be created by adding steps between these.


type alias Icon hasId =
Internal.Icon hasId

Information on how an icon should be rendered. In general, you shouldn't need to interact directly with this type - it should generally only exist in a chain of operations to display an icon.

Adding titles or using masking require that the icon has a unique id. This is because references are made in the HTML via the HTML id attribute, which must be unique on the page. Views with an id will have the WithId type and will therefore work with those options, while ones that have the WithoutId type won't.


type alias WithId =
Internal.WithId

Indicates that the presentation has an id, which lets you use titled and masked. For more on why those features are "locked" like this, see the documentation for the View type above.


type alias WithoutId =
Internal.WithoutId

Indicates that the presentation does not have an id, which means you can't use titled and masked. For more on why those features are "locked" like this, see the documentation for the View type above.

view : Icon hasId -> Html msg

Render the given icon to HTML.

styled : List (Svg.Attribute Basics.Never) -> Icon hasId -> Icon hasId

Add the given attributes to the icon's presentation. These will be applied to the icon when viewed. Note the icon is an svg tag, and it appears that using Html.Attribute.class will remove any Svg.Attribute.class values that are set, including FontAwesome ones that make the icon work, so make sure to use Svg.Attribute.class with this.

Due to this taking Svg.Attribute Never you can't use attributes that can produce messages. You can use viewWithAttributes to add such attributes if required.

transform : List Transforms.Transform -> Icon hasId -> Icon hasId

Add the given transforms to the icon's presentation. These will be applied to the icon when viewed.

withId : String -> Icon WithoutId -> Icon WithId

Set the HTML id for the icon presentation to the given value. This must be unique on the page.

The FontAwesome JavaScript library generates random ids for this. Doing this in elm is a little more cumbersome, but is possible if you need to dynamically generate items and don't have existing ids to work from. Please see the elm-fontawesome-example repository for an example of this.

titled : String -> Icon WithId -> Icon WithId

Sets the title of the presented icon. This will make the icon semantically meaningful, and as such it won't be hidden from accessibility tools.

Note that this can only be applied where the icon has an id unique on the page as it uses that id under the hood in the HTML. Use withId to add one.

masked : Icon WithId -> Icon hasId -> Icon hasId

Sets an outer icon that the main icon is masking (i.e.: the initial icon will become a "cut out" of this outer icon). This creates true transparency.

Note that this can only be applied where the icon to be masked has an id unique on the page as it uses that id under the hood in the HTML. Use withId to add one.


type alias IconDef =
{ prefix : String
, name : String
, size : ( Basics.Int
, Basics.Int )
, paths : ( String
, Maybe String ) 
}

The definition of an icon.

You will find these in the modules for the different IconDef packs (e.g: FontAwesome.Solid.Definition). You should never need to define these or change them yourself (but you can to create custom icons).

Generally you want to work with Icon instead, which can be found in the parent packs.

present : IconDef -> Icon WithoutId

Gets a basic presentation of an icon.

If you do nothing else an pass this to view, the icon will be presented as semantically meaningless (i.e: purely decorative) and will be hidden from accessibility tools. If you need the icon to have semantic meaning then using titled will change that.