Element: <oj-button>

Oracle® JavaScript Extension Toolkit (JET)
18.1.0
G25382-01

Since:

0.6.0

Module:

ojbutton

Note: This component is in maintenance mode. Suggested alternative: <oj-c-button>. For help updating an existing application, see the migration section.

QuickNav

Attributes

chroming
disabled
display
label
translations

JET Button

Description: Themeable, WAI-ARIA-compliant push buttons, with appropriate styles for hover, active, checked, and disabled.

To create toggle buttons, see the JET Buttonset.

<oj-button id="myButton">
    <span>My Button</span>
</oj-button>

Push Buttons

Push buttons are ordinary buttons that do not stay pressed in when clicked. Push buttons are created from oj-button elements.

Buttonsets and Toolbars

The JET Buttonset component can be used to create toggle buttons or group related buttons, such as a group of radios or checkboxes. Buttonset provides visual and semantic grouping and WAI-ARIA-compliant focus management. See the Buttonset API doc for more information.

Also, buttons and buttonsets can be placed in a JET Toolbar. Like Buttonset, Toolbar is themable and provides WAI-ARIA-compliant focus management. See the Toolbar API doc for more information.

Touch End User Information

Target	Gesture	Action
Push Button	`Tap`	Push the button.
Toggle Button	`Tap`	Toggle the button.
Menu Button	`Tap`	Open the menu.

Keyboard End User Information

Target	Key	Action
Push Button	`Enter` or `Space`*	Push the button.
Toggle Button	`Enter` or `Space`	Toggle the button.
Menu Button	`Enter`, `Space`*, or `DownArrow`	Open the menu.
Menu Button	`Esc`	Close the menu.

* Some types of Push and Menu Buttons support Enter, not Space.

See the Menu keyboard doc for keystrokes that apply when focus is on the menu.

For accessibility, it is not required to set an aria label on a JET button as it uses the text in the default slot to generate an aria label. Therefore the default slot should be filled even if the button is icon-only (display=icons). However, you can override the default behavior by setting aria-label or aria-labelledby. For providing additional description, you can set aria-describedby with id of span with custom description

See also the oj-focus-highlight discussion.

Disabled content: JET supports an accessible luminosity contrast ratio, as specified in WCAG 2.0 - Section 1.4.3 "Contrast", in the themes that are accessible. (See the "Theming" chapter of the JET Developer Guide for more information on which themes are accessible.) Note that Section 1.4.3 says that text or images of text that are part of an inactive user interface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio required of enabled content, it cannot be used to convey meaningful information.

Migration

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

Deprecated APIs are not available in Core Pack, and are not documented in this migration section.
Before trying to migrate to Core Pack run the JET audits and fix any issues before proceeding.
The refresh() method is no longer supported in Core Pack. See the Core Pack Migration Guide for more information.
This section uses MVVM object syntax, this VDOM Developer Guide section and JET VDOM Binding and Modules video may be helpful to understand what the syntax would be in a VDOM app.

To migrate from oj-button to oj-c-button, you need to revise the import statement and references to oj-c-button in your app. Please note the changes between the two components below.

Label attribute

The default slot is no longer supported. Text labels must be provide using the label attribute.

Title attribute

The title attribute has changed to tooltip

Context Menu

The context menu is no longer supported.

oj-button-full-width class

The oj-button-full-width style class should no longer be used with oj-c-button. Instead, set edge property to bottom

oj-button-sm class

The oj-button-sm style class should no longer be used with oj-c-button. Instead, set size property to sm

oj-button-lg class

The oj-button-lg style class should no longer be used with oj-c-button. Instead, set size property to lg

oj-button-width-full class

The oj-button-width-full style class should no longer be used with oj-c-button. Instead, set width property to 100%

Performance

In lieu of stamping a button in a table, dataGrid, or other container, consider placing a single Button outside the container that acts on the currently selected row or cell.

Setting Component State

