@leiops/icon

Simple SVG icons for use in React apps. Fully customizeable and configurable, with an excellent API.

Simple Usage

import React from 'react'
import Icon from '@leiops/icon'

const ConfirmButton = props => (
  <button className="confirm" onClick={props.onClick}>
    Confirm <Icon.Checkmark />
  </button>
)

Component API

The library will blindly pass props down to the svg element it renders, with two exceptions:

• Any className you pass will be appended to the base class (icon by default) and the icon class (e.g. chevron-left).
• The title prop will be separated out and placed within the SVG, providing the expected hover-over behavior in most browsers.

DEV - we're working on that. Not quite there yet ^

  <Icon.Checkmark
    onClick={this.handleClick}
    className={isDisabled ? '' : 'disabled'}
    title="Submit form."
  />

Custom Configuration

The library provides an adapter function which allows you to augment and customize our icons.

We keep a libraries directory for external code which we've altered slightly to fit our needs. This is the perfect place for our configuration file. The directory structure looks something like this:

libraries/
  ...
  icon/
    adapter.js
    styles.scss
  ...

You could also place this directly within a components directory and treat it like internal code.

adapter.js takes advantage of several of the features explained in the following sections, so we won't go into that now.

import { adapter } from '../../node_modules/@leiops/icon'

export default adapter({
    ...
})

We also keep a stylesheet with our preferred default styles right beside the adapter:

@import 'styles/variables';

.icon {
    height: $m-size;
    width: $m-size;
}

We then provide an alias in our webpack configuration:

  ...
  resolve: {
    ...
    alias: {
      'icon': './libraries/icon/adapter',
      ...
    },
    ...
  }
  ...

Which makes it easy for us to use our configured icons library anywhere just like this:

import Icon from 'icon'
...

Configuration: Base Class

By default, icons will be rendered with the base class icon, followed by their component name in kebab-case (i.e. ChevronLeft becomes chevron-left). If icon is too broad for your project, you can change it in the adapter.

import { adapter } from '@leiops/icon'

export default adapter({
  ...
  baseClass: 'leiops-icon',
  ...
})

Configuration: Alias

Users can provide alternative names for any of the icons in the library. The aliased icons will get their className from the alias.

import { adapter } from '@leiops/icon'

export default adapter({
  ...
  alias: {
    'Confirm': 'Checkmark'
  },
  ...
})

Now, we could write something like this:

import React from 'react'
import Icon from 'icon'

const ConfirmButton = props => (
  <button className="confirm" onClick={props.onClick}>
    Confirm <Icon.Confirm />
  </button>
)

Configuration: Inject

Users can provide their own icons to the library.

Icons must be SVG files, and must be processed by the loader provided by this library, as well as babel. To get started, you'll want to run yarn add --dev @leiops/icon-loader, then provide the following in your Webpack configuration:

...
module: {
  ...
  rules: [
    ...
    {
      test: /libraries\/icon\/.+\.svg$/,
      loaders: [
        'babel-loader',
        '@leiops/icon-loader',
      ],
    },
    ...
  ],
  ...
},
...

You can also invoke the loader on a case-by-case basis:

import CustomIcon from 'babel-loader!@leiops/icon-loader!./label-icon.svg'

If they have the same name as an existing icon, it will be overwritten. In order for the svg to be readable by our library, you will have to have raw-loader set up to load svg files in your webpack config.

import { adapter } from '@leiops/icon'
import LabelIcon from './label-icon.svg'

export default adapter({
  ...
  inject: {
    'Label': LabelIcon
  },
  ...
})

While we can accept any valid svg, we reccomend that you use the following as a template. Importantly, our icons are all designed at 24 x 24. Adhering to this constraint will help to blend your icons more cleanly with ours.

<?xml version="1.0" encoding="utf-8"?>
<svg 
  version="1.1" 
  xmlns="http://www.w3.org/2000/svg" 
  xmlns:xlink="http://www.w3.org/1999/xlink" 
  x="0px" 
  y="0px" 
  width="24px"
  height="24px" 
  viewBox="0 0 24 24" 
  enable-background="new 0 0 24 24" 
  xml:space="preserve"
>
  <!-- your artwork here -->
  <path fill="none" d="M0,0h24v24H0V0z"/>
</svg>