1 | <img src="/meta/phosphor-mark-tight-yellow.png" width="128" align="right" />
|
2 |
|
3 | # phosphor-react
|
4 |
|
5 | Phosphor is a flexible icon family for interfaces, diagrams, presentations — whatever, really. Explore all our icons at [phosphoricons.com](https://phosphoricons.com).
|
6 |
|
7 | [![NPM](https://img.shields.io/npm/v/phosphor-react.svg?style=flat-square)](https://www.npmjs.com/package/phosphor-react) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com) [![Travis](https://img.shields.io/travis/com/rektdeckard/phosphor-react.svg?style=flat-square)](https://travis-ci.com/github/rektdeckard/phosphor-react)
|
8 |
|
9 | [![GitHub stars](https://img.shields.io/github/stars/phosphor-icons/phosphor-react?style=flat-square&label=Star)](https://github.com/phosphor-icons/phosphor-react)
|
10 | [![GitHub forks](https://img.shields.io/github/forks/phosphor-icons/phosphor-react?style=flat-square&label=Fork)](https://github.com/phosphor-icons/phosphor-react/fork)
|
11 | [![GitHub watchers](https://img.shields.io/github/watchers/phosphor-icons/phosphor-react?style=flat-square&label=Watch)](https://github.com/phosphor-icons/phosphor-react)
|
12 | [![Follow on GitHub](https://img.shields.io/github/followers/rektdeckard?style=flat-square&label=Follow)](https://github.com/rektdeckard)
|
13 |
|
14 | ## Installation
|
15 |
|
16 | ```bash
|
17 | yarn add phosphor-react
|
18 | ```
|
19 |
|
20 | or
|
21 |
|
22 | ```bash
|
23 | npm install --save phosphor-react
|
24 | ```
|
25 |
|
26 | ## Usage
|
27 |
|
28 | Simply import the icons you need, and add them anywhere in your render method. Phosphor supports tree-shaking, so your bundle only includes code for the icons you use.
|
29 |
|
30 | ```tsx
|
31 | import React from "react";
|
32 | import ReactDOM from "react-dom";
|
33 | import { Horse, Heart, Cube } from "phosphor-react";
|
34 |
|
35 | const App = () => {
|
36 | return (
|
37 | <div>
|
38 | <Horse />
|
39 | <Heart color="#AE2983" weight="fill" size={32} />
|
40 | <Cube color="teal" weight="duotone" />
|
41 | </div>
|
42 | );
|
43 | };
|
44 |
|
45 | ReactDOM.render(<App />, document.getElementById("root"));
|
46 | ```
|
47 |
|
48 | ### Props
|
49 |
|
50 | Icon components accept all props that you can pass to a normal SVG element, including inline `style` objects, `onClick` handlers, and more. The main way of styling them will usually be with the following props:
|
51 |
|
52 | - **color?**: `string` – Icon stroke/fill color. Can be any CSS color string, including `hex`, `rgb`, `rgba`, `hsl`, `hsla`, named colors, or the special `currentColor` variable.
|
53 | - **size?**: `number | string` – Icon height & width. As with standard React elements, this can be a number, or a string with units in `px`, `%`, `em`, `rem`, `pt`, `cm`, `mm`, `in`.
|
54 | - **weight?**: `"thin" | "light" | "regular" | "bold" | "fill" | "duotone"` – Icon weight/style. Can also be used, for example, to "toggle" an icon's state: a rating component could use Stars with `weight="regular"` to denote an empty star, and `weight="fill"` to denote a filled star.
|
55 | - **mirrored?**: `boolean` – Flip the icon horizontally. Can be useful in RTL languages where normal icon orientation is not appropriate.
|
56 | - **alt?**: `string` – Add accessible alt text to an icon.
|
57 |
|
58 | ### Context
|
59 |
|
60 | Phosphor takes advantage of React Context to make applying a default style to all icons simple. Create an `IconContext.Provider` at the root of the app (or anywhere above the icons in the tree) and pass in a configuration object with props to be applied by default to all icons:
|
61 |
|
62 | ```tsx
|
63 | import React from "react";
|
64 | import ReactDOM from "react-dom";
|
65 | import { IconContext, Horse, Heart, Cube } from "phosphor-react";
|
66 |
|
67 | const App = () => {
|
68 | return (
|
69 | <IconContext.Provider
|
70 | value={{
|
71 | color: "limegreen",
|
72 | size: 32,
|
73 | weight: "bold",
|
74 | mirrored: false,
|
75 | }}
|
76 | >
|
77 | <div>
|
78 | <Horse /> {/* I'm lime-green, 32px, and bold! */}
|
79 | <Heart /> {/* Me too! */}
|
80 | <Cube /> {/* Me three :) */}
|
81 | </div>
|
82 | </IconContext.Provider>
|
83 | );
|
84 | };
|
85 |
|
86 | ReactDOM.render(<App />, document.getElementById("root"));
|
87 | ```
|
88 |
|
89 | You may create multiple Contexts for styling icons differently in separate regions of an application; icons use the nearest Context above them to determine their style.
|
90 |
|
91 | > **Note:** The context will also pass any provided SVG props down to icon instances, which can be useful E.G. in adding accessible `aria-label`s, `classNames`, etc.
|
92 |
|
93 | ### Composability
|
94 |
|
95 | <img src="/meta/cube-rotate.svg" width="128" align="right" />
|
96 |
|
97 | Components can accept arbitrary SVG elements as children, so long as they are valid children of the `<svg>` element. This can be used to modify an icon with background layers or shapes, filters, animations and more. The children will be placed *below* the normal icon contents.
|
98 |
|
99 | The following will cause the Cube icon to rotate and pulse:
|
100 |
|
101 | ```jsx
|
102 | const RotatingCube = () => {
|
103 | return (
|
104 | <Cube color="darkorchid" weight="duotone">
|
105 | <animate
|
106 | attributeName="opacity"
|
107 | values="0;1;0"
|
108 | dur="4s"
|
109 | repeatCount="indefinite"
|
110 | ></animate>
|
111 | <animateTransform
|
112 | attributeName="transform"
|
113 | attributeType="XML"
|
114 | type="rotate"
|
115 | dur="5s"
|
116 | from="0 0 0"
|
117 | to="360 0 0"
|
118 | repeatCount="indefinite"
|
119 | ></animateTransform>
|
120 | </Cube>
|
121 | );
|
122 | };
|
123 | ```
|
124 |
|
125 | > **Note:** The coordinate space of slotted elements is relative to the contents of the icon `viewBox`, which is a 256x256 square. Only [valid SVG elements](https://developer.mozilla.org/en-US/docs/Web/SVG/Element#SVG_elements_by_category) will be rendered.
|
126 |
|
127 | ### Imports
|
128 |
|
129 | You may wish to import all icons at once for use in your project, though depending on your bundler this could prevent tree-shaking and make your app's bundle larger.
|
130 |
|
131 | ```tsx
|
132 | import * as Icon from "phosphor-react";
|
133 | ...
|
134 | <Icon.Smiley />
|
135 | <Icon.Folder weight="thin" />
|
136 | <Icon.BatteryHalf size="24px" />
|
137 | ```
|
138 |
|
139 | ## Our Related Projects
|
140 |
|
141 | - [phosphor-home](https://github.com/phosphor-icons/phosphor-home) ▲ Phosphor homepage and general info
|
142 | - [phosphor-vue](https://github.com/phosphor-icons/phosphor-vue) ▲ Phosphor icon component library for Vue
|
143 | - [phosphor-icons](https://github.com/phosphor-icons/phosphor-icons) ▲ Phosphor icons for Vanilla JS
|
144 | - [phosphor-flutter](https://github.com/phosphor-icons/phosphor-flutter) ▲ Phosphor IconData library for Flutter
|
145 | - [phosphor-webcomponents](https://github.com/phosphor-icons/phosphor-webcomponents) ▲ Phosphor icons as Web Components
|
146 | - [phosphor-figma](https://github.com/phosphor-icons/phosphor-figma) ▲ Phosphor icons Figma plugin
|
147 | - [phosphor-sketch](https://github.com/phosphor-icons/phosphor-sketch) ▲ Phosphor icons Sketch plugin
|
148 |
|
149 | ## Community Projects
|
150 |
|
151 | - [phosphor-react-native](https://github.com/duongdev/phosphor-react-native) ▲ Phosphor icon component library for React Native
|
152 | - [phosphor-svelte](https://github.com/haruaki07/phosphor-svelte) ▲ Phosphor icons for Svelte apps
|
153 | - [phosphor-r](https://github.com/dreamRs/phosphoricons) ▲ Phosphor icon wrapper for R documents and applications
|
154 | - [blade-phosphor-icons](https://github.com/codeat3/blade-phosphor-icons) ▲ Phosphor icons in your Laravel Blade views
|
155 |
|
156 | If you've made a port of Phosphor and you want to see it here, just open a PR [here](https://github.com/phosphor-icons/phosphor-home)!
|
157 |
|
158 | ## License
|
159 |
|
160 | MIT © [Phosphor Icons](https://github.com/phosphor-icons)
|