Built-in KO bindings, like KO's disable binding, should not be used for state with a JS API, since that is tatamount to updating the DOM directly. The component attribute should be bound instead.

State with no JS API should be set by manipulating the DOM directly in an allowable way, and then calling refresh() on the affected component(s). E.g. the reading direction (LTR / RTL) is changed by by setting the "dir" attribute on the <html> node and calling refresh().

When using a built-in Knockout binding, keep in mind that those bindings do not execute the necessary refresh() call after updating the DOM. Updates that flow from the component to the observable, as a result of user interaction, are not problematic. But updates in the other direction, that programmatically update the DOM because the observable changed, will not be picked up until the next refresh().

Usage

Signature:
interface ButtonElement<SP extends ojButtonSettableProperties = ojButtonSettableProperties>

Typescript Import Format

//To typecheck the element APIs, import as below.
import { ButtonElement } from "ojs/ojbutton";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojbutton";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Styling Classes

.oj-button-confirm

Identifies an action to confirm. Designed for use with a push button.
This class is applied to the Button's root element.

Deprecated:

Since	Description
`9.0.0`	This class will be removed in the future.

Example

<oj-button class="oj-button-confirm">
   <!--  content -->
</oj-button>

.oj-button-full-width

Note: This styleclass is not supported in the following themes: Alta

Apply 100% full-width to the button. The class is applied to the Button's root element. It is intended for buttons which stretch to the edge, not for buttons with padding.

Example

<oj-button class="oj-button-full-width">
   <!--  content -->
</oj-button>

.oj-button-primary

Draws attention to the button, often identifying the primary action in a set of buttons. Designed for use with a push button. In some themes, this class does nothing.
The class is applied to the Button's root element.

Deprecated:

Since	Description
`8.0.0`	This class will be removed in the future. Please use 'callToAction' chroming instead.

Example

<oj-button class="oj-button-primary">
   <!--  content -->
</oj-button>

.oj-focus-highlight

Under normal circumstances this class is applied automatically. It is documented here for the rare cases that an app developer needs per-instance control.

The oj-focus-highlight class applies focus styling that may not be desirable when the focus results from pointer interaction (touch or mouse), but which is needed for accessibility when the focus occurs by a non-pointer mechanism, for example keyboard or initial page load.

The application-level behavior for this component is controlled in the theme by the $focusHighlightPolicy SASS variable; however, note that this same variable controls the focus highlight policy of many components and patterns. The values for the variable are:

nonPointer: oj-focus-highlight is applied only when focus is not the result of pointer interaction. Most themes default to this value.
all: oj-focus-highlight is applied regardless of the focus mechanism.
none: oj-focus-highlight is never applied. This behavior is not accessible, and is intended for use when the application wishes to use its own event listener to precisely control when the class is applied (see below). The application must ensure the accessibility of the result.

To change the behavior on a per-instance basis, the application can set the SASS variable as desired and then use event listeners to toggle this class as needed.

Example

<oj-button class="oj-focus-highlight">
   <!--  content -->
</oj-button>

Category: Button Size

Makes the button small, large, or extra large.
The class is applied to the Button's root element.

Classes:

.oj-button-sm

.oj-button-lg

.oj-button-xl

Deprecated:

Since	Description
`9.0.0`	This class will be removed in the future.

Example

<oj-button class="oj-button-sm">
   <!--  content -->
</oj-button>

CSS Variables

See JET CSS Variables for additional details.

Default buttons

Name	Type	Description
`--oj-button-height`	<length> \| <percentage>	Button height
`--oj-button-border-radius`	<length> \| <percentage>	Button border radius
`--oj-button-font-size`	<length> \| <percentage>	Button font size
`--oj-button-font-weight`	<font_weight>	Button font weight
`--oj-button-icon-size`	<length> \| <percentage>	Button icon size
`--oj-button-text-to-edge-padding`	<length> \| <percentage>	Button text to edge padding
`--oj-button-icon-to-text-padding`	<length> \| <percentage>	Button icon to text padding
`--oj-button-icon-to-edge-padding`	<length> \| <percentage>	Button icon to edge padding

