@financial-times/o-icons

> ⚠️ **NOTE:** o-icons has been replaced with [o3-foundation](../o3-foundation/README.md). Please see [Migration Guide](MIGRATION.md#migrating-from-v7-to-o3-foundation@3) for steps to upgrade. # o-icons Helper Sass for the [fticons](https://o2-core.origami.ft.com/?path=/story/deprecated-o-icons--icons) image set. - [o-icons](#o-icons) - [Usage](#usage) - [Summary](#summary) - [Markup](#markup) - [Sass](#sass) - [Includes icons of different sizes and colors](#includes-icons-of-different-sizes-and-colors) - [Using the default CSS helper classes](#using-the-default-css-helper-classes) - [Contributing](#contributing) - [Migration](#migration) - [Contact](#contact) - [Licence](#licence) ## Usage Check out [how to include Origami components in your project](https://origami.ft.com/documentation/components/#including-origami-components-in-your-project) to get started with `o-icons`. ## Summary There are a few ways to get icons from `fticons`: 1. Use [o-icons CSS classes](#markup) 2. Use [o-icons Sass mixins](#sass) with your own CSS. 3. Request the icon directly from the [Image Service](https://www.ft.com/__origami/service/image/v2/docs/url-builder?url=fticon-v1%3Aarrow-down&preview=true) (without using o-icons at all). ## Markup To add an icon apply the `o-icons-icon` class to a `span`, along with the modifier class for your specific icon e.g. `o-icons-icon--arrow-down`. See the [storybook demos](https://o2-core.origami.ft.com/?path=/story/deprecated-o-icons--icons) for a full list of icons. ```html ``` This will include icons with a `128px` width/height by default. If you would like to use an icon at a different dimension or colour, use `o-icon` [Sass](#sass) mixins or request the icon from the [Image Service](https://www.ft.com/__origami/service/image/v2/docs/url-builder?url=fticon-v1%3Aarrow-down&preview=true) directly (without using o-icons at all). ## Sass ### Includes icons of different sizes and colors Use `oIconsContent` to output the styles for an icon of a given size and colour. The `$color` argument should be set using an [o-colors](https://o2-core.origami.ft.com/?path=/docs/deprecated-o-colors-readme--docs) Sass function such as `oColorsByName`, but may be set to any hex value. ```scss // Use o-colors so you can use colors from the Origami palette. @import "@financial-times/o-icons/main"; @import "@financial-times/o-colors/main"; // Output a 32px, claret coloured plus icon. .my-icon-plus { @include oIconsContent( $icon-name: 'plus', $color: oColorsByName('claret'), $size: 32 ); } ``` ```html ``` The `oIconsContent` mixins outputs styles used by each icon. This is inefficient if your project outputs multiple icons. In this case we recommend outputting the base styles separately with `oIconsContentBaseStyles`. ```scss // Output a 32px, claret coloured plus icon. .my-icon { @include oIconsContentBaseStyles(); } .my-icon--plus { @include oIconsContent( $icon-name: 'plus', $color: oColorsByName('claret'), $size: 32, $include-base-styles: false // do not duplicate the base styles ); } ``` ```html ``` `o-icons` includes a media query to restore either a black or white icon in Microsoft's high-contrast mode. If no icon is acceptable for users of Microsoft's high-contrast mode this may be disabled to reduce bundle size: ```scss .no-high-contrast-window { @include oIconsContent( $icon-name: 'plus', $color: oColorsByName('claret'), $high-contrast-fallback: false ); } ``` ### Using the default CSS helper classes To output all icon [helper classes](#markup) include the `oIcons` mixin. ```scss @import "@financial-times/o-icons/main"; @include oIcons(); // include helper classes for all icons ``` To avoid including all icon [helper classes](#markup), `oIcons` mixin also accepts a list of icons to include: ```scss @include oIcons($opts: ( 'icons': ('arrow-down', 'audio') // include helper classes for the arrow-down and audio icons )); ``` ## Contributing `o-icons` is some Sass mixins and helpers for using the fticons image set. To add a new icon you need to add it to the fticons set. There are instructions in the [origami-image-service README](https://github.com/Financial-Times/origami-image-service#adding-images). When the icon is in fticons, run `node ./scripts/build-icon-list.js NAME_OF_THE_NEW_ICON` to update `o-icons` Sass with the new icon automatically. If you need to remove an icon from `o-icons` you run `node ./scripts/build-icon-list.js NAME_OF_THE_NEW_ICON remove`. ## Migration State | Major Version | Last Minor Release | Migration guide | :---: |:-------------:| :---: |:----------------------------------------------------------------: ✨ active | o3 | N/A | [migrate to o3](MIGRATION.md#migrating-from-v7-to-o3-foundation@3) | ╳ deprecated | 7 | N/A | [migrate to v6](MIGRATION.md#migrating-from-v6-to-v7) | ╳ deprecated | 6 | 6.3 | [migrate to v6](MIGRATION.md#migrating-from-v5-to-v6) | ╳ deprecated | 5 | 5.9 | [migrate to v5](MIGRATION.md#migrating-from-v4-to-v5) | ╳ deprecated | 4 | 4.5 | [migrate to v4](MIGRATION.md#migrating-from-v3-to-v4) | ╳ deprecated | 3 | 3.3 | - | ╳ deprecated | 2 | 2.4 | - | ╳ deprecated | 1 | 1.2 | - | ## Contact If you have any questions or comments about this component, or need help using it, please either [raise an issue](https://github.com/Financial-Times/o-icons/issues), visit [#origami-support](https://financialtimes.slack.com/messages/origami-support/) or email [Origami Support](mailto:origami-support@ft.com). *** ## Licence This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).