| 1 | # React{ions}
|
| 2 |
|
| 3 | [](https://circleci.com/gh/GetAmbassador/react-ions)
|
| 4 |
|
| 5 | **React{ions}** is a suite of React components that implement Ambassador's Design and UX patterns. They are designed to be re-usable and composable across large-scale web applications.
|
| 6 |
|
| 7 | Check out our [documentation site](http://reactions.getambassador.com/) for live examples.
|
| 8 |
|
| 9 | ## Installation
|
| 10 | Ambassador's React{ions} is available as an [npm package](https://npmjs.com/react-ions).
|
| 11 |
|
| 12 | `$ npm install react-ions`
|
| 13 |
|
| 14 | ## Prerequisites
|
| 15 |
|
| 16 | React{ions} currently requires React 15.1+.
|
| 17 |
|
| 18 | We use CSS Modules by default to import stylesheets written in SASS. In case you want to import the components already bundled with CSS, your module bundler should be able to require these SASS modules.
|
| 19 |
|
| 20 | ## Example Webpack App
|
| 21 | Here is an example [React{ions} Webpack app](https://github.com/GetAmbassador/reactions-webpack-example) to get you started.
|
| 22 |
|
| 23 | ## Basic Usage
|
| 24 | In this minimal example, we import a Button with styles already bundled:
|
| 25 |
|
| 26 | import React from 'react'
|
| 27 | import Button from 'react-ions/lib/Button'
|
| 28 |
|
| 29 | <Button>I am a Button</Button>
|
| 30 |
|
| 31 | Live examples and more info [documentation site](http://reactions.getambassador.com/components).
|
| 32 |
|
| 33 | Icons
|
| 34 | -----
|
| 35 | To limit the number of network requests, this library dynamically generates an `.svg` sprite, to handle our user interfaces. The list of available icons is here: http://reactions.getambassador.com/foundations/iconography.
|
| 36 |
|
| 37 | The list is primarily made up of [Material Icons](https://material.io/icons/). However, there are a few social icons that we have added on our own.
|
| 38 |
|
| 39 | If you've cloned the React:ions library, and wish to add/remove Material icons, or add custom (eg: non-Material) icons, to the sprite, follow the directions below.
|
| 40 |
|
| 41 | ### To add a Material Icon to the svg sprite:
|
| 42 | - Search for the icon on the [Material Icon](https://material.io/icons/) site.
|
| 43 | - Open the master list `/react-ions/src/assets/icons/master-list.js`, and add the icon to the `material` array.
|
| 44 | - The *category* of the icon is needed to construct the path.
|
| 45 | - The *hash* after the path will be the `name` prop as passed into the React:ions `Icon` component.
|
| 46 | - All Material icon names should be prefixed with `md-`.
|
| 47 | - Stop the app, and run `npm run build:sprite`.
|
| 48 | - Run the app again, and go to: http://localhost:3000/foundations/iconography.
|
| 49 | - Your icon will be visible in the list.
|
| 50 |
|
| 51 | ### To make a Custom Icon available in our apps:
|
| 52 | - Follow the instructions for adding a `Material` app, however instead you will add to the `mbsy` array, and include a raw `.svg` file here: `/react-ions/src/assets/icons/svg`.
|
| 53 |
|
| 54 | ## License
|
| 55 | This project is licensed under the terms of the [MIT license](LICENSE)
|