Element: <oj-c-switch>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
21.0.0
G39657-01

Since:
  • 21.0.0
Module:
  • switch

Note: This component supersedes the following component: <oj-switch>. Migration info available at preceding link.

QuickNav

Attributes

Methods

Type Definitions

Documentation-only Types

Other Topics


JET Switch Component

The Switch component toggles between two mutually exclusive states, such as on and off. It immediately affects content or state for binary choices that must take effect right away, for example, switching between light and dark mode. 

<oj-c-switch label-hint="Notifications" value="false"></oj-c-switch>

Validation and Messaging

oj-c-switch does not support JET EditableValue validation features such as converters, validators, or the required property. As a result, it does not run normal or deferred validation and does not provide validate() or showMessages().

Applications can display business/custom validation messages using the messagesCustom property. Messages set through messagesCustom are shown immediately. To clear custom messages, set messagesCustom to an empty array.

The component clears messagesCustom when:

  • the user toggles the switch (value changes due to user interaction)
  • the application changes the value property programmatically
  • the reset() method is called

The valid property reflects the current messaging state (for example, it becomes invalid when custom error messages are present).

User Assistance Text

User assistive text provides guidance to help the user understand what data to enter or select.

By default all user assistance text shows inline. See the user-assistance-density property for other ways the user assistance text can render, like in 'compact' mode.

The JET form component properties that are used for user assistance text are help.instruction, validator and converter hints (for components that support these properties), and help-hints. In the Redwood theme for clarity only one user assistance text shows to the user. The precedence rules are:

  • help.instruction shows;
  • if no help.instruction, then validator hint shows (for components that have validators);
  • if no help.instruction or validator hint, then help-hints.definition shows;
  • if no help.instruction, validator hint, or help-hints.definition, then converter hint shows (for components that have converters).
  • help-hints.source always shows along side the above.

Touch End User Information

Target Gesture Action
Switch Tap Toggles the switch value.

Keyboard End User Information

Target Key Action
Switch Tab In Sets focus to the switch.
Switch Space or Enter Toggles the switch value.

Accessibility

For accessibility, set the label-hint property. If there is no visible label, then to make this accessible to screen reader users, set the label-hint and label-edge='none' which renders an aria-label with the label-hint text.

The component is accessible; it sets and maintains the appropriate aria- attributes (for example aria-checked and aria-disabled).

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.


Usage

Signature:

interface CSwitchElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CSwitchElement } from "oj-c/switch";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/switch";

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.


Global Attributes

Note: In addition to the component's custom attributes, the following global attributes are also supported by this component (note the differences in data binding syntax between component and global attributes described here)

aria-describedby :string

Identifies the element (or elements) that describes the switch.
Names
Item Name
Property aria-describedby
Property change event aria-describedbyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-aria-describedby-changed

id :string

Unique identifier for the component.
Names
Item Name
Property id
Property change event idChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-id-changed

Attributes

column-span :number

Specifies how many columns this component should span. This only takes effect when this component is a child of a form layout that has direction 'row'.
Default Value:
  • 1
Names
Item Name
Property columnSpan
Property change event columnSpanChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-column-span-changed

container-readonly :boolean

Specifies whether an ancestor container, like oj-c-form-layout, is readonly.
Names
Item Name
Property containerReadonly
Property change event containerReadonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-container-readonly-changed

disabled :boolean

Whether the component is disabled.
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-options :oj-c.Switch.DisplayOptionsProps

Display options for auxiliary content that determines whether or not it should be displayed.
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-display-options-changed

help :oj-c.Switch.Help

Form component help information.
Names
Item Name
Property help
Property change event helpChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-help-changed

help-hints :oj-c.Switch.HelpHints

The helpHints object contains a definition property, sourceText property, and a source property.
Names
Item Name
Property helpHints
Property change event helpHintsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-help-hints-changed

label-edge :"inside"|"none"|"start"|"top"

Specifies how the label of the component is positioned when the label-hint attribute is set on the component.
Supported Values:
Value Description
inside The label will be placed on top of the switch, but is smaller than 'top' option.
none The switch will not create a label, but instead set the aria-label property on the switch.
start The label will be placed before the start of the switch.
top The label will be placed on top of the switch.
Names
Item Name
Property labelEdge
Property change event labelEdgeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-edge-changed

label-hint* :string

Represents a hint for rendering a label on the component. Used in combination with label-edge.
Names
Item Name
Property labelHint
Property change event labelHintChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-hint-changed

