Skip to content

Commit c11b0c5

Browse files
mlwilkersonmlwilkerson
authored
Port more usage documentation from react-fortawesome (#9)
- update code samples for React Native - add section for using the style prop to set color
1 parent 15dda24 commit c11b0c5

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎README.md

+244
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@
1717
- [Installation](#installation)
1818
- [Add more styles or Pro icons](#add-more-styles-or-pro-icons)
1919
- [or with Yarn](#or-with-yarn)
20+
- [Usage](#usage)
21+
* [Explicit Import](#explicit-import)
22+
* [Build a Library to Reference Icons Throughout Your App More Conveniently](#build-a-library-to-reference-icons-throughout-your-app-more-conveniently)
23+
* [Change Color with a StyleSheet](#change-color-with-a-stylesheet)
2024
- [Frequent questions](#frequent-questions)
2125
* [How do I import the same icon from two different styles?](#how-do-i-import-the-same-icon-from-two-different-styles)
2226
* [I don't think tree-shaking is working; got any advice?](#i-dont-think-tree-shaking-is-working-got-any-advice)
@@ -92,6 +96,246 @@ $ yarn add @fortawesome/free-solid-svg-icons
9296
$ yarn add @fortawesome/react-native-fontawesome
9397
```
9498

99+
## Usage
100+
101+
You can use Font Awesome icons in your React Native components as simply as this:
102+
103+
```javascript
104+
<FontAwesomeIcon icon="coffee" />
105+
```
106+
107+
That simple usage is made possible when you add the `"coffee"` icon, to the
108+
_library_.
109+
110+
This is one of the two ways you can use Font Awesome 5 with React Native. We'll
111+
summarize both ways briefly and then get into the details of each below.
112+
113+
1. **Explicit Import**
114+
115+
Allows icons to be subsetted, optimizing your final bundle. Only the icons
116+
you import are included in the bundle. However, explicitly importing icons
117+
into each of many components in your app might become tedious, so you may
118+
want to build a library.
119+
120+
2. **Build a Library**
121+
122+
Explicitly import icons just once in some init module. Then add them to the
123+
library. Then reference any of them by icon name as a string from any
124+
component. No need to import the icons into each component once they're in
125+
the library.
126+
127+
### Explicit Import
128+
129+
For this example, we'll also reference the `@fortawesome/free-solid-svg-icons`
130+
module, so make sure you've added it to the project as well:
131+
132+
```
133+
$ npm i --save @fortawesome/free-solid-svg-icons
134+
```
135+
136+
or
137+
138+
```
139+
$ yarn add @fortawesome/free-solid-svg-icons
140+
```
141+
142+
Now, a simple React Native component might look like this:
143+
144+
```javascript
145+
import React, { Component } from 'react'
146+
import { View } from 'react-native'
147+
import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome'
148+
import { faCoffee } from '@fortawesome/free-solid-svg-icons'
149+
150+
type Props = {}
151+
export default class App extends Component<Props> {
152+
render() {
153+
return (
154+
<View>
155+
<FontAwesomeIcon icon={ faCoffee } />
156+
</View>
157+
)
158+
}
159+
}
160+
```
161+
162+
Notice that the `faCoffee` icon is imported from
163+
`@fortawesome/free-solid-svg-icons` as an object and then provided to the
164+
`icon` prop as an object.
165+
166+
Explicitly importing icons like this allows us to subset Font Awesome's
167+
thousands of icons to include only those you use in your final bundled file.
168+
169+
### Build a Library to Reference Icons Throughout Your App More Conveniently
170+
171+
You probably want to use our icons in more than one component in your app,
172+
right?
173+
174+
But with explicit importing, it could become tedious to import into each of
175+
your app's components every icon you want to reference in that component.
176+
177+
So, add them to the _library_. Do this setup once in some initializing module
178+
of your app, adding all of the icons you'll use in your app's React components.
179+
180+
Suppose `App.js` initializes my app, including the library. For this example,
181+
we'll add two individual icons, `faCheckSquare` and `faCoffee`. We also add all
182+
of the brands in `@fortawesome/free-brands-svg-icons`. This example would
183+
illustrate the benefits of building a library even more clearly if it involved
184+
fifty or a hundred icons, but we'll keep the example brief and leave it to your
185+
imagination as to how this might scale up with lots of icons.
186+
187+
Don't forget to add `@fortawesome/free-brands-svg-icons`:
188+
189+
```
190+
$ npm i --save @fortawesome/free-brands-svg-icons
191+
```
192+
193+
or
194+
195+
```
196+
$ yarn add @fortawesome/free-brands-svg-icons
197+
```
198+
199+
In `App.js`, where our app is initialized:
200+
201+
```javascript
202+
// ...
203+
import { library } from '@fortawesome/fontawesome-svg-core'
204+
import { fab } from '@fortawesome/free-brands-svg-icons'
205+
import { faCheckSquare, faCoffee } from '@fortawesome/free-solid-svg-icons'
206+
207+
library.add(fab, faCheckSquare, faCoffee)
208+
```
209+
210+
OK, so what's happening here?
211+
212+
In our call to <span style="white-space:nowrap;">`library.add()`</span> we're passing
213+
214+
- `fab`: which represents _all_ of the brand icons in
215+
<span style="white-space:nowrap;">`@fortawesome/free-brands-svg-icons`</span>.
216+
So any of the brand icons in that package may be referenced by icon name
217+
as a string anywhere else in our app.
218+
For example: `"apple"`, `"microsoft"`, or `"google"`.
219+
- `faCheckSquare` and `faCoffee`: Adding each of these icons individually
220+
allows us to refer to them throughout our app by their icon string names,
221+
`"check-square"` and `"coffee"`, respectively.
222+
223+
Now, suppose you also have React Native components `Beverage` and `Gadget` in your app.
224+
You don't have to re-import your icons into them. Just import the `FontAwesomeIcon`
225+
component, and when you use it, supply the icon prop an icon name as a string.
226+
227+
We'll make `Beverage.js` a functional component:
228+
229+
```javascript
230+
import React from 'react'
231+
import { View, Text } from 'react-native'
232+
import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome'
233+
234+
export const Beverage = () => (
235+
<View>
236+
<FontAwesomeIcon icon="check-square" />
237+
<Text>Favorite beverage: </Text><FontAwesomeIcon icon="coffee" />
238+
</View>
239+
)
240+
```
241+
242+
There's one another piece of magic that's happening in the background when
243+
providing icon names as strings like this: the `fas` prefix (for Font Awesome
244+
Solid) is being inferred as the default. Later, we'll look at what that means
245+
and how we can do something different than the default.
246+
247+
Now suppose `Gadget.js` looks like this:
248+
249+
```javascript
250+
import React from 'react'
251+
import { View, Text } from 'react-native'
252+
import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome'
253+
254+
export const Gadget = () => (
255+
<View>
256+
<FontAwesomeIcon icon="check-square" />
257+
<Text>Popular gadgets come from vendors like:</Text>
258+
<FontAwesomeIcon icon={['fab', 'apple']} />
259+
<FontAwesomeIcon icon={['fab', 'microsoft']} />
260+
<FontAwesomeIcon icon={['fab', 'google']} />
261+
</View>
262+
)
263+
```
264+
265+
Notice:
266+
267+
- We used the `"check-square"` icon name again in this component, though we
268+
didn't have to explicitly import it into this component. With one explicit import of
269+
that icon in `App.js`, and adding it to the library, we've managed to use
270+
it by name in multiple components.
271+
- We used the `"apple"`, `"microsoft"`, and `"google"` brand icons, which were
272+
never explicitly _individually_ imported, but they're available to us by
273+
name as strings because `fab` was added to our library in `App.js`, and
274+
`fab` includes all of those icons.
275+
- We added the `fab` prefix to reference those brand icons.
276+
277+
Adding a prefix—and the syntax we used to do it—are new. So what's
278+
going on here?
279+
280+
First, recall when we introduced `<FontAwesomeIcon icon="coffee"/>` and learned
281+
that a prefix of `fas` was being added to `"coffee"` by default.
282+
283+
The `"check-square"` icon is getting a default prefix of `fas` here too, which
284+
is what we want, because that icon also lives in the
285+
`@fortawesome/free-solid-svg-icons` package.
286+
287+
However, the `"apple"`, `"microsoft"`, and `"google"` brand icons live in the
288+
package `@fortawesome/free-brands-svg-icons`. So we need to specify a
289+
different prefix for them—not the default `fas`, but `fab`, for Font Awesome
290+
_Brand_.
291+
292+
When specifying a prefix with an icon name, both are given as strings.
293+
294+
Now, what about that syntax?
295+
296+
The `icon` prop expects a single object:
297+
298+
- It could be an icon object, like `{faCoffee}`.
299+
- It could a string object, like `"coffee"`.
300+
(The curly braces around a string object supplied to a prop are optional,
301+
so we've omitted them.)
302+
- Or it could be an `Array` of strings, where the first element is a prefix,
303+
and the second element is the icon name: `{["fab", "apple"]}`
304+
305+
### Change Color with a StyleSheet
306+
307+
As `react-native-svg` gains more support for [`StyleSheets`](https://github.com/react-native-community/react-native-svg/commit/e7d0eb6df676d4f63f9eba7c0cf5ddd6c4c85fbe), we will pass down to it the `StyleSheet` provided to the `style` prop on `FontAwesomeIcon`.
308+
309+
For now, there's just one `StyleSheet` property for which we've implemented special-case support: `color`.
310+
311+
To set the color of an icon, provide a `StyleSheet` like this:
312+
313+
```javascript
314+
import React, { Component } from 'react'
315+
import { View, StyleSheet } from 'react-native'
316+
import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome'
317+
import { faCoffee } from '@fortawesome/free-solid-svg-icons'
318+
319+
320+
type Props = {}
321+
322+
const style = StyleSheet.create({
323+
icon: {
324+
color: 'blue'
325+
}
326+
})
327+
328+
export default class App extends Component<Props> {
329+
render() {
330+
return (
331+
<View>
332+
<FontAwesomeIcon icon={ faCoffee } style={ style.icon } />
333+
</View>
334+
)
335+
}
336+
}
337+
```
338+
95339
## Frequent questions
96340

97341
### How do I import the same icon from two different styles?

0 commit comments

Comments
 (0)