Generate Font Awesome icons as SVGs
Description
Add one or more Font Awesome icons as SVGs contained within <svg>...</svg>.
We can optionally set certain style attributes. The fa() function can be
used directly within inline evaluations of R code in R Markdown documents.
Usage
fa(
name,
fill = NULL,
fill_opacity = NULL,
stroke = NULL,
stroke_width = NULL,
stroke_opacity = NULL,
height = NULL,
width = NULL,
margin_left = NULL,
margin_right = NULL,
vertical_align = NULL,
position = NULL,
title = NULL,
prefer_type = c("regular", "solid"),
a11y = c("deco", "sem", "none")
)
Arguments
name |
The name of the Font Awesome icon. This could be as a short name
(e.g., "npm", "drum", etc.), or, a full name (e.g., "fab fa-npm",
"fas fa-drum", etc.). The names should correspond to current Version 6
Font Awesome names. A list of short and full names can be accessed through
the fa_metadata() function with fa_metadata()$icon_names and
fa_metadata()$icon_names_full. If supplying a previous name associated
with the icon, it will be internally translated to the current name and a
Version 6 icon will be returned.
|
fill, fill_opacity
|
The fill color of the icon can be set with fill.
If not provided then the default value of "currentColor" is applied so
that the SVG fill matches the color of the parent HTML element's color
attribute. The opacity level of the SVG fill can be controlled with a
decimal value between 0 and 1.
|
stroke, stroke_width, stroke_opacity
|
The stroke options allow for
setting the color, width, and opacity of the SVG outline stroke. By
default, the stroke width is very small at "1px" so a size adjustment
with "stroke_width" can be useful. The "stroke_opacity" value can be
any decimal values between 0 and 1 (bounds included).
|
height, width
|
The height and width style attributes of the rendered
SVG. If nothing is provided for height then a default value of "1em"
will be applied. If a width isn't given, then it will be calculated in
units of "em" on the basis of the icon's SVG "viewBox" dimensions.
|
margin_left, margin_right
|
The length value for the margin that's either
left or right of the icon. By default, "auto" is used for both
properties. If space is needed on either side then a length of "0.2em" is
recommended as a starting point.
|
vertical_align |
The vertical alignment of the icon. By default, a
length of "-0.125em" is used.
|
position |
The value for the position style attribute. By default,
"relative" is used here.
|
title |
An option for populating the SVG 'title' attribute, which
provides on-hover text for the icon. By default, no title text is given to
the icon. If a11y == "semantic" then title text will be
automatically given to the rendered icon, however, providing text here
will override that.
|
prefer_type |
Chooses the type of icon returned if: (1) providing a
short name, and (2) that icon has both solid and regular types.
For example, using name = "address-book" will result in two types of
icons for an Address Book. By default, this preference is set to
"regular" and the other option is "solid".
|
a11y |
Cases that distinguish the role of the icon and inform which
accessibility attributes to be used. Icons can either be "deco"
(decorative, the default case) or "sem" (semantic). Using "none" will
result in no accessibility features for the icon.
|
Value
A fontawesome object.
Examples
if (interactive()) {
fa(name = "r-project")
}
Use a Font Awesome html_dependency
Description
The fa_html_dependency() function adds a html_dependency object into a
Shiny or R Markdown context. This allows for the direct use of <i> tags
that refer to Font Awesome icons without having to use the fa_i() to create
these tags and also add the html_dependency to the document.
Usage
fa_html_dependency()
Details
The html_dependency object is created internally with the following
invocation:
htmltools::htmlDependency(
name = "font-awesome",
version = fa_version,
src = "fontawesome",
package = "fontawesome",
stylesheet = c("css/all.min.css", "css/v4-shims.min.css")
)
The fa_version object is an internal object that provides the released
version number for the Font Awesome icons. This can be inspected by using
fa_metadata()$version.
Value
An html_dependency object.
Examples
if (interactive()) {
fa_html_dependency()
}
Generate a Font Awesome <i> tag
Description
The fa_i() function creates a Font Awesome <i> tag and not an SVG as with
fa(). The primary use case for fa_i() is for legacy Shiny applications
that use the shiny::icon() function. This function is called within a
shiny::icon() call and all HTML dependencies to support icon generation are
hosted in the fontawesome package.
Usage
fa_i(
name,
class = NULL,
...,
prefer_type = c("regular", "solid"),
html_dependency = fa_html_dependency()
)
Arguments
name |
The name of the Font Awesome icon. This could be as a short name
(e.g., "npm", "drum", etc.), or, a full name (e.g., "fab fa-npm",
"fas fa-drum", etc.). The names should correspond to current Font Awesome
names. A list of short and full names can be accessed through the
fa_metadata() function with fa_metadata()$icon_names and
fa_metadata()$icon_names_full. If supplying a known alias to a short icon
name (e.g., "vcard", which is now "address-card"), it will be
internally translated to the current icon name before returning the icon
tag.
|
class |
Additional classes to customize the style of the icon.
|
... |
Arguments passed to the <i> tag of htmltools::tags.
|
prefer_type |
Chooses the type of icon returned if: (1) providing a
short name, and (2) that icon has both solid and regular types.
For example, using name = "address-book" will result in two types of
icons for an Address Book. By default, this preference is set to
"regular" and the other option is "solid".
|
html_dependency |
Provides an opportunity to use a custom
html_dependency object (created via a call to
htmltools::htmlDependency()) instead of one supplied by the function
(which uses Font Awesome's free assets and are bundled in the package). A
custom html_dependency object is useful when you have paid icons from
Font Awesome or would otherwise like to customize exactly which icon assets
are used (e.g., woff, woff2, eot, etc.). By default, this is NULL
where the function internally generates an html_dependency.
|
Value
An icon element.
Examples
if (interactive()) {
fa_i(name = "r-project")
}
Create a PNG version of a Font Awesome icon
Description
Get a Font Awesome icon as a PNG file. We can optionally set the fill
attribute before writing the PNG. Additionally, there is control over the
output width and height (usually, icons are 512 by 512 pixels). Please note
that this function requires that the rsvg is installed on the system.
Attempting to use fa_png() without rsvg available will result in an
error message.
Usage
fa_png(
name,
file = NULL,
fill = NULL,
fill_opacity = NULL,
stroke = NULL,
stroke_width = NULL,
stroke_opacity = NULL,
height = NULL,
width = NULL,
prefer_type = c("regular", "solid")
)
Arguments
name |
The name of the Font Awesome icon.
|
file |
the path to the output file. If NULL, then filename will take
the short name of the icon and a .png extension will be applied.
|
fill, fill_opacity
|
The fill color of the icon can be set with fill.
If not provided then the default fill color will be black. The opacity
level of the fill color can be controlled with a decimal value between 0
and 1.
|
stroke, stroke_width, stroke_opacity
|
The stroke options allow for
setting the color, width, and opacity of the outline stroke. By default,
the stroke width is very small at "1px" so a size adjustment with
"stroke_width" can be useful. The "stroke_opacity" value can be any
decimal values between 0 and 1 (bounds included).
|
height, width
|
The output height and width of the rendered PNG. If
nothing is provided then the output dimensions will match that of the input
SVG viewBox.
|
prefer_type |
Chooses the type of icon returned if: (1) providing a
short name, and (2) that icon has both solid and regular types.
For example, using name = "address-book" will result in two types of
icons for an Address Book. By default, this preference is set to
"regular" and the other option is "solid".
|
Value
A PNG file written to disk.
Examples
if (interactive()) {
fa_png(name = "r-project")
}
