An Ember addon for Shopify's Polaris design system
ember-polaris
is an ember-cli
addon to make Shopify's Polaris design system accessible to Ember developers.
NOTE: this addon is still in development. As such, not all of the components available in the React component library have been built yet, and some features of those which have been built are currently unimplemented. Check the component list for a list of those which are currently available.
Install ember-polaris
using ember-cli
:
$ ember install @smile-io/ember-polaris
This addon will install ember-cli-sass in the host app. It will also set up your app's app/styles/app.scss
to @import "ember-polaris";
, creating the file if it does not already exist.
For icons to work you will need to:
public
, ex: public/assets/images/svg/polaris
ember-svg-jar
ember-svg-jar
options to your ember-cli-build.js
:// ember-cli-build.js
var app = new EmberApp(defaults, {
...
svgJar: {
strategy: 'inline',
inline: {
stripPath: false,
optimizer: {
removeDimensions: true,
},
sourceDirs: [
'public/assets/images/svg',
],
}
},
...
});
If your app does not already import ember-template-compiler
, you may get an error similar to this one when passing a hash of componentName
and props
into one of the ember-polaris
components:
Uncaught TypeError: _ember.default.HTMLBars.compile is not a function
If that happens, you need to add an import statement to its ember-cli-build.js
.
// ember-cli-build.js
app.import('node_modules/ember-source/dist/ember-template-compiler.js');
NOTE: This setup will be handled by ember-polaris
in the future.
ember-polaris
provides a set of Ember components intended to implement the same behavior and functionality as the Shopify Polaris React components. In general the usage can be inferred from the Polaris component documentation, with some exceptions as described below.
We have tried to keep the components provided by ember-polaris
as similar to the original Polaris React components as possible. However, there are cases where it makes sense to do things in a more Ember-friendly way, and where this is true we will describe the ember-polaris
usage and how it differs from the original Shopify components.
children
propertyA large number of the Polaris React components have a children
property listed in their documentation. In these cases, the corresponding ember-polaris
component can be given a text
attribute which will take the place of the children
property and specify the text to be rendered by the component. Alternatively these components can be used in block form to achieve the same result. Note that the block content will take precedence over the text
attribute (if one is supplied):
{{polaris-button text="Attribute text"}}
=> renders a button with the content "Attribute text"
{{#polaris-button}}
Block text
{{/polaris-button}}
=> renders a button with the content "Block text"
{{#polaris-button text="Attribute text"}}
Block text
{{/polaris-button}}
=> renders a button with the content "Block text"
element
propertySome Polaris React components accept an element
property which changes the tag rendered by the component. In ember-polaris
, this is replaced by the tagName
attribute unless otherwise noted. This attribute cannot be dynamic - the following code would cause an error:
{{#polaris-display-text tagName=displayTextTagName}}
Displays fine to start with...
{{/polaris-display-text}}
{{#polaris-button onClick=(action (mut displayTextTagName) "h5")}}
... but clicking this button will cause an error
{{/polaris-button}}
actions
propertySome Polaris React components accept an actions
property as a list of actions which can be performed. In ember-polaris
, this is renamed to avoid collisions with the Ember actions
hash. The new name will be different based on the component - check the documentation for the specific component to find out what attribute to pass the actions list as.
Below is a categorised list of the components available in ember-polaris
. Click an item to see more information and usage examples for that component.
See the Contributing guide for details.
ember-polaris
has an automated changelog generator when preparing releases.
Run yarn changelog-generator
to generate changelog for the current branch.
This project is licensed under the MIT License.