# Bootstrap 5 Search Button

> Bootstrap Search Button for CoreUI is a keyboard-aware trigger component that can open search interfaces, modals, offcanvas panels, and custom flows from click or shortcut.

## Overview

The CoreUI **Bootstrap Search Button component** is a trigger element designed for search entry points and command-style actions. It behaves like a regular button on click, but it can also react to a configurable keyboard shortcut such as `meta+/` or `ctrl+/`.

- Use it as a standalone trigger for a custom search UI.
- Combine it with `data-coreui-toggle` and `data-coreui-target` to open a modal or offcanvas.
- Shortcut keys are rendered automatically.
- Displayed shortcut keys react to keyboard interaction and receive an `.active` state while pressed.

## Basic example

Use `.search-button` together with `data-coreui-search-button`. The keyboard shortcut keys are generated automatically by JavaScript. Because the component dispatches a real `click()` when the configured shortcut matches, it works with CoreUI data APIs such as modal, offcanvas, or collapse triggers.

```html
<button type="button" class="search-button" data-coreui-search-button>
  <svg class="search-button-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" aria-hidden="true">
    <path fill="currentcolor" d="..."/>
  </svg>
  <span class="search-button-placeholder">Search</span>
</button>
```

## Custom shortcut

Configure the shortcut with `data-coreui-shortcut`. On macOS, the component prefers the `meta` variant for the visual label. On Windows and Linux, it prefers the `ctrl` variant.

> Shortcuts such as `meta+f`, `ctrl+f`, `meta+s`, or `ctrl+s` can override native browser or system shortcuts. Prefer safer combinations such as `meta+/` and `ctrl+/` unless replacing the default behavior is intentional.

```html
<button type="button" class="search-button" data-coreui-search-button data-coreui-shortcut="meta+i,ctrl+i">
  <svg class="search-button-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" aria-hidden="true">
    <path fill="currentcolor" d="..."/>
  </svg>
  <span class="search-button-placeholder">Command palette</span>
</button>
```

## Launch an offcanvas

Because the component dispatches a real `click()` when the configured shortcut matches, it works with CoreUI data APIs such as modal, offcanvas, or collapse triggers. This demo uses `meta+shift+o` / `ctrl+shift+o` to avoid colliding with other live examples on the page.

```html
<button
  type="button"
  class="search-button"
  data-coreui-search-button
  data-coreui-shortcut="meta+shift+o,ctrl+shift+o"
  data-coreui-toggle="offcanvas"
  data-coreui-target="#searchButtonOffcanvas"
  aria-controls="searchButtonOffcanvas"
>
  <svg class="search-button-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" aria-hidden="true">
    <path fill="currentcolor" d="..."/>
  </svg>
  <span class="search-button-placeholder">Search</span>
</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="searchButtonOffcanvas" aria-labelledby="searchButtonOffcanvasLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="searchButtonOffcanvasLabel">Search panel</h5>
    <button type="button" class="btn-close" data-coreui-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <input type="search" class="form-control mb-3" placeholder="Search...">
    <p class="mb-0">Use this space for filters, recent searches, or command shortcuts.</p>
  </div>
</div>
```

## Keyboard behavior

### When the configured shortcut is pressed

| Key | Action |
| --- | --- |
| `Enter` / `Space` on a focused search button | Trigger the same action as a pointer click |
| Configured shortcut, e.g. `⌘/` / `Ctrl+/` | Trigger the same action as a pointer click |
| Modifier key inside the visible shortcut | Add `.active` to the corresponding `.search-button-key` while pressed |
| Final key inside the visible shortcut | Add `.active` to the corresponding `.search-button-key` while pressed |

### Keyboard state behavior

| Interaction | Effect |
| --- | --- |
| Matching shortcut on `keydown` | Optionally prevents the browser's default behavior and dispatches the component trigger |
| Plain typing inside `input`, `textarea`, `select`, or `contenteditable` | Does not trigger the component without `meta` or `ctrl` |
| `keyup` after a shortcut key press | Removes `.active` from the rendered shortcut keys |
| Browser window `blur` | Clears all active shortcut key states |
| Multiple configured shortcuts | The component listens to all configured shortcuts and renders the platform-preferred one in the UI |

## Accessibility

Accessibility is an important part of the Search Button design. The component includes built-in behaviors that help preserve expected keyboard interaction and reduce conflicts with assistive technologies, but accessible results still depend on choosing the right markup and shortcut combinations.

### Built-in accessibility behavior

- Native button semantics are preserved when the component is used on a `<button type="button">`.
- Rendered `.search-button-keys` are treated as visual hints only and are hidden from assistive technologies.
- Plain typing inside editable fields does not trigger the component unless the shortcut also includes `meta` or `ctrl`.
- The component keeps standard button keyboard behavior such as `Enter` and `Space`.

### Author responsibilities

- Use a native `<button type="button">` element so the component keeps expected focus behavior and keyboard interaction.
- Mark decorative icons with `aria-hidden="true"` when they do not contribute to the accessible name.
- Choose shortcuts carefully and avoid overriding common browser or system shortcuts unless that behavior is intentional and clearly communicated.
- Make sure the visible button label clearly describes the action, for example `Search`, `Open search`, or `Command palette`.

