Dropdown Component

Description

The Dropdown component is a customizable dropdown component with built-in dark mode support and flexible styling options. It supports single and multiple selection, search functionality, and custom value input.

Installation

To use the Dropdown component in your project, you can install it via npm (or include it as part of your component library):

npm install custom-headless-dropdown@latest

Usage

Here's a simple example of how to use the Dropdown component in your application:

import React, { useState } from "react";
import Dropdown from "custom-headless-dropdown";

const App = () => {
  const [value, setValue] = useState("");

  const options = [
    { value: "yes", label: "Yes" },
    { value: "no", label: "No" },
    { value: "unsure", label: "Unsure" },
    { value: "na", label: "Not applicable" },
  ];

  const handleChange = (selectedValue) => {
    setValue(selectedValue);
  };

  return (
    <div>
      <Dropdown
        label="Please select a value"
        id="example-dropdown"
        options={options}
        value={value}
        onChange={handleChange}
        placeholder="Select an option"
        allowCustom={true}
        multiple={false}
        hideSearch={false}
      />
    </div>
  );
};

export default App;

Example with Hidden Search

Here's an example of a dropdown with the search functionality disabled:

<Dropdown
  label="Select a country"
  id="country-dropdown"
  options={countryOptions}
  value={selectedCountry}
  onChange={setSelectedCountry}
  placeholder="Choose a country"
  hideSearch={true}
/>

Props

Dropdown Props

| Prop | Type | Default | Description | | --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | label | React.ReactNode | - | Label to assign to the field. | | id | string | - | Unique identifier for the dropdown. | | options | Array<{value: string, label: string}> | - | An array of options to display in the dropdown. | | value | string or Array<string> | - | Variable that holds the selected item(s) from the dropdown | | onChange | function | - | A callback function that is called to save the dropdown selection | | onBlur | function | - | Callback function called when dropdown loses focus (optional) | | placeholder | string | - | Placeholder for the dropdown (optional) | | required | boolean | - | Whether the field is required (optional) | | icon | React.ReactNode | - | Icon to display in the dropdown button (optional) | | className | string | - | Additional CSS classes for the dropdown button (optional) | | allowCustom | boolean | false | Whether to allow custom value input (optional) | | multiple | boolean | false | Whether to accept multi option selection (optional) | | hideSearch | boolean | false | Whether to hide the search input (optional) | | buttonClass | string | "border-white/10 bg-white/5 text-white" | Custom styling for the dropdown button | | dropdownClass | string | "bg-white dark:bg-background dark:border-white/10" | Custom styling for the dropdown menu | | optionClass | string | "text-black hover:bg-gray-50 dark:text-white dark:hover:bg-white/5" | Custom styling for dropdown options | | selectedOptionClass | string | "bg-gray-50 text-black dark:bg-purple/20 dark:text-purple" | Custom styling for selected options | | tagClass | string | "dark:bg-purple/20 dark:text-purple bg-gray-50 text-black" | Custom styling for multi-select tags | | searchInputClass | string | "bg-white/5 border-white/10 dark:text-white text-black placeholder-gray-400" | Custom styling for search input | | labelClass | string | "font-bold" | Custom styling for the label | | textColor | string | "text-white" | Custom text color | | placeholderColor | string | "text-gray-400" | Custom placeholder text color | | focusRingColor | string | "dark:focus:ring-purple dark:focus:border-purple focus:ring-background focus:border-background" | Custom focus ring styling | | hoverColor | string | "dark:hover:border-purple/30 hover:border-background" | Custom hover styling |

Styling

The Dropdown component uses Tailwind CSS 4.1.11 with built-in dark mode support. The component automatically adapts to light and dark themes based on the presence of the dark class on a parent element.

Default Styling

The dropdown comes with sensible defaults that work in both light and dark modes:

• Light Mode: White background with gray borders and dark text
• Dark Mode: Dark background with subtle white borders and light text

Custom Styling

You can override any part of the dropdown's appearance by passing custom Tailwind classes:

<Dropdown
  label="Custom Styled Dropdown"
  options={options}
  value={value}
  onChange={setValue}
  buttonClass="border-blue-300 bg-blue-50 text-blue-900"
  dropdownClass="bg-blue-50 border-blue-300"
  optionClass="text-blue-900 hover:bg-blue-100"
  selectedOptionClass="bg-blue-200 text-blue-900"
  tagClass="bg-blue-200 text-blue-900"
/>

Dark Mode Setup

To enable dark mode, add the dark class to a parent element (typically <html> or <body>):

// Toggle dark mode
document.documentElement.classList.toggle("dark");

Example CSS Setup

If you haven't set up Tailwind CSS yet, here's a basic example:

1. Install Tailwind CSS:

npm install -D tailwindcss@^4.1.11 @tailwindcss/postcss@^4.1.11 postcss

2. Configure your postcss.config.js:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

3. Include Tailwind in your CSS file:

@import "tailwindcss";

Features

The dropdown component includes several advanced features:

• Single/Multiple Selection: Toggle between single and multiple selection modes
• Search Functionality: Built-in search to filter options
• Custom Values: Allow users to add custom values not in the options list
• Keyboard Navigation: Full keyboard support for accessibility
• Responsive Design: Works well on all screen sizes
• Dark Mode Support: Automatic theme switching
• Custom Styling: Complete control over appearance through props

Customization

The dropdown component is highly customizable through props. You can:

• Control the dropdown appearance using styling props
• Add custom icons and labels
• Enable/disable search and custom value input
• Switch between single and multiple selection modes
• Use the built-in dark mode support
• Override any styling with custom Tailwind classes