bare-select

       

<bare-select>

The lean alternative to <select>.

• Dead easy to style. Just match it to your design.
• Pretty and usable without JavaScript. Usable even without CSS.
• Mimicks the native <select>. Keyboard navigation included.
• Event-driven and plugin-based. Hackable from head to toe.

Installation

$ npm install [e-mail]:js/lib/bare-select
$ cd node_modules/bare-select
$ npm install
$ npm run prepublish

Once we’ve published to http://npmjs.org, it’ll be a lot easier:

$ npm install bare-select

Usage

You’ll likely be fine with the default settings. Just execute this to register the <bare-select>:

require('bare-select')();

Then prepare your markup:

<bare-select>             <!-- • The custom element.                         -->
  <label></label>         <!-- • A `<label>` for the switch. A click on this -->
                          <!--   element will unfold the dropdown.           -->
                          <!-- • The caption of the select box. It’s the     -->
                          <!--   same element as the label unless you        -->
                          <!--   configure it otherwise.                     -->
  <input type=checkbox>   <!-- • The switch. Controls the visibility of the  -->
                          <!--   dropdown.                                   -->
  <ul>                    <!-- • The dropdown. Folds and unfolds.            -->
    <li>                  <!-- • An option. You can have zero or more.       -->
      <input type=radio>  <!-- • The option’s radio. Its `value` is the      -->
                          <!--   value of the option. When it’s checked, the -->
                          <!--   option is selected.                         -->
      <label></label>     <!-- • The content of the option. What the user    -->
    </li>                 <!--   sees.                                       -->
  </ul>
</bare-select>

Looks complicated? How about an example:

<bare-select unfolded>
  <label>Pick a number</label>
  <input type="checkbox" />
  <ul>
    <li><input type="radio" value="1" /><label>
      One
    </label></li>
    <li><input type="radio" value="2" /><label>
      Two
    </label></li>
    <li><input type="radio" value="3" /><label>
      Three
    </label></li>
  </ul>
</bare-select>

Now try taking the unfolded off your <bare-select>. Try setting value="2" on it.

Configuring

 

bareSelect([{[view], [model], [plugins], [logger]}])
  → HTMLBareSelectElement

Register the element.

This function should only be called once.

Importing: var bareSelect = require('bare-select')

Parameters:

• options
  ^{type: Object | default: {} | optional}

• options.view
  ^{type: viewMaker | default: require('bare-select/module/view')() | optional}

• options.model
  ^{type: modelMaker | default: require('bare-select/module/model')() | optional}

• options.plugins
  ^{type: pluginMaker[] | default: [require('bare-select/module/plugins/keyboardNavigation')(), require('bare-select/module/plugins/mouseNavigation')(), require('bare-select/module/plugins/unfolded')(), require('bare-select/module/plugins/updateCaption')(), require('bare-select/module/plugins/value')()] | optional}
  Default plugins. They’ll be registered on any newly created

• options.logger
  ^{type: logger | default: console | optional}
  A custom logger. Make sure logger.info and logger.warn are functions.

Return value:

• HTMLBareSelectElement
  ^{type: HTMLBareSelectElement}

 

model()
  → customElementModel

A model based on a custom element.

The state of the model is stored as attributes on a custom element. Changing an attribute will update the model, and patching the model’s state will update the attribute.

Importing: var model = require('bare-select/model')

Parameters:

None.

Return value:

• customElementModel
  ^{type: modelMaker}

 

view([{[selectors]}])
  → pureView

A pure HTML+CSS view.

Have a look at <../Readme.md> to see an example of the markup.

Importing: var view = require('bare-select/view')

Parameters:

• options
  ^{type: Object | required}

• options.selectors
  ^{type: Object | default: {} | optional}

• options.selectors.caption
  ^{type: String | default: 'bare-select > label' | optional}

• options.selectors.selectLabel
  ^{type: String | default: 'bare-select > label' | optional}

• options.selectors.switch
  ^{type: String | default: 'bare-select > input[type=checkbox]' | optional}

• options.selectors.dropdown
  ^{type: String | default: 'bare-select > ul' | optional}

• options.selectors.option
  ^{type: String | default: 'bare-select > ul > li' | optional}

• options.selectors.optionRadio
  ^{type: String | default: 'input[type=radio]' | optional}

• options.selectors.optionLabel
  ^{type: String | default: 'label' | optional}

Return value:

• pureView
  ^{type: viewMaker}

 

keyboardNavigation()
  → keyboardNavigationPlugin

Great keyboard navigation.

Importing: var keyboardNavigation = require('bare-select/plugins/keyboardNavigation')

Parameters:

None.

Return value:

• keyboardNavigationPlugin
  ^{type: pluginMaker}

 

mouseNavigation()
  → mouseNavigationPlugin

Great mouse navigation.

Importing: var mouseNavigation = require('bare-select/plugins/mouseNavigation')

Parameters:

None.

Return value:

• mouseNavigationPlugin
  ^{type: pluginMaker}

 

unfolded()
  → unfoldedPlugin

Adds support for the attribute unfolded. Adding the attribute to the <bare-select> will unfold the select – and removing the attribute will fold it.

Importing: var unfolded = require('bare-select/plugins/unfolded')

Parameters:

None.

Return value:

• unfoldedPlugin
  ^{type: pluginMaker}

 

updateCaption()
  → updateCaptionPlugin

Updates content displayed in the caption to match the selected option.

Importing: var updateCaption = require('bare-select/plugins/updateCaption')

Parameters:

None.

Return value:

• updateCaptionPlugin
  ^{type: pluginMaker}

 

value()
  → valuePlugin

Adds support for the attribute value. Changing the selection will update the attribute value within the <bare-select>. Changing the attribute will update the selection.

Importing: var value = require('bare-select/plugins/value')

Parameters:

None.

Return value:

• valuePlugin
  ^{type: pluginMaker}

Hacking

Our event-driven design means that every feature is a plugin. Plugins are the glue between the view and model.

You can easily add, remove, fork and modify plugins to suit them to your needs. You can even replace the view and the model with your own custom implementations.

Work in progress…

License

MIT © Studio B12 GmbH