/
README.Rmd
109 lines (79 loc) · 5.11 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
# icons <a href='https://pkg.mitchelloharawild.com/icon'><img src='man/figures/logo.png' align="right" height="138" /></a>
[](https://github.com/mitchelloharawild/icons/actions/workflows/R-CMD-check.yaml)
[](https://codecov.io/gh/mitchelloharawild/icon?branch=master)
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://cran.r-project.org/package=icons)
<!-- [](https://cran.r-project.org/package=icons) -->
The `icons` package for R makes adding web icons to reports, presentations and apps easy. It integrates many popular icon libraries from around the web with a simple interface that works with any `rmarkdown` output format. If a particular icon library is not explicitly supported by this package, you can still use it by creating a custom icon set from a folder of SVG files. Icons provide flexible means of digital expression, allowing expressions and functionality beyond what is possible with emoji.
The `icons` package currently provides helpful tools for downloading and using icons from these libraries:
* [Font Awesome](https://github.com/FortAwesome/Font-Awesome/) (Pro icons can be used using custom icon sets)
* [Ionicons](https://github.com/ionic-team/ionicons/)
* [Academicons](https://github.com/jpswalsh/academicons)
* [Simple Icons](https://github.com/simple-icons/simple-icons/)
* [Google's Material Design](https://github.com/google/material-design-icons)
* [Octicons](https://github.com/primer/octicons)
* [Feather Icons](https://github.com/feathericons/feather)
* [Bioicons](https://github.com/duerrsimon/bioicons)
# Installation
The **development** version can be installed from GitHub using:
```{r gh-installation, eval = FALSE}
# install.packages("remotes")
remotes::install_github("mitchelloharawild/icons")
```
Once you've installed the package you'll also need to download some icons! Supported icon libraries (listed above) can be downloaded using the `download_*()` functions. For example, to download the Font Awesome icons you would use `download_fontawesome()`.
# Usage
```{r load}
library(icons)
```
Icons can be inserted inline using inline code `` `r knitr::inline_expr('icons::fontawesome("rocket", style = "solid")')` `` `r icons::fontawesome("rocket", style = "solid")` or `` `r knitr::inline_expr('icons::fontawesome$solid$rocket')` `` `r icons::fontawesome$solid$rocket`.
Icons can also be inserted using usual R chunks.
````
```{r icon-chunk}`r ''`
fontawesome("rocket", style = "solid") # equivalent to icons::fontawesome$solid$rocket
```
````
```{r icon-chunk, echo=FALSE}
fontawesome("rocket", style = "solid")
```
If the icon name contains non-syntactic name characters like a `-` or `+`, you will need to quote the name with backticks, single or double quotes:
```{r icon-syntax}
fontawesome$brands$`r-project` # or 'r-project' or "r-project"
```
The appearance of an icon can be customised using the `icon_style()` function.
````
```{r icon-style}`r ''`
icon_style(fontawesome("rocket", style = "solid"), scale = 2, fill = "red")
```
````
```{r icon-style, echo=FALSE}
icon_style(fontawesome("rocket", style = "solid"), scale = 2, fill = "red")
```
Custom icon sets can be created using the `icon_set()` function, which accepts a directory of SVG files and allows them to be used as icons.
````
```{r icon-custom}`r ''`
custom <- icons::icon_set("hex")
custom$icons
```
````
```{r icon-custom, echo=FALSE}
custom <- icon_set("hex")
custom$icons
```
You can also search for icons using the `icon_find()` function.
```{r icon-find}
icon_find("rocket")
```
# A Note on the old API
This is the second iteration of the icon package, the [first icon package](https://github.com/ropenscilabs/icon) has been successful, but lacked a few features such as SVG icons, user defined libraries, and extensibility support. You can read the notes on the new API [here](https://github.com/ropenscilabs/icon/issues/19). It turns out that it was easier to build the new and improved icon from scratch, which is what this repository is. In the future this version of icon might just be merged into rOpenScilabs/icon, but for the mean time it will be developed here. We anticipate that there will only be any minor changes to the existing API, so hopefully this will be a seamless transition for users! Notably, the `icon_name` functions have been removed in favour of `icon$name`, and the interface for styling and animating has been removed/changed.
If you need to use the first version of the package that was developed from the rOpenSci hackathon, you can install it with `remotes::install_github("mitchelloharawild/icons@v0.1.0")`.