# Search Input Field

## Overview

<figure><img src="/files/HjspVwcptJQhOzP7scTY" alt=""><figcaption></figcaption></figure>

## Usage

### When to use this component?

Search fields are used in applications where users need to search for information, such as on websites, in databases, or in content-heavy applications. They are ideal for scenarios requiring quick and efficient information retrieval.

### How it works

A search field component typically includes a label, an input area for entering search queries, and optional elements like a clear button and helper text for guidance. It may also feature different states, such as focused, filled, or error, to reflect its current status. Search fields enable users to quickly locate specific information by entering keywords or phrases, streamlining their search experience.

### Code

{% tabs %}
{% tab title="Vanilla Js" %}

<pre class="language-jsx"><code class="lang-jsx"><strong>&#x3C;dda-search-input    
</strong>    placeholder="Search"
    label="Search"
    size="default"
    helper_text="Helper or footer text"
    error_message=""
    validation_id=""
    show_button="false"
    has_error="false"
    custom_class=""
    component_mode=""
    button_id="button"
    input_id="Search"
    aria_label="search-input"
    button_aria_label="clear-search"
    onchange=""
    search_input_name="search-input"
    close_button_name="close-button"
    search_button_name="search-button"
    button_text="Search"
    input_status="normal"
>&#x3C;/dda-search-input>
</code></pre>

{% endtab %}

{% tab title="React" %}

```jsx
<DdaSearchInput
    placeholder="Search"
    label="Search"
    size="default"
    helper_text="Helper or footer text"
    error_message=""
    validation_id=""
    show_button="false"
    has_error="false"
    custom_class=""
    component_mode=""
    button_id="button"
    input_id="Search"
    aria_label="search-input"
    button_aria_label="clear-search"
    onchange=""
    search_input_name="search-input"
    close_button_name="close-button"
    search_button_name="search-button"
    button_text="Search"
    input_status="normal"
></DdaSearchInput>
```

{% endtab %}

{% tab title="Vue" %}

```jsx
<DdaSearchInput
    placeholder="Search"
    label="Search"
    size="default"
    helper_text="Helper or footer text"
    error_message=""
    validation_id=""
    show_button="false"
    has_error="false"
    custom_class=""
    component_mode=""
    button_id="button"
    input_id="Search"
    aria_label="search-input"
    button_aria_label="clear-search"
    onchange=""
    search_input_name="search-input"
    close_button_name="close-button"
    search_button_name="search-button"
    button_text="Search"
    input_status="normal"
></DdaSearchInput>
```

{% endtab %}

{% tab title="Angular" %}

```jsx
<dda-search-input
    placeholder="Search"
    label="Search"
    size="default"
    helper_text="Helper or footer text"
    error_message=""
    validation_id=""
    show_button="false"
    has_error="false"
    custom_class=""
    component_mode=""
    button_id="button"
    input_id="Search"
    aria_label="search-input"
    button_aria_label="clear-search"
    onchange=""
    search_input_name="search-input"
    close_button_name="close-button"
    search_button_name="search-button"
    button_text="Search"
    input_status="normal"
></dda-search-input>
```

{% endtab %}
{% endtabs %}

### Properties

For version 3.12.0+ you can use the new unified [input interactions](/developers/input-interactions.md) to set/get data from the components.

| Property             | Description                                                                                                                                                                                                   | Type       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `placeholder`        | The placeholder text to be displayed inside the input field when it is empty. Default is "Search".                                                                                                            | `string`   |
| `label`              | The label text for the search input. This label is displayed above the input field.                                                                                                                           | `string`   |
| `size`               | Specifies the size of the input field. Default is 'sm' (small). Can be adjusted to other sizes like 'md' (medium) or 'lg' (large) depending on the desired appearance.                                        | `string`   |
| `helper_text`        | Text displayed below the input field to assist users, such as instructions or tips.                                                                                                                           | `string`   |
| `error_message`      | Custom error message displayed when the input field has an error. Appears below the input if `has_error` is `true`.                                                                                           | `string`   |
| `validation_id`      | Defines a unique identifier for the helper or error message element. This `id` can be referenced by form fields using `aria-describedby` or similar attributes to associate the supporting text with an input | `string`   |
| `show_button`        | A boolean flag to control the visibility of the "Search" button. If `true`, the button is shown; otherwise, it is hidden.                                                                                     | `boolean`  |
| `has_error`          | A boolean flag indicating whether the input field has an error. If `true`, it triggers error styling and the error message display.                                                                           | `boolean`  |
| `custom_class`       | A string of additional custom CSS classes that can be applied to the input container for further styling customization.                                                                                       | `string`   |
| `component_mode`     | An optional property for specifying a particular mode or variant of the component, which can be used to alter its appearance or behavior based on the context.                                                | `string`   |
| `button_id`          | The ID to be assigned to the button elements for accessibility and targeting purposes.                                                                                                                        | `string`   |
| `input_id`           | Specifies a unique identifier for the input element. This `id` can be used to associate labels or helper text with the input field and is useful for accessibility, scripting, and styling purposes.          | `string`   |
| `aria_label`         | The `aria-label` attribute for the search input element, used to enhance accessibility by providing a textual description.                                                                                    | `string`   |
| `button_aria_label`  | The `aria-label` attribute for the buttons in the component, which helps provide a clear description for screen readers.                                                                                      | `string`   |
| `onchange`           | JavaScript function to call when the input value changes.                                                                                                                                                     | `function` |
| `search_input_name`  | Name attribute for the search input field                                                                                                                                                                     | `string`   |
| `close_button_name`  | Name attribute for the close button                                                                                                                                                                           | `string`   |
| `search_button_name` | Name attribute for the search button                                                                                                                                                                          | `string`   |
| `button_text`        | Text displayed on the search button.                                                                                                                                                                          | `string`   |
| `input_status`       | Specifies the status of the input field, e.g., "valid" or "invalid". This can be used to apply custom styling based on the field’s state.                                                                     | `string`   |

## Anatomy

<figure><img src="/files/rDMQ7W3ogFiN2b7KsGD6" alt=""><figcaption></figcaption></figure>

### Anatomy Options

**Label**: Describes the function or purpose of the search field, here labeled as "Search."

**Lead-Icon**: An icon placed at the beginning of the input field, usually representing the action or purpose, like a magnifying glass for search.

**Placeholder**: Text that appears within the input field when it’s empty, providing a hint or example for what to type, such as "Search."

**Button**: A clickable element labeled "Search" that initiates the search action when pressed.

**Caption**: Additional helper or footer text below the field, providing more context or instructions to the user.

## Dos and Don'ts

| Dos                                                                              | Don'ts                                                                               |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Use search fields to allow users to quickly find specific information.           | Don't use search fields for inputs that are not related to search or query purposes. |
| Label the search field clearly to indicate its purpose.                          | Avoid using ambiguous or unclear labels for search fields.                           |
| Include a placeholder text to guide users on what to search for.                 | Don't rely solely on placeholder text for essential instructions.                    |
| Provide a clear button to allow users to quickly clear the search input.         | Don't omit the clear button if the search input field is long or complex.            |
| Ensure the search field is large enough to be easily tappable or clickable.      | Avoid making the search field too small to interact with comfortably.                |
| Use helper text to provide additional context or instructions, if necessary.     | Don't overload the search field with too much information.                           |
| Validate input and provide clear error messages when necessary.                  | Don't provide generic error messages that don't help users understand the issue.     |
| Keep consistent styling and spacing across all search fields in the application. | Don't use inconsistent styles that may confuse users.                                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://designsystem.dubai.ae/components/search-input-field.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.