Coral.Button

Current Version: 1.8.1
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Related Components: Coral.AnchorButton
Github: @coralui/coralui-component-button

A button containing text and/or an image. It extends HTMLButtonElement to take advantage of the accessibility given by browsers but it means that this component has a special way of instantiating.

Note: Using the minimal variant results in a button without a minimum value for its width or height. One possible usage could icon-only buttons, such as a close button for a dialog.

Forms

Vertical Layout

Show Markup 
<form class="coral-Form coral-Form--vertical">
  <section class="coral-Form-fieldset">
    <div class="coral-Form-fieldwrapper">
      <label class="coral-Form-fieldlabel" id="label-vertical-textfield-0">Label</label>
      <input is="coral-textfield" class="coral-Form-field" placeholder="Enter your text" name="name" labelledby="label-vertical-textfield-0">
    </div>
    <div class="coral-Form-fieldwrapper">
      <button is="coral-button" class="coral-Form-field" variant="primary">Engage</button>
      <button is="coral-button" class="coral-Form-field" variant="quiet">Cancel</button>
    </div>
  </section>
</form>

Aligned Layout

Show Markup 
<form class="coral-Form coral-Form--aligned">
  <section class="coral-Form-fieldset">
  <div class="coral-Form-fieldwrapper">
    <label class="coral-Form-fieldlabel" id="label-aligned-textfield-0">Label</label>
    <input is="coral-textfield" class="coral-Form-field" placeholder="Enter your text" name="name" labelledby="label-aligned-textfield-0">
  </div>
  <div class="coral-Form-fieldwrapper">
    <label class="coral-Form-fieldlabel" id="label-aligned-textfield-empty"></label>
    <button is="coral-button" class="coral-Form-field" variant="primary">Engage</button>
    <button is="coral-button" class="coral-Form-field" variant="quiet">Cancel</button>
  </div>
</section>
</form>

Coral.Button API

Constructor

JavaScript:

new Coral.Button() or document.createElement('button', 'coral-button')

HTML Tag:

<button is="coral-button">

Extends

Sub-components

Static Properties

Coral.Button.iconPosition {String}

Enumeration representing the icon position inside the button.

Properties:

Name Type Value Description
RIGHT String right Position should be right of the button label.
LEFT String left Position should be left of the button label.

Coral.Button.size {String}

Enumeration representing button sizes.

Properties:

Name Type Value Description
MEDIUM String M A medium button is the default, normal sized button.
LARGE String L A large button, which is larger than a medium button.

Coral.Button.variant {String}

Enum for button variant values.

Properties:

Name Type Value Description
CTA String cta A button that is meant to grab the user's attention.
PRIMARY String primary A button that indicates that the button's action is the primary action.
SECONDARY String secondary A default, gray button
DEFAULT String secondary An alias to secondary, included for backwards compatibility.
QUIET String quiet A button with no border or background.
WARNING String warning A button that indicates that the button's action is dangerous.
MINIMAL String minimal A minimal button with no background or border.

Instance Properties

instance.block {Boolean}

Reflected
Expands the button to the full width of the parent.
Default Value:
  • false
HTML Attribute:
  • block

instance.hidden {Boolean}

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

instance.icon {String}

Specifies the icon name used inside the button. See Coral.Icon for valid icon names.
Default Value:
  • ""
HTML Attribute:
  • icon
See:

instance.iconPosition {Coral.Button.iconPosition}

Reflected
Position of the icon relative to the label. If no iconPosition is provided, it will be set on the left side by default.
Default Value:
  • Coral.Button.iconPosition.LEFT
HTML Attribute:
  • iconposition

instance.iconSize {Coral.Icon.size}

Size of the icon. It accepts both lower and upper case sizes.
Default Value:
  • Coral.Icon.size.SMALL
HTML Attribute:
  • iconsize
See:

instance.label {HTMLElement}

The label of the button.

instance.selected {Boolean}

Reflected
Whether the button is selected.
Default Value:
  • false
HTML Attribute:
  • selected

instance.size {Coral.Button.size}

Reflected
The size of the button. It accepts both lower and upper case sizes. Currently only "M" (the default) and "L" are available.
Default Value:
  • Coral.Button.size.MEDIUM
HTML Attribute:
  • size

instance.variant {Coral.Button.variant}

Reflected
The button's variant.
Default Value:
  • Coral.Button.variant.SECONDARY
HTML Attribute:
  • variant

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.