Smart Search Web Component

A reusable Smart Search component built using Lit (Web Components). Supports dynamic search, filtering, keyboard navigation, accessibility, and flexible theming.

Features

• Interactive search with debounce
• Dynamic dropdown results
• Filter options (All, Accounts, Customers, Transactions)
• Full keyboard navigation (Arrow keys, Enter, Escape)
• Highlight matched text
• Accessibility support (ARIA roles, screen reader friendly)
• Shadow DOM for style isolation
• Event-based communication with parent apps
• Lightweight and framework-independent
• Built-in light and dark theme support
• Custom theming using CSS variables

Installation

Clone the repository:

git clone <your-repo-url>
cd smart-search
npm install

Development

Run the development server:

npm run dev

Open in browser:

http://localhost:5173

Build

Build the component for production:

npm run build

Output:

dist/smart-search.js

Testing

Run tests using Vitest:

npm test

Tests cover:

• Component rendering
• User interactions (typing, click)
• Keyboard navigation
• Event communication
• Edge cases (no results, disabled state)

Usage

In HTML

<script type="module" src="./dist/smart-search.js"></script>

<smart-search placeholder="Search users..."></smart-search>

In React

import { useEffect, useRef } from 'react';
import 'smart-search';

function App() {
  const ref = useRef(null);

  useEffect(() => {
    const el = ref.current;

    const handler = (e) => console.log(e.detail);

    el.addEventListener('search-change', handler);

    return () => el.removeEventListener('search-change', handler);
  }, []);

  return <smart-search ref={ref}></smart-search>;
}

In Angular

import 'smart-search';

<smart-search></smart-search>

Properties (Props)

| Property | Type | Default | Description | | --------------- | ------- | ----------- | ------------------------------ | | placeholder | string | "Search..." | Input placeholder text | | debounceTime | number | 500 | Delay before search triggers | | disabled | boolean | false | Disables input field | | value | string | "" | Controlled input value | | enableHighlight | boolean | false | Highlight matched text | | theme | string | "light" | Theme mode ("light" or "dark") |

Events

| Event | Description | Payload | | ------------- | ------------------------- | ---------------- | | search-change | Fired when user types | { query, value } | | result-select | Fired when item selected | SearchItem | | filter-change | Fired when filter changes | { filter } |

Theming

The component supports flexible theming using CSS variables.

Default (Light Theme)

The component uses a default theme internally:

export const defaultTheme = css`
  :host {
    --input-bg: white;
    --text-color: black;
    --border-color: #ccc;
    --dropdown-bg: white;
    --hover-bg: #f5f5f5;
    --active-bg: #dbeafe;
    --muted-text: gray;
    --error-color: red;
    --btn-bg: white;
    --highlight-bg: yellow;
  }
`;

Dark Theme (Using Prop)

You can enable dark mode using the theme property:

<smart-search theme="dark"></smart-search>

Internally, the component applies:

:host([theme="dark"]) {
  --input-bg: #1f2937;
  --text-color: #f9fafb;
  --border-color: #374151;
  --dropdown-bg: #111827;
  --hover-bg: #374151;
  --active-bg: #2563eb;
  --muted-text: #9ca3af;
  --error-color: #f87171;
  --btn-bg: #1f2937;
  --highlight-bg: #facc15;
}

Custom Theme Override (Recommended)

Users can override theme values directly using CSS variables:

<smart-search
  style="
    --input-bg: red;
    --text-color: white;
    --dropdown-bg: black;
  "
></smart-search>

CSS-based Override

smart-search.custom-theme {
  --input-bg: #222;
  --text-color: #eee;
}

<smart-search class="custom-theme"></smart-search>

Optional Theme Files

You can optionally maintain separate theme files for reuse:

default-theme.ts

export const defaultTheme = css`
  :host {
    --input-bg: white;
    --text-color: black;
  }
`;

dark-theme.ts

export const darkTheme = css`
  :host {
    --input-bg: #1f2937;
    --text-color: #f9fafb;
  }
`;

Note: These files are optional and mainly useful for design system consistency.

Data Structure

type SearchItem = {
  id: string;
  type: 'account' | 'customer' | 'transaction';
  label: string;
  subtitle?: string;
  meta?: string;
  disabled?: boolean;
  raw?: unknown;
};

Architecture

The component follows separation of concerns:

• Component (smart-search.ts) UI rendering, state management, event handling

• Service (smart-search.service.ts) Data fetching and filtering logic

• Utils (smart-search.utils.ts) Helper functions such as highlighting

• Styles (smart-search.styles.ts) Encapsulated component styles

Project Structure

src/
  data/
    mockData.ts
  utils/
    types.ts 
  theme/
    default-theme.ts
    dark-theme.ts
  component/
    __test__/
      smart-search.test.ts
    smart-search.ts
    smart-search.styles.ts
    smart-search.service.ts
    smart-search.utils.ts
  index.ts
  index.css
index.html
vite.config.ts
package.json
README.md

Future Improvements

• Async API integration
• Virtualized list for large data
• Advanced accessibility

Author

Ahamed Faizal