Small buttons

Name	Type	Description
`--oj-button-sm-height`	<length> \| <percentage>	Small button height
`--oj-button-sm-font-size`	<length> \| <percentage>	Small button font size
`--oj-button-sm-icon-size`	<length> \| <percentage>	Small button icon size
`--oj-button-sm-text-to-edge-padding`	<length> \| <percentage>	Small button text to edge padding
`--oj-button-sm-icon-to-text-padding`	<length> \| <percentage>	Small button icon to text padding
`--oj-button-sm-icon-to-edge-padding`	<length> \| <percentage>	Small button icon to edge padding

Large buttons

Name	Type	Description
`--oj-button-lg-height`	<length> \| <percentage>	Large button height
`--oj-button-lg-font-size`	<length> \| <percentage>	Large button font size
`--oj-button-lg-icon-size`	<length> \| <percentage>	Large button icon size
`--oj-button-lg-text-to-edge-padding`	<length> \| <percentage>	Large button text to edge padding
`--oj-button-lg-icon-to-text-padding`	<length> \| <percentage>	Large button icon to text padding
`--oj-button-lg-icon-to-edge-padding`	<length> \| <percentage>	Large button icon to edge padding

Borderless buttons

Name	Type	Description
`--oj-button-borderless-chrome-text-color`	<color>	Borderless chrome button text color
`--oj-button-borderless-chrome-bg-color-hover`	<color>	Borderless chrome button hover background color
`--oj-button-borderless-chrome-border-color-hover`	<color>	Borderless chrome button hover border color
`--oj-button-borderless-chrome-text-color-hover`	<color>	Borderless chrome button hover text color
`--oj-button-borderless-chrome-bg-color-active`	<color>	Borderless chrome button active background color
`--oj-button-borderless-chrome-border-color-active`	<color>	Borderless chrome button active border color
`--oj-button-borderless-chrome-text-color-active`	<color>	Borderless chrome button active text color
`--oj-button-borderless-chrome-bg-color-selected`	<color>	Borderless chrome button selected background color
`--oj-button-borderless-chrome-border-color-selected`	<color>	Borderless chrome button selected border color
`--oj-button-borderless-chrome-text-color-selected`	<color>	Borderless chrome button selected text color
`--oj-button-borderless-chrome-bg-color-selected-hover`	<color>	Borderless chrome button selected hover background color
`--oj-button-borderless-chrome-border-color-selected-hover`	<color>	Borderless chrome button selected hover border color
`--oj-button-borderless-chrome-text-color-selected-hover`	<color>	Borderless chrome button selected hover text color
`--oj-button-borderless-chrome-text-color-disabled`	<color>	Borderless chrome button disabled text color
`--oj-button-borderless-chrome-bg-color-selected-disabled`	<color>	Borderless chrome button disabled selected background color
`--oj-button-borderless-chrome-border-color-selected-disabled`	<color>	Borderless chrome button disabled selected border color
`--oj-button-borderless-chrome-text-color-selected-disabled`	<color>	Borderless chrome button disabled selected text color

Outlined buttons

