@heroku/ember-malibu-icon
v1.8.0
Published
Ember Malibu Icons
Downloads
4,184
Maintainers
Keywords
Readme
Ember Malibu Icon
This Ember addon injects the Malibu svg sprite into your Ember application and provides a helper to insert icons into your templates. You can explore how this helper works in this addon's demo app and documentation.
Note that it will be helpful if you also use Purple 3 for styling
Installation
ember install --save @heroku/ember-malibu-icon
Configuration
By default this addon will inject the latest
version of Malibu. Consumers can configure this in their application's config/environment.js
file
ENV['ember-malibu-icon'] = {
malibuVersion: '1.3.0'
}
Ember Template Lint Rules
Ember Malibu Icon also comes with a bunch of handy Ember Template Lint rules to help remind you to declare accessibility options when possible.
To use these lint rules in your app, add the following to your .template-lintrc.js
file:
module.exports = {
extends: [
'recommended',
'@heroku/ember-malibu-icon:recommended'
],
plugins: [
require('@heroku/ember-malibu-icon/lib/ember-template-lint-plugin')
]
};
The documentation for each rule can be found in the docs/rules directory folder of this project.
Usage
From a Handlebars (.hbs) file
Accessibility
Accessibility When rendering MalibuIcon
, you must declare the icon as either:
- informational: Pass a non-empty string to
@title
argument. This will read the text to the screenreader instead of being announced as "Image". - decorative: Pass
aria-hidden="true"
to the component. This will hide the icon from assistive technology. This should only be used for icons that don't convey additional meaning and are being used for aesthetic/design reasons.
Informational Usage Example
Use this when when you want text to be announced to the screenreader. This is most common when you have icons that are used for buttons or links but lack text rendered next to the icon to describe it.
<MalibuIcon @title="Add Buildpack {{buildpackName}}" @size="28" @iconClass="gradient-dark-gray" @name="app-28" />
For example:
Given this screenshot, note the pencil icon. There is no text next to it to describe its intended purpose to the screenreader (in this case, "Edit"). @title="Edit {{domain}}"
would be an improvement in this scenario.
Decorative Usage
Use this when the icon does not convey additional meaning. There should be visual text accompanying the icon. Never use this when only the icon is rendered.
- Ember.js v3.12 or above
- Ember CLI v2.13 or above
- Node.js v10 or above
In this example, the GitHub logo is "decorative" because it does not convey additional meaning not already presented to the user via the "GitHub" text next to it.
<MalibuIcon @size="28" @iconClass="gradient-dark-gray" @name="app-28" aria-hidden="true" />
From a javascript file (not recommended/deprecated)
import { malibuIcon } from '@heroku/ember-malibu-icon/helpers/malibu-icon';
malibuIcon({
name: 'app-16',
size: 16,
iconClass: 'v-mid gradient-purple',
title='Optional Title'
})
Development
git clone https://github.com/heroku/ember-malibu-icon
cd ember-malibu-icon
yarn
Running
ember serve
- Visit your app at http://localhost:4200.
Running Tests
yarn test
(Runsember try:each
to test your addon against multiple Ember versions)ember test
ember test --server
Building
ember build
For more information on using ember-cli, visit https://ember-cli.com/.
Releases
Notes
This library does its best to follow the principles of Semantic Versioning. Every effort should be made to ensure all non-major versions are released in a backwards compatible way.
Making a New Release
Once you are ready to make a new release follow these steps:
- Create a new branch
- Update the version number in
package.json
- Commit your changes and open a PR
Publish your new version to npm with the command npm publish
🎉
Note that you must have publish access to the @heroku npm organization to successfully publish