A Multifield is a composite field that allows you to add, reorder, and remove multiple instances of a component.

Pre-filled items

A Multifield item can have a pre-filled content different from the Multifield template. But added items will always be generated based on the template.

Child elements of <coral-multifield> can be given a special attribute to enable functionality.

  • [coral-multifield-add] - Click to add an item
Show Markup
<coral-multifield>
  <coral-multifield-item>
    <input is="coral-textfield" type="text" value="Basel">
  </coral-multifield-item>
  <button coral-multifield-add type="button" is="coral-button">Add a field</button>
  <template coral-multifield-template>
    <input is="coral-textfield" type="text">
  </template>
</coral-multifield>

IE11 template limitation

Multifield partially supports the template element on IE11. If adding/removing items in the template is required, template.content should be used.

<script>
  document.addEventListener('DOMContentLoaded', function() {
    var multifield = new Coral.Multifield();
    // Use template.content to be able to specify the template content dynamically on IE11.
    multifield.template.content.appendChild(new Coral.Textfield());
  
    var add = new Coral.Button();
    add.label.textContent = 'Add a field';
    add.setAttribute('coral-multifield-add', '');
    multifield.appendChild(add);
  
    var constructorExample = document.getElementById('constructorExample');
    constructorExample.appendChild(multifield);
  });
</script>

Coral.Multifield API

Constructor

JavaScript:

new Coral.Multifield() or document.createElement('coral-multifield')

HTML Tag:

<coral-multifield>

Extends

Sub-components

Instance Properties

instance.hidden {Boolean}

Reflected
Whether this component is hidden or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • hidden

instance.items {Coral.Collection}

Readonly
The Collection Interface that allows interacting with the Coral.Multifield items that the component contains. See Coral.Collection for more details.

instance.template {HTMLElement}

The Multifield template element. It will be used to render a new item once the element with the attribute coral-multifield-add is clicked. It supports the template tag. While specifying the template from markup, it should include the coral-multifield-template attribute. NOTE: On IE11, only template.content is supported to add/remove elements to the template.

Methods

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hide

Hide this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
The event name to stop listening for.
selector String Yes
The selector that was used for event delegation.
func function No
The function that was passed to on().
useCapture Boolean Yes
Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to listen for.
selector String Yes
The selector to use for event delegation.
func function No
The function that will be called when the event is triggered.
useCapture Boolean Yes
Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
Inherited From:

instance.set

Set a single property.
Parameters:
Name Type Description
property String The name of the property to set.
value * The value to set the property to.
silent Boolean If true, events should not be triggered as a result of this set.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.show

Show this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
The event name to trigger.
props Object Yes
Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
Set to false to prevent the event from bubbling.
cancelable Boolean Yes
Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Events

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:
Deprecated:
  • since 1.14.0, use MutationObserver instead.

    coral-component:detached

    Triggered when the component is detached to the DOM.
    Callback Parameters:
    Name Type Description
    event Object Event object.
    Inherited From:
    Deprecated:
    • since 1.14.0, use MutationObserver instead.

      coral-component:ready

      Triggerred when the component has been upgraded and is ready for use.
      Callback Parameters:
      Name Type Description
      event Object Event object.
      Inherited From:
      Deprecated:
      • since 1.9.0, use Coral.commons.ready() instead.

        Coral.Multifield.Item API

        Constructor

        JavaScript:

        new Coral.Multifield.Item() or document.createElement('coral-multifield-item')

        HTML Tag:

        <coral-multifield-item>

        Extends

        Sub-components

        Instance Properties

        instance.content {HTMLElement}

        The item content.

        instance.hidden {Boolean}

        Reflected
        Whether this component is hidden or not.
        Inherited From:
        Default Value:
        • false
        HTML Attribute:
        • hidden

        Methods

        instance.get

        Get the value of a property.
        Parameters:
        Name Type Description
        property String The name of the property to fetch the value of.
        Returns:
        Property value. {*}
        Inherited From:

        instance.hide

        Hide this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.off

        Remove an event listener.
        Parameters:
        Name Type Optional Description
        eventName String No
        The event name to stop listening for.
        selector String Yes
        The selector that was used for event delegation.
        func function No
        The function that was passed to on().
        useCapture Boolean Yes
        Only remove listeners with useCapture set to the value passed in.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.on

        Add an event listener.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        The event name to listen for.
        selector String Yes
        The selector to use for event delegation.
        func function No
        The function that will be called when the event is triggered.
        useCapture Boolean Yes
        Whether or not to listen during the capturing or bubbling phase.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.remove

        Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
        Inherited From:

        instance.set

        Set a single property.
        Parameters:
        Name Type Description
        property String The name of the property to set.
        value * The value to set the property to.
        silent Boolean If true, events should not be triggered as a result of this set.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.show

        Show this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.trigger

        Trigger an event.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        The event name to trigger.
        props Object Yes
        Additional properties to make available to handlers as event.detail.
        bubbles Boolean Yes
        Set to false to prevent the event from bubbling.
        cancelable Boolean Yes
        Set to false to prevent the event from being cancelable.
        Returns:
        CustomEvent object {CustomEvent}
        Inherited From:

        Events

        coral-component:attached

        Triggered when the component is attached to the DOM.
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:
        Deprecated:
        • since 1.14.0, use MutationObserver instead.

          coral-component:detached

          Triggered when the component is detached to the DOM.
          Callback Parameters:
          Name Type Description
          event Object Event object.
          Inherited From:
          Deprecated:
          • since 1.14.0, use MutationObserver instead.

            coral-component:ready

            Triggerred when the component has been upgraded and is ready for use.
            Callback Parameters:
            Name Type Description
            event Object Event object.
            Inherited From:
            Deprecated:
            • since 1.9.0, use Coral.commons.ready() instead.