Import
import { SearchBoxModule } from '@backbase/ui-ang/search-box'
Usage
Use the bb-search-box-ui component to provide search functionality. The component supports both simple search and typeahead functionality with customizable search and clear buttons.
<!-- Basic search box usage -->
<bb-search-box-ui
[placeholder]="'Search for items...'"
(submit)="onSearch($event)">
</bb-search-box-ui>
Inputs
|
Input |
Type |
Default |
|---|---|---|
|
autocomplete |
string |
'off' |
|
autofocus |
boolean |
false |
|
clearLabel |
string |
'Clear' |
|
disabled |
boolean |
false |
|
id |
string |
Auto-generated unique string |
|
inputClassName |
string |
undefined |
|
label |
string |
'' |
|
maxLength |
string |
'140' |
|
placeholder |
string |
'' |
|
readonly |
boolean |
false |
|
required |
boolean |
false |
|
searchLabel |
string |
'Search' |
|
showClear |
boolean |
false |
|
showSearch |
boolean |
false |
|
size |
number | string |
20 |
|
squareBorder |
boolean |
false |
|
typeaheadOptions |
TypeaheadOptions<T> |
undefined |
autocomplete
The autocomplete input sets the autocomplete attribute value for the search input, controlling browser autocomplete behavior.
<!-- Search box with autocomplete enabled -->
<bb-search-box-ui [autocomplete]="'on'">
</bb-search-box-ui>
autofocus
The autofocus input determines whether the search box should be automatically focused when the component is rendered.
<!-- Search box with autofocus enabled -->
<bb-search-box-ui [autofocus]="true">
</bb-search-box-ui>
clearLabel
The clearLabel input sets the aria-label text for the clear button, providing accessible text for screen readers when the clear button is focused.
<!-- Search box with custom clear button label -->
<bb-search-box-ui
[showClear]="true"
[clearLabel]="'Clear search'">
</bb-search-box-ui>
disabled
The disabled input determines whether the search box is disabled and non-interactive. When disabled, users cannot interact with the input or buttons.
<!-- Disabled search box -->
<bb-search-box-ui [disabled]="true">
</bb-search-box-ui>
id
The id input sets a unique identifier for the search input element. If not provided, an auto-generated unique string is used.
<!-- Search box with custom ID -->
<bb-search-box-ui [id]="'product-search'">
</bb-search-box-ui>
inputClassName
The inputClassName input allows you to add custom CSS classes to the search input element for additional styling.
<!-- Search box with custom input classes -->
<bb-search-box-ui [inputClassName]="'custom-search-input'">
</bb-search-box-ui>
label
The label input sets the visible label text displayed above the search box to describe its purpose.
<!-- Search box with custom label -->
<bb-search-box-ui [label]="'Product Search'">
</bb-search-box-ui>
maxLength
The maxLength input sets the maximum number of characters allowed in the search input.
<!-- Search box with custom max length -->
<bb-search-box-ui [maxLength]="'100'">
</bb-search-box-ui>
placeholder
The placeholder input sets the placeholder text displayed when the search box is empty, providing guidance to users about what to search for.
<!-- Search box with custom placeholder -->
<bb-search-box-ui [placeholder]="'Enter product name or SKU...'">
</bb-search-box-ui>
readonly
The readonly input sets the search box to read-only mode, where the value can be viewed but not modified. Search and clear buttons are disabled in this mode.
<!-- Read-only search box -->
<bb-search-box-ui [readonly]="true">
</bb-search-box-ui>
required
The required input indicates whether the search box content is required for form validation. When true, empty content will trigger validation errors.
<!-- Required search box -->
<bb-search-box-ui [required]="true">
</bb-search-box-ui>
searchLabel
The searchLabel input sets the aria-label text for the search button, providing accessible text for screen readers when the search button is focused.
<!-- Search box with custom search button label -->
<bb-search-box-ui
[showSearch]="true"
[searchLabel]="'Search products'">
</bb-search-box-ui>
showClear
The showClear input determines whether to display the clear button icon after the search text. The button only appears when there is content to clear.
<!-- Search box with clear button -->
<bb-search-box-ui [showClear]="true">
</bb-search-box-ui>
showSearch
The showSearch input determines whether to display the search button icon before the search text.
<!-- Search box with search button -->
<bb-search-box-ui [showSearch]="true">
</bb-search-box-ui>
size
The size input configures the minimum width to fit the specified number of characters, similar to the HTML input size attribute.
<!-- Search box with custom size -->
<bb-search-box-ui [size]="30">
</bb-search-box-ui>
squareBorder
The squareBorder input controls the border styling of the search box.
<!-- Search box with square border -->
<bb-search-box-ui [squareBorder]="true">
</bb-search-box-ui>
typeaheadOptions
The typeaheadOptions input provides configuration for typeahead functionality, enabling autocomplete suggestions as users type.
<!-- Search box with typeahead -->
<bb-search-box-ui [typeaheadOptions]="searchTypeaheadOptions">
</bb-search-box-ui>
Outputs
|
Output |
Type |
Description |
|---|---|---|
|
blur |
EventEmitter<FocusEvent | void> |
Fired when the search box loses focus |
|
clear |
EventEmitter<string> |
Fired when the clear button is clicked |
|
focus |
EventEmitter<FocusEvent | void> |
Fired when the search box receives focus |
|
submit |
EventEmitter<string | boolean | Object | null> |
Fired when a search is submitted via enter key or search button |
|
valueChange |
EventEmitter<any> |
Fired when the value in the search box is changed |
Data models
TypeaheadOptions<T>
Interface for configuring typeahead functionality.
interface TypeaheadOptions<T> {
ngbTypeahead: (text: Observable<string>) => Observable<Array<T>>;
editable?: boolean;
focusFirst?: boolean;
showHint?: boolean;
placement?: string;
inputFormatter?: (item: T) => string;
resultFormatter?: (item: T) => string;
resultTemplate?: TemplateRef<any>;
selectItem?: (item: NgbTypeaheadSelectItemEvent) => void;
groupCssClasses?: string;
}
Form integration
The search box component implements ControlValueAccessor, making it fully compatible with Angular reactive forms and template-driven forms.
// Reactive forms example
this.searchForm = this.formBuilder.group({
query: ['', Validators.required]
});
<!-- Template integration -->
<form [formGroup]="searchForm">
<bb-search-box-ui
formControlName="query"
[label]="'Search Query'"
[showSearch]="true"
[showClear]="true">
</bb-search-box-ui>
</form>
Accessibility
This component is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
- ARIA labels: Proper ARIA labeling for the search input and action buttons
- Keyboard navigation: Full keyboard support including Enter key for search submission
- Screen reader support: Search actions and state changes are announced to assistive technologies
- Focus management: Clear focus indicators and logical focus flow
- Button accessibility: Search and clear buttons include appropriate aria-label attributes
- Container roles: Proper search landmark role for the container element
- Typeahead accessibility: When enabled, typeahead results include proper listbox roles and navigation
ARIA
These inputs support WAI-ARIA compliance and are intended to improve accessibility for users relying on assistive technologies. Use them to provide meaningful semantic information for the component when additional context is needed to convey its purpose, state, or behavior.
|
Input |
Description |
Type |
|---|---|---|
|
aria-activedescendant |
Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application |
string |
|
aria-autocomplete |
Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox |
string |
|
aria-controls |
Indicates which element or elements the user interface widget controls |
string |
|
aria-describedby |
References the ID of an element that contains a detailed description of the search box |
string |
|
aria-expanded |
Indicates if a control is expanded or collapsed, and whether or not its child elements are displayed or hidden |
string |
|
aria-invalid |
Indicates the entered value is not in a format expected by the application |
string |
|
aria-label |
Sets the accessible label for the search input when no visible label is present |
string |
|
aria-labelledby |
References the ID of an element that labels the search input |
string |
|
aria-owns |
Identifies an element (or elements) to define a visual, functional, or contextual relationship between a parent and its child elements when the DOM hierarchy cannot be used |
string |
|
containerAriaLabel |
Sets the aria-label for the search container. When there are multiple search inputs on a page, this should be assigned to distinguish between them |
string |
|
containerRole |
Sets the role attribute for the search container. For non-landmarked search functionality, this should be assigned a value |
string |
|
role |
Customizes the ARIA role for the search input element. Automatically set to 'searchbox' for simple search or 'combobox' for typeahead |
string |
The component automatically handles focus management, keyboard interactions, and provides appropriate feedback to screen readers. When typeahead is enabled, it includes comprehensive support for listbox navigation and selection announcement.