1.0.1 • Published 8 years ago

bare-select v1.0.1

Weekly downloads
13
License
MIT
Repository
github
Last release
8 years ago

Coveralls – test coverage
Travis – build status
David – status of dependencies
Code style: airbnb

<bare-select>

The lean alternative to <select>.

  • Dead easy to style. That’s the whole point.
  • Great keyboard navigation.
  • Drop-in usage. As easy as <bare-select></bare-select>.
  • Pretty without JavaScript. Usable without CSS.
  • FIRST. Hackable from head to toe.

Using a bundler?

If you’re not using webpack or the like, skip to the next section.

$ npm install bare-select

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

require('bare-select')();

Using <script> tags?

Download the latest version from https://registry.npmjs.org/bare-select/-/bare-select-0.1.0.tgz. Unpack the file package/dist/bare-select.drop-in.min.js. Then add this to your <head>:

<script src="path/to/bare-select.drop-in.min.js"></script>

You’re all set!

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>

That’s it!

To get a feeling of how it works, try taking the unfolded attribute off your <bare-select>. Try setting value="2" on it.

Configuring

 

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

 

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

 

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|default: {}|optional

  • 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

 

Great keyboard navigation.

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

Parameters:

None.

Return value:

  • keyboardNavigationPlugin
    type: pluginMaker

 

Great mouse navigation.

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

Parameters:

None.

Return value:

  • mouseNavigationPlugin
    type: pluginMaker

 

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

 

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

 

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