Dropdown Component

A customizable React dropdown with searchable options. The field displays the selected option's text and stores its value internally.

Estilos

O CSS está incluído no JavaScript do pacote e é adicionado automaticamente à página no navegador. Basta importar o componente, sem importar CSS separado. Ao atualizar, remova imports manuais de CSS deste pacote.

Em aplicações com SSR, os estilos são adicionados quando o JavaScript executa no navegador; não são incluídos automaticamente no HTML gerado pelo servidor.

Installation

Use the package manager npm:

npm install @tevui/dropdown

Props

The Dropdown component accepts the following properties.

| Prop | Type | Required | Default | Description | | ---------------- | ------------------------------------------------------ | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | dataTestId | string | No | "tevui-input-datatestid" | Sets the wrapper's data-testid attribute. | | disabled | boolean | No | false | Disables the field and prevents opening or selecting options. | | required | boolean | Yes | true at runtime | Requires a non-empty selected value. Validation runs when the main field loses focus and when an option is selected. | | label | string | Yes | � | Visible label associated with the main field. | | labelSize | number | No | 14 | Label font size in pixels. | | baseColor | string | No | "#545454" | CSS color for the label and border. | | baseColorError | string | No | "#f53434" | CSS color for the label, border, and error message when an error is present. | | inputSize | number | No | Inherited from CSS | Main field font size in pixels. | | borderRadius | number | No | 0 | Wrapper border radius in pixels. | | id | string | No | Generated with React useId() | Wrapper ID, also used to derive the input and options panel IDs. Supply a unique value. | | ariaLabel | string | No | � | Accessible label for the main field; also applied to the visible label element. | | onClick | (event: React.MouseEvent<HTMLInputElement>) => void | No | � | Called when the main field is clicked. | | onChange | (event: React.ChangeEvent<HTMLInputElement>) => void | No | � | Called when the search text changes. event.target.value contains the search query. Selecting an option does not call this callback. | | onBlur | (event: React.FocusEvent<HTMLInputElement>) => void | No | � | Called when the main field loses focus, after validation. | | tip | DropdownTextProp | No | � | Helper message shown below the field when there is no error. | | error | DropdownErrorProp | No | � | Error message shown below the field. Overrides internal validation errors and hides the tip. | | options | DropdownItemProp[] | Yes | � | Available options. Search matches part of text, ignoring letter case. | | value | string | No | undefined | Initial selected value, matched against option.value. Read only when the component mounts; subsequent prop changes do not update the selection. |

required is mandatory in the TypeScript interface even though the implementation provides a runtime default.

Option and message types

import type {
  DropdownItemProp,
  DropdownTextProp,
  DropdownErrorProp,
} from "@tevui/dropdown";

// DropdownItemProp
// { id: string; text: string; value: string }
// id: unique option key
// text: displayed label and searchable text
// value: internally stored selection

// DropdownTextProp and DropdownErrorProp
// { text: string; size: number }
// text: message content
// size: font size in pixels

Usage

"use client";

import { Dropdown } from "@tevui/dropdown";
import type { DropdownItemProp } from "@tevui/dropdown";

const fruits: DropdownItemProp[] = [
  { id: "banana", text: "Banana", value: "banana" },
  { id: "apple", text: "Apple", value: "apple" },
  { id: "avocado", text: "Avocado", value: "avocado" },
];

export default function ExampleComponent() {
  return (
    <Dropdown
      id="fruit"
      label="Fruit"
      required={true}
      options={fruits}
      value="apple"
      labelSize={14}
      inputSize={16}
      borderRadius={8}
      baseColor="#545454"
      baseColorError="#f53434"
      tip={{ text: "Choose a fruit", size: 12 }}
      onChange={(event) => {
        console.log("Search query:", event.target.value);
      }}
    />
  );
}

This example initially displays Apple and stores apple internally. Click the field to open the options and type ap in the search field to show only Apple. Selecting an option updates the displayed text and stored value, then closes the panel. Clicking outside or pressing Escape also closes it.