Element: <oj-c-input-search>

CORE PACK

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

Since:
  • 21.0.0
Module:
  • input-search

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

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Documentation-only Types

Other Topics


JET Input Search

Description: JET Input Search provides support for entering freeform search text.

Input Search is not a full form control and is not intended to be used as a normal form-layout field. It does not expose label, help, validation, disabled, readonly, or form context features.


<oj-c-input-search></oj-c-input-search>

Accessibility

Core Pack Input Search provides a localized default accessible label for the search affordance. Applications do not need to set aria-label or aria-labelledby. Use aria-describedby when additional descriptive content needs to be associated with the search field. The component sets and maintains the appropriate ARIA attributes for the input and its suggestions.

Touch End User Information

Target Gesture Action
Non-phone input field Tap Opens suggestions when they are closed and suggestions are available. If suggestions are already open, leaves them open.
Phone search launcher Tap Opens the full-screen search dialog when suggestions are available.
Phone dialog back button Tap Closes the dialog without submitting new text and restores the prior field value. If the clear button was used, retains the cleared value instead.
Phone dialog input Tap Places cursor focus in the dialog input.
Phone dialog clear button Tap Clears the current search text without submitting it. The cleared value is retained if the dialog is then closed with the back button.
Phone dialog suggestion Tap Selects the suggestion, closes the dialog, and returns focus to the search launcher.

Keyboard End User Information

Target Key Action
Input field Tab In Sets focus to the input and initially highlights the text in the field. On desktop, suggestions do not open until the user enters text, clicks the field, or presses UpArrow or DownArrow.
Input field Enter Submits the current search text. An open suggestion list or autocomplete text does not select a suggestion by itself. If a suggestion is highlighted through keyboard navigation, Enter selects that suggestion and closes the suggestions.
Input field UpArrow or DownArrow Opens the suggestions when they are closed. When suggestions are open, moves the keyboard highlight to the previous or next suggestion while focus remains in the input. With autocomplete enabled, a prefix match can appear as an inline autocomplete preview, while a desktop partial match can appear as floating autocomplete text (for example, D – Edge). These autocomplete displays do not by themselves establish a keyboard highlight; UpArrow or DownArrow does. In collection mode on desktop, the first press opens the collection popup and the next press moves focus into the collection.
Input field Esc Closes the suggestions when they are open. If suggestions are closed, does nothing.
Input field with inline autocomplete preview (prefix match) LeftArrow or RightArrow Accepts the inline autocomplete preview. LeftArrow places the caret at the start of the suggested suffix, and RightArrow places the caret at the end.
Input field with inline autocomplete preview (prefix match) Backspace or Delete Dismisses the inline autocomplete preview and keeps the user-entered text.
Input field Tab Moves focus to the next tabbable element. If suggestions are open, closes them without submitting a new search. Tabbing can blur the field, which may update value and rawValue to the current displayed value, including an autocomplete preview, but it does not fire ojValueAction.
Collection Shift + Tab When focus is on the first tabbable item, closes the collection, restores the typed search text, and moves focus to the previous tabbable page element. Otherwise, follows the collection's own focus order.


Usage

Signature:

interface CInputSearchElement<K extends oj-c.InputSearch.Key,D extends Data>

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

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

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.


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.

collectionTemplate

Note: When the template is executed for each item, it will have access to the binding context containing the following properties: oj-c.InputSearch.InputSearchCollectionTemplateContext

The collectionTemplate slot is used to specify the template for rendering suggestions in collection mode. The slot must be a <template> element containing a child core-pack collection element (e.g. <oj-c-table/> or <oj-c-list-view/>).

When provided, collectionTemplate takes precedence over suggestionItemTemplate. Collection mode currently supports DataProvider-backed suggestions only.

The collectionTemplate supports oj-c-table and oj-c-list-view.

Properties of $current:
Name Type Argument Description
currentRowOverride { rowKey: K; } <optional>
 Current focused row/item override for the rendered collection.
data DataProvider.<K, D> | null <optional>
 Data and metadata for the collection rendered by the template.
onCurrentRowChanged (detail: { rowKey?: K; }) => void Callback invoked when the rendered collection changes its current row.
onRowAction (detail: { item: Item<K, D>; }) => void Callback invoked when the user performs an action gesture on a row/item.
searchText string <optional>
 The text entered by the user for filtering the collection data.
selected ImmutableKeySet.<K> Selected row/item keys for the rendered collection.

suggestionItemTemplate

Note: When the template is executed for each item, it will have access to the binding context containing the following properties: oj-c.InputSearch.InputSearchSuggestionItemTemplateContext

The suggestionItemTemplate slot is used to specify the template for rendering each suggestion in the dropdown. The slot must be a <template> element.

When the template is executed for each suggestion, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current suggestion. (See the table below for a list of properties available on $current)
  • alias - if the data-oj-as attribute was specified on the template, the value will be used to provide an application-named alias for $current.

If no suggestionItemTemplate is specified, the component will render based on the value of the suggestionItemText property.

Properties of $current:
Name Type Argument Description
data D The data for the current suggestion.
index number The zero-based index of the current suggestion.
key K The key of the current suggestion.
metadata ItemMetadata.<K> The metadata for the current suggestion.
searchText string <optional>
 The search text entered by the user.

Attributes

autocomplete :"off"|"on"

