ember-toggle

ember-toggle

Checkbox based Toggle Switch component with swipe/drag support for Ember.

Based on this codepen. Here's the official demo using this component.

Install

ember install ember-toggle

Basic Usage

{{x-toggle value=myValue onToggle=(action (mut myValue))}}

Themes

There are many themes which change the visual appearance of the toggle. Check the demo for interactive examples.

• 'default'
• 'ios'
• 'light'
• 'flat'
• 'flip'
• 'skewed'

Example of changing the theme

{{x-toggle value=toggled theme='ios' onToggle=(action (mut toggled))}}

Note: By default only the default theme is included, see the Configuration section to import other themes.

Size

You can also adjust the size of the widget by use of the size property. Valid sizes are:

• 'small'
• 'medium'
• 'large'

This option is available on all themes but is a less sensible choice for those themes which actually include the label within the control (e.g., skew and flip).

Labels

You can set both labels (what is displayed to the user) and the values associated with this label:

{{x-toggle
  value=myValue
  showLabels=true
  onLabel='Enabled'
  offLabel='Disabled'
  onToggle=(action (mut myValue))
}}

If you want your labels to be display, then you must set showLabels to true.

Available Options

• theme - One of 'light', 'ios', 'flat', 'flip', 'skewed', 'default'. Defaults to 'default' if not specified.
• size - One of 'small', 'medium', 'large'. Defaults to 'medium' if not specified.
• onLabel - The label for the on state. Defaults to 'On'.
• offLabel - The label for the off state. Defaults to 'Off'.
• showLabels - Defaults to 'false', if 'true' will display labels on left and ride side of toggle switch
• disabled - Defaults to false, which means you can click the toggle. When true, an .x-toggle-disabled class is set on the toggle and an .x-toggle-container-disabled class is set on the component.
• name - A name to differentiate multiple toggles, gets passed to the toggle action. Defaults to 'default'.

Configuring

Add a configuration for ember-toggle to include only the themes that you will use.

ENV['ember-toggle'] = {
  includedThemes: ['light', 'default', 'flip'],
  excludedThemes: ['flip'],
  excludeBaseStyles: false, // defaults to false
  defaultShowLabels: true,  // defaults to false
  defaultTheme: 'light',    // defaults to 'default'
  defaultSize: 'small',     // defaults to 'medium'
  defaultOffLabel: 'False', // defaults to 'Off'
  defaultOnLabel: 'True'    // defaults to 'On'
};

note: the IOS theme is referred to as just ios not ios7 as was indicated in the originating CSS source

To exclude or not include a theme, means that it's css styles will not be bundled with your application, thus not polluting your app.

Note: including a blank array e.g. includeThemes: [] will not include any themes, leaving you to define your own theme styles. See the vendor/ember-toggle/themes directory for reference. Note: you may also want to set excludeBaseStyles: true so that this addon doesn't include the styles used by all the themes.

Advanced Usage

If you need custom labels, or additional markup, or non-standard behavior, you are in the right section.

The x-toggle component also provides a composable component API.

{{#x-toggle value=value showLabels=true onToggle=(action (mut value)) as |toggle|}}
  {{toggle.offLabel}}
  {{toggle.switch}}
  {{toggle.onLabel}}
{{/x-toggle}}

The above is a simple example that returns a basic toggle, but you can see how this could be used to wrap the switch or the labels in custom markup or logic.

Single Label

This format allows greater flexibility with labels, like the single label use-case.

{{#x-toggle value=value showLabels=true onToggle=(action (mut value)) as |toggle|}}
  {{#toggle.label value=(not value)}}
    <b>turn {{if value 'off' 'on'}}</b>
  {{/toggle.label}}

  {{toggle.switch theme='flip' onLabel='diff on' offLabel='diff off'}}
{{/x-toggle}}

Note: The not helper is a custom Ember helper in the above example.

Contributing

See CONTRIBUTING.md for details.

Changelog

5.1.2 (2017-09-19)

Bug Fixes

• x-toggle toggles on click when the onToggle action does not update the value (#92) (bb46c74), closes #91 #91

<a name="5.1.1"></a>