Svelecte

Rendering

Svelecte provides many ways how to customize rendering. Whole concept of rendering was rewritten in v4.0 to provide more possibilities as many (some) users requested. Hopefully you will have enough tools to make it work as you need.

In general rendering customization can be split into 2 groups:

Render functions

Render functions (aka renderers) are simple functions which return string, which is then rendered through {@html} tag. This is very easily customizable and more importantly available outside svelte, which is needed when using svelecte as custom element. Another advantage is, that highlighting is handled automatically. Of course highlighting can be disabled if needed.

Render function have following signature:

/**
 * @param {object} item
 * @param {boolean} [selectionSection] - if true, option is rendered in control, otherwise in dropdown
 * @param {string} [inputValue] - search value, if you want to handle highlighting yourself
 * @returns {string}
 */
function renderer() {}
/**
 * @param {object} item
 * @param {boolean} [selectionSection] - if true, option is rendered in control, otherwise in dropdown
 * @param {string} [inputValue] - search value, if you want to handle highlighting yourself
 * @returns {string}
 */
function renderer() {}

You can define renderers globally or per-component basis. To differenciate whether item is selected you can use internal $selected property.

Note: When using custom renderers with inputValue being used, it’s up to you correctly escape HTML tags

<script>
  import Svelecte, { addRenderer } from 'svelecte';

  function colorRenderer(item, _isSelection, _inputValue) {
    return _isSelection
      ? `<div style="width:16px; height: 16px; background-color: ${item.hex};"></div>${item.text}`
      : `${item.text} (#${item.hex})`
  }

  addRenderer('color', colorRenderer);
</script>

<Svelecte renderer="color" />

<Svelecte renderer={colorRenderer} />
<script>
  import Svelecte, { addRenderer } from 'svelecte';

  function colorRenderer(item, _isSelection, _inputValue) {
    return _isSelection
      ? `<div style="width:16px; height: 16px; background-color: ${item.hex};"></div>${item.text}`
      : `${item.text} (#${item.hex})`
  }

  addRenderer('color', colorRenderer);
</script>

<Svelecte renderer="color" />

<Svelecte renderer={colorRenderer} />

Result:

Using renderer globally:

Using renderer locally:

Snippets

Svelecte provide multiple Snippets as you can see below. On the left you can see default snippet implementation, on the right you can see snippet placeholders.

2 selected
prepend
Collapsed selection
append

Snippets summary:

{#snippet prepend()}
{#snippet selection(selectedOptions, bindItemAction)}
{#snippet collapsedSelection(selectedOptions, i18n)}
{#snippet clearIcon(selectedOptions, inputValue)}
{#snippet toggleIcon(dropdownShow)}
{#snippet append()}
{#snippet listHeader()}
{#snippet option(opt, inputValue)}
{#snippet createRow(isCreating, inputValue, i18n)}
{#snippet prepend()}
{#snippet selection(selectedOptions, bindItemAction)}
{#snippet collapsedSelection(selectedOptions, i18n)}
{#snippet clearIcon(selectedOptions, inputValue)}
{#snippet toggleIcon(dropdownShow)}
{#snippet append()}
{#snippet listHeader()}
{#snippet option(opt, inputValue)}
{#snippet createRow(isCreating, inputValue, i18n)}

Snippets in more details:

• selection

{#snippet collapsedSelection(selectedOptions, i18n)}
<!-- your snippet content -->
{/snippet}

<!-- example implementation -->
{#snippet selection(selectedOptions, bindItemAction)}
  {#each selectedOptions as opt (opt.id)}
    <div>
      {item.text}
      <button data-action="deselect" use:bindItem={opt}>&times;</button>
    </div>
  {/each}
{/snippet}
{#snippet collapsedSelection(selectedOptions, i18n)}
<!-- your snippet content -->
{/snippet}

<!-- example implementation -->
{#snippet selection(selectedOptions, bindItemAction)}
  {#each selectedOptions as opt (opt.id)}
    <div>
      {item.text}
      <button data-action="deselect" use:bindItem={opt}>&times;</button>
    </div>
  {/each}
{/snippet}

Where:

  • selectedOptions is array of selected options as objects
  • bindItemAction is action which can be used to bind selected option option to the element with attribute data-action="deselect". This attribute indicates, that when given option should be removed from selection.

• collapsedSelection

collapsedSelection is paired with collapseSelection prop:

  • collapseSelection=null: only selection snippet is visible (default)
  • collapseSelection='blur': selection snippet is show only when component is focused
  • collapseSelection='always': selection snippet is never show
{#snippet collapsedSelection(selectedOptions, i18n)}{/snippet}

<!-- default implementation -->
{#snippet collapsedSelection(i18n)}
  {i18n.collapsedSelection(selectedOptions.length)}
{/snippet}
{#snippet collapsedSelection(selectedOptions, i18n)}{/snippet}

<!-- default implementation -->
{#snippet collapsedSelection(i18n)}
  {i18n.collapsedSelection(selectedOptions.length)}
{/snippet}

Where:

  • selectedOptions is array of selected options as objects
  • i18n default or customized i18n object

• clearIcon

Snippet is coupled with clearable prop. You can override only the content of clear button.

{#snippet snippet_clearIcon(selectedOptions, inputValue)}
{#snippet snippet_clearIcon(selectedOptions, inputValue)}

Where:

  • selectedOptions is array of selected options as objects
  • inputValue search query, if state of clear icon is related to user action

• toggleIcon

Dropdown toggle icon

{#snippet toggleIcon(dropdownShow)}
{#snippet toggleIcon(dropdownShow)}

Where:

  • dropdownShow is bool, whether dropdown is being shown or not

• listHeader

Optional dropdown header content

<!-- empty snippet with no props -->
{#snippet listHeader()}
<!-- empty snippet with no props -->
{#snippet listHeader()}

Originally added to address issue #151, but can be used for anything. If you want to display selected options here as in mentioned issue, check Migration guide.

• option

{#snippet option(opt, inputValue)}
{#snippet option(opt, inputValue)}

Where:

  • item is current option in dropdown. To duplicate highlighting functionality you need to use function highlightSearch exported from the library.
  • inputValue entered value

• createRow

This snippet is available only when creatable prop is true (and you enter to enter some input).

{#snippet snippet_createRow(isCreating, inputValue, i18n)}
{#snippet snippet_createRow(isCreating, inputValue, i18n)}

Where:

  • isCreating is true when executing async createHandler.
  • inputValue entered value
  • i18n default or customized i18n object
Made with Svelte ❤ by Martin Skocik.
♦
You can support me through GitHub.