❤
npm
Sign UpSign In

@nice-digital/icons

6.0.1 • Public • Published

NICE Icons

Icons for use in NICE Digital Services

npm GitHub release License Dependencies Dev dependencies

Table of contents

Intro

NICE Icons is a set of SVG icons for use in NICE Digital Services using the NICE Design System. It provides source SVGs, React/TypeScript versions and an icon font.

Some background

NICE Icons is a replacement for NICE.Glyphs, which in turn was part of the old 'NICE.Bootstrap'.

Guidance

Avoid unnecessary decoration - only use icons if there's a real user need:

  • if icons are needed ensure they are clear, simple and accompanied by relevant text
  • don't hide functionality under icons
  • icons should be easily recognizable
  • keep icon designs simple and schematic.

Upgrading from 1.x to 2.9

The following are breaking changes from v1 to v2:

  • the generated SASS file is at a new path - now at /scss rather than dist/ to be consistent with other packages
  • the SASS base path variable $nice-font-base-path is now $nice-icons-base-path
  • the SASS mixin icon-base is now nice-icons-base
  • there are no nested folders within src
  • dropped speak: none CSS property
  • dropped support for usage via Bower
  • use Node 10, and npm 6.8+.

What's new in v2.0?

As well as the breaking changes listed above, we've made the following updates:

  • upgrade to Babel 7
  • upgrade other outdated packages
  • add Figma source file containing all the SVG icons
  • add React components, with ES5 transpiled version.

What's new in v2.3?

Version 2.3 is an internal refactor, mostly to use fantasticon instead of grunt-webfont for the icon font generation. This release drops support for IE8, which we no longer support but that should be the only 'breaking' change.

We have removed generation of EOT, SVG and TTF font files because we know longer support older browsers like IE8 that needed these types. We now just generate WOFF and WOFF2 which covers all modern browsers.

Installation

Install NICE Icons from npm:

npm i @nice-digital/icons --save

The node_modules/@nice-digital/icons package folder will include:

  • source SVG files in the src folder
  • React components:
    • ES5 in the lib folder (with associated d.ts files)
    • ES6 in the es folder (with associated d.ts files)
    • TypeScript in the ts folder
  • generated icon font (WOFF and WOFF 2) in the dist folder
  • generated SCSS in the scss folder
  • JSON file in the dist folder with font metadata information.

Include sass

Import NICE Icons in SASS with:

@use '@nice-digital/icons/scss/nice-icons';

Usage

There are 2 main ways to use NICE Icons in your project:

React

There are React component versions of each icon within the lib folder (transpiled to ES5) or the es folder (ES6 compatible). This allows you to easily include inline SVGs when rendering via React. Each icon file is named with PascalCase, for example src/email-closed.svg is available in React as lib/EmailClosed.js.

To use, first import the SASS file into your project as above. Then import and use React components from the lib folder, for example:

import Search from "@nice-digital/icons/lib/Search";

const something = (props) => {
	return <div>
		<Search />
	</div>;
};

The React component icons have the following default props:

  • className=icon - the associated class has a height and width of 1em to match the surrounding text
  • aria-hidden={true} as they're designed to be a visual to textual labels. In the rare case you need icons on their own without text, then pass a prop of aria-hidden={false} and make sure there's an associated aria label, title etc.

The svg path also has a default fill=currentColor to match surrounding text colour, but this can also be overridden via CSS.

Note: these React files in the lib folder are ES5 compatible. However, we also include ES6 versions in the es folder if you prefer. This means you'll need to transpile these with babel (or similar) as part of your build. For example, by using the include option pointing to node_modules/@nice-digital/icons with babel-loader in webpack.

Browser support

This method is subject to the same browser support as inline SVGs - essentially IE9+.

Webfont

We provide a custom icon web font because:

  • it's easy to render custom icons with content managed markup
  • there's no JavaScript required
  • icon color, size, shadow etc can be styled with CSS
  • any custom icons can be used
  • icon fonts support IE8+
  • vector icons are infinitely scalable
  • vector icons look perfect on retina displays.

Serving font files

Note: Add the corrrect MIME type to your web.config if you get a 404 error for .woff files in IIS.

Express

Use express.static to serve font files in Express directly from the dist folder:

const express = require("express"),
	path = require("path");

const app = express();

app.use("/fonts", express.static(path.join(__dirname, "./node_modules/@nice-digital/icons/dist")))

See the simple-express folder for a complete example of this.

Visual Studio Copy Task

Use a Visual Studio Copy Task to copy the font files into your application. Or use a post build event.

Webpack

Install Copy Webpack Plugin into your application, then at the top of your webpack config file add the following:

const CopyWebpackPlugin = require('copy-webpack-plugin');

then in the plugins section add the following:

new CopyWebpackPlugin([{ from: "node_modules/@nice-digital/icons/dist/*", to: "fonts", ignore: ["*.html"], flatten: true }]),

note that the 'to' destination is relative to the output path, which for a .NET core app would probably have been configured for wwwroot.

Markup

