Methods reference

Here is some methods to manipulate your Celesta instances directly (that is, without any user actions).

Examples below assume you have Celesta instance created and named c (why not c?):

var c = new Celesta(document.getElementById('my_select'));

Most methods examples below will use this c variable to demonstrate some usage case.

c.someCoolMethod();

And only static methods examples (there are few) will use Celesta.prototype instead.

Arguments: {object} config_overrides

Static method to override default options (config params) for all newly created Celesta instances. Accepts an object of option names and values, like the following.

Celesta.prototype.setConfigDefaults({
    space_key_open: false,
    options_nav_cycling: true,
    closed_options_pagekey_jump_by: 5
})

Arguments: {string} param_name

Returns: {*}

Get the value for config param (option) specified.

c.getConfigParam('enter_key_open'); // => true
c.getConfigParam('typed_life'); // => 1000

var x = new Celesta(document.querySelector('.another-select', { typed_life: 1500 });
x.getConfigParam('typed_life'); // => 1500

Returns: {boolean}

Returns true if current instance is successfully initialized, false otherwise.

c.isInitialized(); // => true

Arguments: {string} event_name, {function} handler

Attaches a callback that will be fired on certain event. For more information on events and callback arguments, see Events reference.

c.addEventListener('open', function () {
    console.log('bang!');
});
c.open(); // 'bang!'

c.addEventListener('change', function (new_value, old_value, new_text, old_text, new_index, old_index) {
    console.log("Changed to option '" + new_value + "' which has text '" + new_text + "' and index '" + new_index + "'."); 
});
c.selectOption(2); // "Changed to option 'second' which has text 'The second option' and index '2'."
c.selectOption(3); // "Changed to option 'third' which has text 'The third option' and index '3'."
c.selectOption(3); // (nothing happens, because selected option wasn't changed)

Turns Celesta to open state (as if it was mouse-clicked).

c.open(); // (now you can see it opened)

Turns Celesta to closed state (as if Esc was pressed).

c.close(); // (now you can see it closed)

Turns Celesta to closed state (as if Esc was pressed).

c.toggle(); // (now you can see it opened)

c.toggle(); // (now you can see it closed again)

Returns: {boolean}

Returns true if Celesta is currently in open state, false otherwise.

c.open();
c.isOpen(); // => true

c.close();
c.isOpen(); // => false

c.toggle();
c.isOpen(); // => true

c.toggle();
c.isOpen(); // => false

Arguments: {boolean} value

Set or unsets disabled state for Celesta instance. Accepts boolean value (true to disable, false to enable).

c.setDisabled(true); // (now you can see it disabled)

c.setDisabled(false); // (now you can see it enabled again)

A shortcut for setDisabled(true).

c.disable(); // (now you can see it disabled)

A shortcut for setDisabled(false).

c.enable(); // (now you can see it enabled)

Returns: {boolean}

Returns true if Celesta is currently in open state, false otherwise.

c.isDisabled(); // => false

c.disable();
c.isDisabled(); // => true

c.enable();
c.isDisabled(); // => false

Arguments: {number} index, {boolean=false} force

Selects an option by index.

c.selectOption(2); // (option with index 2 is now selected)

Arguments: {number} index

Pre-selects an option by index. That imitates the behavior of displaying the text for keyboard-focused option in selectbox facade without selecting it.

Pre-selected option only becomes selected only after selectbox (or Celesta) is closed (even by pressing Esc).

Only works on open Celesta instance.

// assuming we have closed Celesta with option values like 'first', 'second' etc., and 'first' is now selected

c.getValue(); // => 'first'

c.preselectOption(2); // (nothing happens, because Celesta is closed)

c.getPreselectedOptionIndex(); // => undefined

c.getValue(); // => 'first'

c.open();
c.preselectOption(2); // (option with index 2 is now pre-selected)

c.getPreselectedOptionIndex(); // => 2

c.getValue(); // => 'first' (pre-selected doesn't mean selected!)

c.close();
c.getPreselectedOptionIndex(); // => undefined (pre-selected option doesn't exist on closed Celesta)

c.getValue(); // => 'second' (instead, it became really selected!)

Arguments: {number} index, {boolean=false} is_mouse, {boolean=false} force

Hovers (focuses) an option by index.

Accepts optional second param is_mouse, default false (which means “keyboard”). By default, keyboard-focused items are also pre-selected, but mouse-hovered aren’t (that depends on keyboard_hover_preselect and mouse_hover_preselect config params).

Only works on open Celesta instance.

// assuming we have closed Celesta with option values like 'first', 'second' etc., and 'first' is now selected

c.getValue(); // => 'first'

c.hoverOption(2); // (nothing happens, because Celesta is closed)

c.open();
c.hoverOption(2); // (option with index 2 is now focused "by keyboard")

c.getPreselectedOptionIndex(); // => 2 (by default, keyboard-focused item is also pre-selected)

c.hoverOption(3, true); // (option with index 3 is now hovered "by mouse")

c.getPreselectedOptionIndex(); // => 2 (still 2, because by default, mouse-hovered item isn't pre-selected)

c.hoverOption(3, false); // (option with index 3 is now hovered "by keyboard"; actually, that false value isn't needed)

c.getPreselectedOptionIndex(); // => 3 (finally, now it is 3)

Arguments: {number} index

Acts as hoverOption on open Celesta, and as selectOption on closed one.

c.open();
c.jumpToOption(2); // (option with index 2 is now hovered)

c.close();
c.jumpToOption(4); // (option with index 4 is now selected)

Returns: {string}

Returns the value of currently selected option.

// assuming you have <option value="second">The second option</option>

c.getSelectedOptionValue(); // => 'second'

Returns: {string}

An alias for getSelectedOptionValue.

// assuming we have <option value="second">The second option</option>

c.getValue(); // => 'second'

Returns: {string}

Returns the text of currently selected option.

// assuming we have <option value="second">The second option</option>

c.getValue(); // => 'The second option'

Returns: {number}

Returns the index of currently selected option.

// assuming we have Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected

c.getSelectedOptionIndex(); // => 0

c.getValue(); // => 'zero'

c.selectOption(2);
c.getSelectedOptionIndex(); // => 2

c.getValue(); // => 'second'

Returns: {number|undefined}

Returns the index of currently pre-selected option (undefined if none).

// assuming we have closed Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected

c.open();
c.getPreselectedOptionIndex(); // => undefined (nothing was pre-selected by now)

c.preselectOption(2);
c.getSelectedOptionIndex(); // => 2

c.close();
c.getSelectedOptionIndex(); // => undefined (Celesta is closed, no pre-selected option exists)

Returns: {number|undefined}

Returns the index of currently hovered (focused) option (undefined if none).

// assuming we have closed Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected

c.getHoveredOptionIndex(); // => undefined (Celesta is closed, no hovered option exists)

c.open();
c.getHoveredOptionIndex(); // => 0 (on open, selected option is focused automatically)

c.hoverOption(2);
c.getHoveredOptionIndex(); // => 2

c.close();
c.getHoveredOptionIndex(); // => undefined (because Celesta is closed)

Act as if ArrowUp (↑) key is pressed (selects/hovers previous available option).

// assuming you have months option list with September currently selected

c.getValue(); // => 'september'

c.arrowUp();
c.getValue(); // => 'august'

Act as if ArrowDown (↓) key is pressed (selects/hovers next available option).

// assuming you have months option list with September currently selected

c.getValue(); // => 'september'

c.arrowDown();
c.getValue(); // => 'october'


// now, assuming you have weekdays list with Wednesday currently selected, and (for some reason) Thursday disabled

c.getValue(); // => 'wednesday'

c.arrowDown(); // (goes down, skips disabled option, so actually goes down once more)

c.getValue(); // => 'friday'

Acts as if PageUp key is pressed (skips several options up). The jump size differs depending on open state, and relies on values for options closed_options_pagekey_jump_by and open_options_pagekey_jump_by.

// assuming that Celesta is currently closed, and jumps by 3 items by default

// also assuming it contains a list of months with September currently selected

c.getValue(); // => 'september'

c.pageUp(); (skips 3 items up)
c.getValue(); // => 'june'

Acts as if PageDown key is pressed (skips several options down). The jump size differs depending on open state, and relies on values for options closed_options_pagekey_jump_by and open_options_pagekey_jump_by.

// assuming that Celesta is currently closed, and jumps by 3 items by default

// also assuming it contains a list of months with September currently selected

c.getValue(); // => 'september'

c.pageDown(); (skips 3 items down)
c.getValue(); // => 'december'

Arguments: {string} new_char

Appends a character to the end quicksearch text (as if it was typed from the keyboard, to find some option).

// assuming you have an option list that contains weekdays

c.appendTyped('t'); // (quicksearch text is now: 't', 'Tuesday' becomes selected)

c.appendTyped('h'); // (quicksearch text is now: 'th', 'Thursday' becomes selected)

c.appendTyped('w'); // (quicksearch text is now: 'thw', 'Thursday' is still selected because there is no matching item)

Clears quicksearch text previously (as if Backspace was pressed while typing).

// assuming you have an option list that contains weekdays

c.appendTyped('t'); // (quicksearch text is now: 't', 'Tuesday' becomes selected)

c.appendTyped('h'); // (quicksearch text is now: 'th', 'Thursday' becomes selected)

c.appendTyped('w'); // (quicksearch text is now: 'thw', 'Thursday' is still selected because there is no matching item)

c.clearTyped(); // (quicksearch text is now empty)

c.appendTyped('w'); // (quicksearch text is now: 'w', 'Wednesday' becomes selected)

Returns: {HTMLSelectElement}

Returns DOM element for source <select>.

c.getSourceSelect(); // => HTMLSelectElement: <select id="my_select">...</select>

Returns: {HTMLElement}

Returns DOM element for Celesta overall container. May be used to attach some click events etc.

c.getContainer(); // => HTMLSpanElement: <span class="celesta-container">...</span>

Returns: {HTMLElement}

Returns DOM element for Celesta facade (a block to display currently selected option). May be used to attach some click events etc.

c.getFacade(); // => HTMLSpanElement: <span class="celesta-facade">...</span>

Returns: {HTMLElement}

Returns DOM element for Celesta options list container. May be used to attach some custom scroll library.

c.getFacade(); // => HTMLSpanElement: <span class="celesta-facade">...</span>

Rebuilds Celesta DOM structure, based on source <select> structure. To be called after external change of source <select>.

Assuming we have the following HTML markup:

<select id="the_select">
    <option value="milk">Milk</option>
    <option value="honey">Honey</option>
</select>

Now, let’s play:

var source = document.getElementById('the_select');
var celesta = new Celesta(source); // (contains 'Milk' and 'Honey' items with indexes 0 and 1)

celesta.selectOption(1); // (selecting 'Honey')

celesta.getSelectedOptionIndex(); // => 1


// now, adding another option (using jQuery syntax to make more readable)

$(source.options[0]).insertAfter('<option value="toast">Toast</option>'); // source select now has 'Milk' and 'Toast' and 'Honey'


// but linked Celesta doesn't know anything about this change, so it cannot even selected third item (which has index 2)

celesta.selectOption(2); // trying to select last item

celesta.getSelectedOption(); // => 1 (nothing changed, because 2 is out of options range remembered by Celesta)


// so we need to make a refresh

celesta.refresh();
celesta.selectOption(2); // trying to select last item, again

celesta.getSelectedOption(); // => 2 (finally, we got it!)

Just an alias for refresh.

c.update();

Destroy any DOM structure and handlers created by Celesta instance. Restores source select to be visible and selectable.

c.selectOption(2); // (that also affects source select)

c.destroy(); // (restores source select, with index 2 selected)