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.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.
Theoj-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>
-
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. 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. The label can be hidden using the display attribute.If a text node is provided it will be wrapped in a span.
-
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.
-
endIcon
-
The
endIcon
slot is the button's end icon. The<oj-button>
element accepts DOM nodes as children with the endIcon slot. -
startIcon
-
The
startIcon
slot is the button's start icon. The<oj-button>
element accepts DOM nodes as children with the startIcon slot.
Attributes
-
chroming :solid|outlined|borderless|callToAction|full|half chroming :solid|outlined|borderless|callToAction
-
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, if
$buttonChromingOptionDefault
is set in the current theme as seen in the example below, then that value is the chroming default. - Else, the default chroming is
"solid"
.
Once a value has been set on this button attribute, that value applies regardless of theme and containership.
- Deprecated:
Since Description 6.0.0
This value will be removed in the future. Please use solid instead. - Deprecated:
Since Description 6.0.0
This value will be removed in the future. Please use borderless instead.
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. full
Please use solid instead. In typical themes, full-chrome buttons always have chrome. half
In typical themes, half-chrome buttons acquire chrome only in their hover, active, and selected states. 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
- If the button is in a buttonset or toolbar, then the default chroming is the current
-
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
-
Whether to display both the label and icons (
"all"
) 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.
- Default Value:
"all"
Supported Values:
Value Description all
Display both the label and icons. icons
Display only the icons. 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
-
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");