Use custom icons in markup (rather than SASS) wherever possible:

  • hide from screenreaders with [aria-hidden="true"]
  • use BEM style CSS classes (icon--NAME modifier)
  • prefer <span> over <i>.

Basics of usage are: <span class="icon icon--[NAME]" aria-hidden="true"></span> where name is one of the source icons e.g.:

<span class="icon icon--logo" aria-hidden="true"></span>

SASS

There are SASS constructs for advanced usage:

  • @mixin nice-icons-base for the base styles required for an icon
  • @mixin nice-icon($icon)n e.g. @include nice-icon(logo);
  • @function nice-icon($icon) e.g. content: nice-icon(logo); - gets the unicode codepoint value
  • $nice-icons - a map of icon name to unicode codepoint. Override this when generating a custom webfont in your application
  • $nice-icons-base-path - the URL from which to download the font files. Override this in your application if you serve font files from a different path.
.logo {
	&__btn {
		@include nice-icon(logo);
	}

	// or
	&__btn {
		@include nice-icons-base;

		&:before {
			content: nice-icon(logo);
			display: block;
		}
	}
}

Development

Dependencies

TL;DR:
	1. `npm i`
	2. `npm start`

To build the icon font on your local machine, first install:

Then before you can run any tasks, run the following from the command line to install dependencies npm i

Commands

Run npm start from the command line for development. This uses fantasticon under the hood to:

Updating the readme

Run the following command to update the readme:

npm run readme

This will generate the table of icons from the readme and to update the ToC.

Creating icons

We provide a [Figma file](NICE Icons.fig) with the source of all icons. Upload this into Figma and add a new Page for each icon.

Note: Figma is an online (and desktop) design and wireframing-type application. We're using it here in the context of a vector drawing tool, like Adobe Illustrator. The steps below will essentially take you through opening the existing project file with all the icons in, adding a new one in the "right" way (so it's a standard format with all of the other icons), exporting your new icon as an SVG to add to the repo, and re-saving the project file ready for the next person.

Follow the following steps to create a new SVG in Figma:

  1. Add page with the correct name eg "Address book"
  2. If you have an existing SVG, drag it into the page pane. If creating a custom SVG, ensure you have a single compound path vector.
  3. Set X and Y to 0 and 0
  4. Add a 32px layout grid to the frame
  5. Rename the frame (with the hash symbol) to "Address book frame" and the vector within it to "Address book vector"
  6. On the vector, change the constraints to Centre and Centre.
  7. On the frame change the width and height to 512px.
  8. On the vector, SHIFT+Click the corner resize tool and give it 1 square padding
  9. Centre the vector using the icons at the top of the design tool panel or use ALT+V and ALT+H when the vector is inside the frame.
  10. On the Address book page, add an export setting with type of SVG, then export the SVG changing the filename to kebab case eg "address-book.svg" and save in the src folder. (Alternatively, right-click the frame and Copy As SVG)
  11. Ensure the SVG file has the XML declaration at the top, the same as all the other SVG files in the repository.
  12. In Figma menu, File > Save as .fig and save a new copy of NICE Icons.fig, in the root of the repository.

Afterwards,

  1. Re-run npm start to rebuild the icon font and React components
  2. Re-run npm run readme to rebuild the icons in this readme file.

Icons