Name	Type	Description
`--oj-button-outlined-chrome-bg-color`	<color>	Outlined chrome button background color
`--oj-button-outlined-chrome-border-color`	<color>	Outlined chrome button border color
`--oj-button-outlined-chrome-text-color`	<color>	Outlined chrome button text color
`--oj-button-outlined-chrome-bg-color-hover`	<color>	Outlined chrome button hover background color
`--oj-button-outlined-chrome-border-color-hover`	<color>	Outlined chrome button hover border color
`--oj-button-outlined-chrome-text-color-hover`	<color>	Outlined chrome button hover text color
`--oj-button-outlined-chrome-bg-color-active`	<color>	Outlined chrome button active background color
`--oj-button-outlined-chrome-border-color-active`	<color>	Outlined chrome button active border color
`--oj-button-outlined-chrome-text-color-active`	<color>	Outlined chrome button active text color
`--oj-button-outlined-chrome-bg-color-selected`	<color>	Outlined chrome button selected background color
`--oj-button-outlined-chrome-border-color-selected`	<color>	Outlined chrome button selected border color
`--oj-button-outlined-chrome-text-color-selected`	<color>	Outlined chrome button selected text color
`--oj-button-outlined-chrome-bg-color-selected-hover`	<color>	Outlined chrome button selected hover background color
`--oj-button-outlined-chrome-border-color-selected-hover`	<color>	Outlined chrome button selected hover border color
`--oj-button-outlined-chrome-text-color-selected-hover`	<color>	Outlined chrome button selected hover text color
`--oj-button-outlined-chrome-bg-color-disabled`	<color>	Outlined chrome button disabled background color
`--oj-button-outlined-chrome-border-color-disabled`	<color>	Outlined chrome button disabled border color
`--oj-button-outlined-chrome-text-color-disabled`	<color>	Outlined chrome button disabled text color
`--oj-button-outlined-chrome-bg-color-selected-disabled`	<color>	Outlined chrome button selected disabled background color
`--oj-button-outlined-chrome-border-color-selected-disabled`	<color>	Outlined chrome button selected disabled border color
`--oj-button-outlined-chrome-text-color-selected-disabled`	<color>	Outlined chrome button selected disabled text color

Solid buttons

Name	Type	Description
`--oj-button-solid-chrome-bg-color`	<color>	Solid chrome button background color
`--oj-button-solid-chrome-border-color`	<color>	Solid chrome button border color
`--oj-button-solid-chrome-text-color`	<color>	Solid chrome button text color
`--oj-button-solid-chrome-bg-color-hover`	<color>	Solid chrome button hover background color
`--oj-button-solid-chrome-border-color-hover`	<color>	Solid chrome button hover border color
`--oj-button-solid-chrome-text-color-hover`	<color>	Solid chrome button hover text color
`--oj-button-solid-chrome-bg-color-active`	<color>	Solid chrome button active background color
`--oj-button-solid-chrome-border-color-active`	<color>	Solid chrome button active border color
`--oj-button-solid-chrome-text-color-active`	<color>	Solid chrome button active text color
`--oj-button-solid-chrome-bg-color-selected`	<color>	Solid chrome button selected background color
`--oj-button-solid-chrome-border-color-selected`	<color>	Solid chrome button selected border color
`--oj-button-solid-chrome-text-color-selected`	<color>	Solid chrome button selected text color
`--oj-button-solid-chrome-bg-color-selected-hover`	<color>	Solid chrome button selected hover background color
`--oj-button-solid-chrome-border-color-selected-hover`	<color>	Solid chrome button selected hover border color
`--oj-button-solid-chrome-text-color-selected-hover`	<color>	Solid chrome button selected hover text color
`--oj-button-solid-chrome-bg-color-disabled`	<color>	Solid chrome button disabled background color
`--oj-button-solid-chrome-border-color-disabled`	<color>	Solid chrome button disabled border color
`--oj-button-solid-chrome-text-color-disabled`	<color>	Solid chrome button disabled text color
`--oj-button-solid-chrome-bg-color-selected-disabled`	<color>	Solid chrome button disabled selected background color
`--oj-button-solid-chrome-border-color-selected-disabled`	<color>	Solid chrome button disabled selected border color
`--oj-button-solid-chrome-text-color-selected-disabled`	<color>	Solid chrome button disabled selected text color

Call to action buttons

