ractive-ez-combobox/readme.md

Ractive Ez UI Combobox

# Ractive Ez ComboBox

ComboBox component for ractive.js

[Demo](https://bartvanbeurden.github.io/ractive-ez-demo/)

## Install

    npm i ractive-ez-combobox

```js
import 'ractive-ez-combobox';
import 'ractive-ez-combobox/themes/blue.less';
```

## Usage

Both combobox and multibox support following properties:

- `items`: List of items to choose from
- `placeholder`: Placeholder text if no value is selected
- `disabled`: True if input is disabled
- `required`: True if input is required
- `button`: If true, renders a button that shows all items when clicked
- `typeahead`: True if the input text is automatically suffixed with the full text of the current option. This option should only be used with a prefix `filter` function, and not combined with `searchOnInput`.
- `path`: The item keypath to filter on
- `compare`: Function(item1, item2) that returns true if the two items are equal. This is used to determine if an item is selected.
- `filter`: Function(text, value) that returns true if the value matches the filter text. The value that is passed to this function is the value of the property at `path` (e.g. if path = "code" then this component will call `filter(text, item.code)`). This function defaults to a prefix filter (that matches at the start of the string).
- `search`: If the items are not known at initialization, you can provide a search function to populate the items asynchronously. `function(text, callback) => callback(error, items)`.
- `searchOnInput`: Automatically refresh your items when the user inputs new text (for full asynchronous search).
- `searchDelay`: When `searchOnInput` is enabled, this value defines the time (in ms) to wait before searching after detecting a keystroke.

The content of the component is the view template of an option.

### ComboBox

The combobox selects a single value.

```html
<EzComboBox
    value="{{ value }}"
    items="{{ countries }}"
    path="code">

    <b>{{ code }}</b> - {{ name }}
</EzComboBox>
```

#### Properties

- `value`: The item that is currently selected

#### Events

- `change(value)`: Dispatched when the value is changed

### MultiBox

The multibox selects a list of values.

```html
<EzMultiBox
    values="{{ values }}"
    items="{{ countries }}"
    path="code">

    {{ code }} ({{ name }})
</EzMultiBox>
```

#### Properties

- `values`: An array of selected values

#### Events

- `change(values)`: Dispatched when the array of selected values changes
- `add(value)`: Dispatched when a value is added to the list of selected values
- `remove(value)`: Dispatched when a value is removed from the list of selected values