Icon Name Unicode HTML SCSS
android android f17b <span class="icon icon--android" aria-hidden="true"></span> @include nice-icon(android);
apple apple f179 <span class="icon icon--apple" aria-hidden="true"></span> @include nice-icon(apple);
calendar calendar e045 <span class="icon icon--calendar" aria-hidden="true"></span> @include nice-icon(calendar);
check check f00c <span class="icon icon--check" aria-hidden="true"></span> @include nice-icon(check);
chevron-down chevron-down e03c <span class="icon icon--chevron-down" aria-hidden="true"></span> @include nice-icon(chevron-down);
chevron-left chevron-left e03b <span class="icon icon--chevron-left" aria-hidden="true"></span> @include nice-icon(chevron-left);
chevron-right chevron-right e03a <span class="icon icon--chevron-right" aria-hidden="true"></span> @include nice-icon(chevron-right);
chevron-up chevron-up e039 <span class="icon icon--chevron-up" aria-hidden="true"></span> @include nice-icon(chevron-up);
comment comment f101 <span class="icon icon--comment" aria-hidden="true"></span> @include nice-icon(comment);
download download e006 <span class="icon icon--download" aria-hidden="true"></span> @include nice-icon(download);
email-closed email-closed e014 <span class="icon icon--email-closed" aria-hidden="true"></span> @include nice-icon(email-closed);
evidence evidence e017 <span class="icon icon--evidence" aria-hidden="true"></span> @include nice-icon(evidence);
facebook facebook e012 <span class="icon icon--facebook" aria-hidden="true"></span> @include nice-icon(facebook);
facebook-square facebook-square f082 <span class="icon icon--facebook-square" aria-hidden="true"></span> @include nice-icon(facebook-square);
google-plus google-plus f0d5 <span class="icon icon--google-plus" aria-hidden="true"></span> @include nice-icon(google-plus);
google-plus-square google-plus-square f0d4 <span class="icon icon--google-plus-square" aria-hidden="true"></span> @include nice-icon(google-plus-square);
guidance guidance e011 <span class="icon icon--guidance" aria-hidden="true"></span> @include nice-icon(guidance);
hamburger hamburger e03d <span class="icon icon--hamburger" aria-hidden="true"></span> @include nice-icon(hamburger);
instagram instagram f16d <span class="icon icon--instagram" aria-hidden="true"></span> @include nice-icon(instagram);
linkedin linkedin f0e1 <span class="icon icon--linkedin" aria-hidden="true"></span> @include nice-icon(linkedin);
linkedin-sign linkedin-sign f08c <span class="icon icon--linkedin-sign" aria-hidden="true"></span> @include nice-icon(linkedin-sign);
location location f102 <span class="icon icon--location" aria-hidden="true"></span> @include nice-icon(location);
logo logo e01a <span class="icon icon--logo" aria-hidden="true"></span> @include nice-icon(logo);
logo-full logo-full e01c <span class="icon icon--logo-full" aria-hidden="true"></span> @include nice-icon(logo-full);
logo-name logo-name e01b <span class="icon icon--logo-name" aria-hidden="true"></span> @include nice-icon(logo-name);
logo-portrait logo-portrait f103 <span class="icon icon--logo-portrait" aria-hidden="true"></span> @include nice-icon(logo-portrait);
minus minus e02a <span class="icon icon--minus" aria-hidden="true"></span> @include nice-icon(minus);
pathways pathways e005 <span class="icon icon--pathways" aria-hidden="true"></span> @include nice-icon(pathways);
play play e028 <span class="icon icon--play" aria-hidden="true"></span> @include nice-icon(play);
plus plus e027 <span class="icon icon--plus" aria-hidden="true"></span> @include nice-icon(plus);
podcast podcast e00b <span class="icon icon--podcast" aria-hidden="true"></span> @include nice-icon(podcast);
print print e001 <span class="icon icon--print" aria-hidden="true"></span> @include nice-icon(print);
question-circle question-circle f059 <span class="icon icon--question-circle" aria-hidden="true"></span> @include nice-icon(question-circle);
readnews readnews e009 <span class="icon icon--readnews" aria-hidden="true"></span> @include nice-icon(readnews);
remove remove e024 <span class="icon icon--remove" aria-hidden="true"></span> @include nice-icon(remove);
search search e004 <span class="icon icon--search" aria-hidden="true"></span> @include nice-icon(search);
share share e008 <span class="icon icon--share" aria-hidden="true"></span> @include nice-icon(share);
sorting sorting e021 <span class="icon icon--sorting" aria-hidden="true"></span> @include nice-icon(sorting);
sorting-asc sorting-asc e022 <span class="icon icon--sorting-asc" aria-hidden="true"></span> @include nice-icon(sorting-asc);
sorting-desc sorting-desc e023 <span class="icon icon--sorting-desc" aria-hidden="true"></span> @include nice-icon(sorting-desc);
standards standards e002 <span class="icon icon--standards" aria-hidden="true"></span> @include nice-icon(standards);
stop stop e043 <span class="icon icon--stop" aria-hidden="true"></span> @include nice-icon(stop);
syndication syndication e013 <span class="icon icon--syndication" aria-hidden="true"></span> @include nice-icon(syndication);
trash trash e020 <span class="icon icon--trash" aria-hidden="true"></span> @include nice-icon(trash);
twitter twitter e000 <span class="icon icon--twitter" aria-hidden="true"></span> @include nice-icon(twitter);
twitter-square twitter-square f081 <span class="icon icon--twitter-square" aria-hidden="true"></span> @include nice-icon(twitter-square);
user user e01f <span class="icon icon--user" aria-hidden="true"></span> @include nice-icon(user);
warning warning e04b <span class="icon icon--warning" aria-hidden="true"></span> @include nice-icon(warning);
youtube-play youtube-play f16a <span class="icon icon--youtube-play" aria-hidden="true"></span> @include nice-icon(youtube-play);
youtube-square youtube-square f166 <span class="icon icon--youtube-square" aria-hidden="true"></span> @include nice-icon(youtube-square);

License

NICE Icons distributed under the MIT license.

We use some icons from the awesome Font Awesome Free, which is licensed under the CC BY 4.0 license.

Readme

Keywords

Package Sidebar

Install

npm i @nice-digital/icons

Repository

github.com/nice-digital/nice-design-system

Homepage

design-system.nice.org.uk

Weekly Downloads

96

Version

6.0.1

License

MIT

Unpacked Size

681 kB

Total Files

310

Last publish

Collaborators

  • dalenice
  • wongcheming
  • johndavey72
  • barkertron
  • martingallagher1980
  • ditprogrammatic
  • ediblecode
  • josealmeida
  • mark-nice
  • nansenst
  • colin.mazurkiewicz
  • imranazad
  • eleanormollett
Try on RunKit
Report malware