Specifies whether suggestions can enable autocomplete typeahead preview. Prefix matches can preview the first suggestion inline. Desktop partial matches can also preview the first suggestion as floating text, but phones suppress floating autocomplete and keep non-prefix matches raw.
Default Value:
  • 'on'
Names
Item Name
Property autocomplete
Property change event autocompleteChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-autocomplete-changed

max-width :(number|string|"sm"|"md")

Specifies the component's max width. If unset, the default max width is 100%.
Supported Values:
Value
sm
md
Names
Item Name
Property maxWidth
Property change event maxWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-width-changed

placeholder :string

The placeholder text to set on the element. The placeholder specifies a short hint that can be displayed before the user selects or enters a value.
Names
Item Name
Property placeholder
Property change event placeholderChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-placeholder-changed

(readonly) raw-value :string

The rawValue is the read-only property for retrieving the current value from the input field in string form.

The rawValue updates on the 'input' javascript event, so the rawValue changes as the value of the input is changed. If the user types in '1,200' into the field, the rawValue will be '1', then '1,', then '1,2', ..., and finally '1,200'. Then when the user blurs, presses Enter, or selects a suggestion, the value property gets updated.

This is a read-only attribute so page authors cannot set or change it directly.

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

suggestion-item-text :keyof D|(itemContext: ojcommontypes.ItemContext<K, D>) => string

Specifies the text string to render for a suggestion. This property can be set to either:
  • a string that specifies the name of a top level data field whose value will be rendered as text, or
  • a callback function that takes a context object and returns the text string to display

By default, the component will attempt to render a 'label' data field as text.

This text will be rendered for the selected value of the component. It will also be rendered for each suggestion in the dropdown if no suggestionItemTemplate is provided. When rendered for the dropdown suggestions, default matching search term highlighting will still be applied. Field values other than null or undefined are converted to strings.

Names
Item Name
Property suggestionItemText
Property change event suggestionItemTextChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-suggestion-item-text-changed

suggestions :(Array.<D>|DataProvider.<K, D>|null)

Data for the InputSearch suggestions. This data is used to populate the list of suggestions in the dropdown or collection mode. When a user selects a suggestion from the dropdown, the ojValueAction event will contain the data for that suggestion. If no suggestions data is provided, then the dropdown will not be shown. Note that the InputSearch only shows up to a maximum of 12 suggestions in the dropdown even if there are more suggestions available in the data.

Suggestions can be supplied as a DataProvider or as an array of suggestion objects.

When collectionTemplate is provided, suggestions must be backed by a DataProvider.

Note that the suggestion-item-text attribute allows for customizing the rendering of each suggestion. If it is not specified, then the component will attempt to render as text the 'label' field in the suggestion by default.

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

value :(string|null)

The current value of the element. The value is updated when the user blurs the field, presses Enter, or selects a suggestion. However, blurring the field does not trigger an onOjValueAction.
Default Value:
  • null
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

variant :"standard"|"hero"

Specifies whether the field uses the standard or hero presentation.
Supported Values:
Value Description
standard Renders the default input search presentation.
hero Renders the larger hero search presentation.
Default Value:
  • 'standard'
Names
Item Name
Property variant
Property change event variantChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-variant-changed

width :(number|string|"sm"|"md")

Specifies the component's width. If unset, the default width is 100%. Note that by default max-width is 100%, which will override the width if the container is smaller than the width specified.
Supported Values:
Value
sm
md
Names
Item Name
Property width
Property change event widthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-width-changed

Events

ojValueAction

Note: The event detail contains the following properties: oj-c.InputSearch.InputSearchValueActionDetail<K, D>

Triggered when search text is explicitly submitted by the user, even if the text has not changed. Submission is triggered by the Enter key or by selecting a suggestion. Blurring the field updates value but does not trigger this event.

See Events and Listeners for additional information.

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

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.

InputSearchCollectionTemplateContext<K extends oj-c.InputSearch.Key = oj-c.InputSearch.Key,D extends Data = Data>

Context passed to the Core Pack collectionTemplate slot. The wrapper adapts Preact collection-mode callbacks to the row/current/selected contracts used by oj-c-table and oj-c-list-view.
Properties:
Name Type Argument Description
currentRowOverride { rowKey: K; } <optional>
 Current focused row/item override for the rendered collection.
data DataProvider.<K, D> | null <optional>
 Data and metadata for the collection rendered by the template.
onCurrentRowChanged (detail: { rowKey?: K; }) => void Callback invoked when the rendered collection changes its current row.
onRowAction (detail: { item: Item<K, D>; }) => void Callback invoked when the user performs an action gesture on a row/item.
searchText string <optional>
 The text entered by the user for filtering the collection data.
selected ImmutableKeySet.<K> Selected row/item keys for the rendered collection.

InputSearchSuggestionItemTemplateContext<K extends oj-c.InputSearch.Key = oj-c.InputSearch.Key,D extends Data = Data>

Properties:
Name Type Argument Description
data D The data for the current suggestion.
index number The zero-based index of the current suggestion.
key K The key of the current suggestion.
metadata ItemMetadata.<K> The metadata for the current suggestion.
searchText string <optional>
 The search text entered by the user.

InputSearchValueActionDetail<K extends oj-c.InputSearch.Key = oj-c.InputSearch.Key,D extends Data = Data>

Properties:
Name Type Argument Description
itemContext ItemContext<K, D> <optional>
 The data provider context for the search text, if available.
previousValue (string|null) <optional>
 The previous submitted search text.
value (string|null) The submitted search text.

Key