label-start-width :(number|string)

The width of the label when labelEdge is 'start'.
Names
Item Name
Property labelStartWidth
Property change event labelStartWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-start-width-changed

label-wrapping :"truncate"|"wrap"

Should the labels wrap or truncate when there is not enough available space.
Deprecated:
Since Description
21.0.0 Label truncation for 'start' and 'top' aligned labels is no longer recommended by the Redwood Design System. The default for labelWrapping was 'wrap' and that is now the only suggested pattern by UX design for 'start' and 'top' aligned labels. 'inside' aligned labels are always truncated per UX design and are not affected by this property's value.
Supported Values:
Value Description
truncate Label will truncate if needed.
wrap Label will wrap if needed.
Names
Item Name
Property labelWrapping
Property change event labelWrappingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-wrapping-changed

messages-custom :Array.<oj-c.Switch.ComponentMessageItem>

List of messages an app would add to the component when it has business/custom validation errors that it wants the component to show. This allows the app to perform further validation before sending data to the server. When this option is set the message shows to the user right away. To clear the custom message, set messagesCustom back to an empty array.

See the Validation and Messaging section for details on when the component clears messagesCustom; for example, when the value changes.

Default Value:
  • []
Supports writeback:
  • true
Names
Item Name
Property messagesCustom
Property change event messagesCustomChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-messages-custom-changed

readonly :boolean

Whether the component is readonly.
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

readonly-user-assistance-shown :"none"|"confirmationAndInfoMessages"

Specifies which user assistance types should be shown when the component is readonly.
Default Value:
  • 'none'
Names
Item Name
Property readonlyUserAssistanceShown
Property change event readonlyUserAssistanceShownChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-user-assistance-shown-changed

user-assistance-density :"reflow"|"efficient"|"compact"

Specifies the density of the form component's user assistance presentation.

If the property value is not set either directly on the component or inherited from a parent form layout, then the property is treated as if its value were "reflow".

Supported Values:
Value Description
reflow Messages, help, and hints are all shown inline under the field with no reserved space. Layout will reflow when text is displayed.
efficient Messages, help, and hints are all shown inline under the field with reserved space.
compact Messages, help, and hints are all shown inline under the field with reserved space.
Names
Item Name
Property userAssistanceDensity
Property change event userAssistanceDensityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-user-assistance-density-changed

(readonly) valid :"valid"|"pending"|"invalidHidden"|"invalidShown"

The current valid state of the component. It is evaluated on initial render. Since oj-c-switch does not support converters, validators, or the required property, the valid state is re-evaluated:

  • when messagesCustom is updated
  • when the value changes (user interaction or programmatic intervention), since the component clears messagesCustom
  • when reset() is called

Note: New valid states may be added to the list of valid values in future releases. Any new values will start with "invalid" if it is an invalid state, "pending" if it is pending state, and "valid" if it is a valid state.

Supported Values:
Value Description
valid The component is valid
pending The component is waiting for the validation state to be determined. The 'pending' state is set at the start of the validation process.
invalidHidden The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity 'error'.
invalidShown The component has invalid messages showing. An invalid message is one with severity 'error'.
Supports writeback:
  • true
Names
Item Name
Property valid
Property change event validChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-valid-changed

value :boolean

The boolean state of the switch component.

When the value property changes due to programmatic intervention, the component clears all messages including messagesCustom.

Default Value:
  • false
Supports writeback:
  • true
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

reset : {void}

Resets the component by clearing all messages.
Returns:
Type
void

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
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.
Returns:
Type
void

Type Definitions

Documentation-only Types

Note: Type definitions in this section have been provided for documentation purposes and cannot be imported into application code.

ComponentMessageItem

A type for a single component message
Properties:
Name Type Argument
detail string <optional>
severity "error" | "confirmation" | "info" | "warning" <optional>
summary string <optional>

DisplayOptionsProps

Display options for auxiliary content that determines whether or not it should be displayed.
Properties:
Name Type Argument Default Description
messages "none" | "display" <optional>
 'display' Display options for auxiliary message text.

Help

Form component help information.
Properties:
Name Type Argument Default Description
instruction string <optional>
 '' A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select.

HelpHints

The helpHints object contains a definition property and a source property.
Properties:
Name Type Argument Default Description
definition string <optional>
 '' A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select. help-hints could come from a help system.
source string <optional>
 '' Help source URL associated with the component.
sourceText string <optional>
 '' Custom text to be used for the source link.