Name	Type	Description
`--oj-button-call-to-action-chrome-bg-color`	<color>	Call to action chrome button background color
`--oj-button-call-to-action-chrome-border-color`	<color>	Call to action chrome button border color
`--oj-button-call-to-action-chrome-text-color`	<color>	Call to action chrome button text color
`--oj-button-call-to-action-chrome-bg-color-hover`	<color>	Call to action chrome button hover background color
`--oj-button-call-to-action-chrome-border-color-hover`	<color>	Call to action chrome button hover border color
`--oj-button-call-to-action-chrome-text-color-hover`	<color>	Call to action chrome button hover text color
`--oj-button-call-to-action-chrome-bg-color-active`	<color>	Call to action chrome button active background color
`--oj-button-call-to-action-chrome-border-color-active`	<color>	Call to action chrome button active border color
`--oj-button-call-to-action-chrome-text-color-active`	<color>	Call to action chrome button active text color

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

Default

The default slot is the button's text label, if no label attribute is specified. The <oj-button> element accepts plain text or DOM nodes as children for the default slot. A default slot label is required for all buttons for accessibility purposes, if no label attribute is specified. The label can be hidden using the display attribute.

If a text node is provided it will be wrapped in a span.

Note that if both a default slot and a label attribute are provided, the attribute takes precedence over the default slot.

contextMenu

The contextMenu slot is set on the oj-menu within this element. This is used to designate the JET Menu that this component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the JET Menu specified in this slot.

The application can register a listener for the Menu's ojBeforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the ojBeforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc of the individual components for details.

Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

Deprecated:

Since	Description
`13.0.0`	This web component no longer supports launching a context menu.

endIcon

The endIcon slot is the button's end icon. The <oj-button> element accepts DOM nodes as children with the endIcon slot.

Example

<oj-button>
  <span>myValue</span>
  <span slot='endIcon' class='myIconClass'></span>
</oj-button>

startIcon

The startIcon slot is the button's start icon. The <oj-button> element accepts DOM nodes as children with the startIcon slot.

Example

<oj-button>
  <span slot='startIcon' class='myIconClass'></span>
  <span>myValue</span>
</oj-button>

Attributes

Indicates in what states the button has chrome (background and border).

The default chroming varies by theme and containership as follows:

If the button is in a buttonset or toolbar, then the default chroming is the current chroming value of the nearest such container.
Else, the default chroming value is controlled by the theme.

Once a value has been set on this button attribute, that value applies regardless of theme and containership.

Supported Values:

Value Description

borderless Borderless buttons are the least prominent variation. Borderless buttons are useful for supplemental actions that require minimal emphasis.

callToAction A Call To Action (CTA) button guides the user to take or complete the action that is the main goal of the page or page section. There should only be one CTA button on a page at any given time.

danger A Danger button alerts the user to a dangerous situation.

full

Please use solid instead. In typical themes, full-chrome buttons always have chrome.

Deprecated:

Since	Description
`6.0.0`	This value will be removed in the future. Please use solid instead.

half

In typical themes, half-chrome buttons acquire chrome only in their hover, active, and selected states.

Deprecated:

Since	Description
`6.0.0`	This value will be removed in the future. Please use borderless instead.

outlined Outlined buttons are salient, but lighter weight than solid buttons. Outlined buttons are useful for secondary actions.

solid Solid buttons stand out, and direct the user's attention to the most important actions in the UI.

Names

Item	Name
Property	`chroming`
Property change event	`chromingChanged`
Property change listener attribute (must be of type function, see Events and Listeners for additional information.)	`on-chroming-changed`

disabled :boolean

Disables the button if set to true.

After create time, the disabled state should be set via this API, not by setting the underlying DOM attribute.

Default Value:

false

Names

Item	Name
Property	`disabled`
Property change event	`disabledChanged`
Property change listener attribute (must be of type function, see Events and Listeners for additional information.)	`on-disabled-changed`

display :"all"|"icons"|"label"

Whether to display both the label and icons ("all") or just the label ("label") or just the icons ("icons"). In the latter case, the label is displayed in a tooltip instead, unless a tooltip was already supplied at create time.