## Usage

Initialize the CoreUI Search Button component via data attributes or JavaScript. The component automatically creates a shortcut key container and renders the visible shortcut keys based on the configured shortcut.

### Data attributes

Use `data-coreui-search-button` to enable the plugin. Configure behavior with `data-coreui-*` options.

```html
<button
  type="button"
  class="search-button"
  data-coreui-search-button
  data-coreui-shortcut="meta+/,ctrl+/"
  data-coreui-toggle="modal"
  data-coreui-target="#searchButtonModal"
>
  <svg class="search-button-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" aria-hidden="true">
    <path fill="currentcolor" d="..."/>
  </svg>
  <span class="search-button-placeholder">Search</span>
</button>
```

### Via JavaScript

```js
const searchButton = document.querySelector('[data-coreui-search-button]')

new coreui.SearchButton(searchButton, {
  shortcut: 'meta+i,ctrl+i'
})
```

### Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `preventDefault` | `boolean` | `true` | Prevents the browser's default behavior when the configured shortcut matches. |
| `shortcut` | `string` | `'meta+/,ctrl+/'` | Comma-separated shortcut list. The component matches all configured shortcuts and prefers the platform-appropriate one for rendering. Plain typing inside editable fields is ignored unless the shortcut also includes `meta` or `ctrl`. |

### Methods

| Method | Description |
| --- | --- |
| `trigger()` | Triggers the `trigger.coreui.search-button` event manually. |

```js
const element = document.querySelector('[data-coreui-search-button]')
const searchButton = coreui.SearchButton.getOrCreateInstance(element)

searchButton.trigger()
```

### Events

| Event | Description |
| --- | --- |
| `trigger.coreui.search-button` | Fired when the component is activated by click, API call, or keyboard shortcut. |

```js
const element = document.querySelector('[data-coreui-search-button]')

element.addEventListener('trigger.coreui.search-button', () => {
  // do something
})
```

## Customizing

### CSS variables

Search buttons use local CSS variables on `.search-button` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

```scss
--cui-search-button-height: #{$search-button-height};
--cui-search-button-padding-x: #{$search-button-padding-x};
--cui-search-button-font-family: #{$search-button-font-family};
--cui-search-button-font-size: #{$search-button-font-size};
--cui-search-button-font-weight: #{$search-button-font-weight};
--cui-search-button-color: #{$search-button-color};
--cui-search-button-bg: #{$search-button-bg};
--cui-search-button-border-width: #{$search-button-border-width};
--cui-search-button-border-color: #{$search-button-border-color};
--cui-search-button-border-radius: #{$search-button-border-radius};
--cui-search-button-box-shadow: #{$search-button-box-shadow};
--cui-search-button-transition: #{$search-button-transition};
--cui-search-button-focus-color: #{$search-button-focus-color};
--cui-search-button-focus-bg: #{$search-button-focus-bg};
--cui-search-button-focus-border-color: #{$search-button-focus-border-color};
--cui-search-button-focus-box-shadow: #{$search-button-focus-box-shadow};
--cui-search-button-icon-size: #{$search-button-icon-size};
--cui-search-button-keys-gap: #{$search-button-keys-gap};
--cui-search-button-key-width: #{$search-button-key-width};
--cui-search-button-key-height: #{$search-button-key-height};
--cui-search-button-key-padding-inline: #{$search-button-key-padding-inline};
--cui-search-button-key-font-size: #{$search-button-key-font-size};
--cui-search-button-key-bg: #{$search-button-key-bg};
--cui-search-button-key-border-radius: #{$search-button-key-border-radius};
--cui-search-button-key-active-bg: #{$search-button-key-active-bg};
--cui-search-button-placeholder-margin-inline: #{$search-button-placeholder-margin-inline};
```

### SASS variables

```scss
$search-button-height:              $input-height !default;
$search-button-padding-x:           $input-padding-x !default;
$search-button-font-family:         $input-font-family !default;
$search-button-font-size:           $input-font-size !default;
$search-button-font-weight:         $input-font-weight !default;
$search-button-color:               $input-placeholder-color !default;
$search-button-bg:                  $input-bg !default;
$search-button-border-width:        $input-border-width !default;
$search-button-border-color:        $input-border-color !default;
$search-button-border-radius:       $input-border-radius !default;
$search-button-box-shadow:          $input-box-shadow !default;
$search-button-transition:          $input-transition !default;

$search-button-focus-color:         $input-focus-color !default;
$search-button-focus-bg:            $input-focus-bg !default;
$search-button-focus-border-color:  $input-focus-border-color !default;
$search-button-focus-box-shadow:    $input-focus-box-shadow !default;

$search-button-icon-size:           1.125rem !default;

$search-button-keys-gap:            .25rem !default;
$search-button-key-width:           1.5rem !default;
$search-button-key-height:          1.5rem !default;
$search-button-key-padding-inline:  .25rem !default;
$search-button-key-font-size:       .75rem !default;
$search-button-key-bg:              var(--cui-tertiary-bg) !default;
$search-button-key-border-radius:   var(--cui-border-radius-sm) !default;
$search-button-key-active-bg:       var(--cui-secondary-bg) !default;

$search-button-placeholder-margin-inline:  .55rem 2rem !default;
```