For accessibility, a JET Button must always have a label set via the default slot, even if it is icon-only.

Supported Values:

Value	Description
`all`	Display both the label and icons.
`icons`	Display only the icons.
`label`	Display only the label.

Default Value:

"all"

Names

Item	Name
Property	`display`
Property change event	`displayChanged`
Property change listener attribute (must be of type function, see Events and Listeners for additional information.)	`on-display-changed`

(nullable) label :string

Text to show in the button. The label attribute takes precedence over the default DOM slot.

Values set on this option, at create time or later, are treated as plain text, not HTML. If the label is specified via DOM at create time, that HTML content is kept.

For accessibility, a JET Button must always have a label, even if it is icon-only.

Names

Item	Name
Property	`label`
Property change event	`labelChanged`
Property change listener attribute (must be of type function, see Events and Listeners for additional information.)	`on-label-changed`

translations :object|null

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

If this component has translations, their documentation immediately follows this doc entry.

Names

Item	Name
Property	`translations`
Property change event	`translationsChanged`
Property change listener attribute (must be of type function, see Events and Listeners for additional information.)	`on-translations-changed`

Events

ojAction

Triggered when a button is clicked. This will be triggered by keyboard events as well as mouse/touch events.

To ensure keyboard accessibility, the only correct, supported way to react to the click of a button is to listen for this event. Click listeners should not be used.

See Events and Listeners for additional information.

Since:

5.0.0

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.

Parameters:

Name	Type	Description
`property`	string	The property name to get. Supports dot notation for subproperty access.

Since:

4.0.0

Returns:

Type: any

Example

Get a single subproperty of a complex property:

let subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

refresh : {void}

Refreshes the component.

Returns:

Type: void

setProperties(properties) : {void}

Performs a batch set of properties. The type of value for each property being set must match the type of the property as specified in this API document.

Parameters:

Name	Type	Description
`properties`	Object	An object containing the property and value pairs to set.

Since:

4.0.0

Returns:

Type: void

Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) : {void}

Sets a property or a subproperty (of a complex property) and notifies the component of the change, triggering a [property]Changed event. The value should be of the same type as the type of the attribute mentioned in this API document.

Parameters:

Name	Type	Description
`property`	string	The property name to set. Supports dot notation for subproperty access.
`value`	any	The new value to set the property to.

Since:

4.0.0

Returns:

Type: void

Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Element: <oj-button>

Slots

Attributes

Events

Methods

Other Topics

Usage

Signature: interface ButtonElement<SP extends ojButtonSettableProperties = ojButtonSettableProperties>

Typescript Import Format

Styling Classes

.oj-button-confirm

Deprecated:

Example

.oj-button-full-width

Example

.oj-button-primary

Deprecated:

Example

.oj-focus-highlight

Example

Category: Button Size

Classes:

.oj-button-sm

.oj-button-lg

.oj-button-xl

Deprecated:

Example

CSS Variables

Default buttons

Small buttons

Large buttons

Borderless buttons

Outlined buttons

Solid buttons

Call to action buttons

Slots

Default

contextMenu

endIcon

Example

startIcon

Example

Attributes

chroming :"solid"|"outlined"|"borderless"|"callToAction"|"danger"|"full"|"half" chroming :"solid"|"outlined"|"borderless"|"callToAction"|"danger"

Supported Values:

Names

disabled :boolean

Names

display :"all"|"icons"|"label"

Supported Values:

Names

(nullable) label :string

Names

translations :object|null

Names

Events

ojAction

Methods

getProperty(property) : {any}

Parameters:

Returns:

Example

refresh : {void}

Returns:

setProperties(properties) : {void}

Parameters:

Returns:

Example

setProperty(property, value) : {void}

Parameters:

Returns:

Example

Signature:
interface ButtonElement<SP extends ojButtonSettableProperties = ojButtonSettableProperties>