Perdana Autocomplete is a plug-and-play React component for an input with a suggestion list. It works in controlled or uncontrolled mode and can render an optional action button.

Installation

npm install perdana-autocomplete
# react and react-dom must already be installed (peer dependencies)

Quick Start

import { useState } from 'react'
import PerdanaAutoComplete from 'perdana-autocomplete'

const people = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' },
]

export default function Example() {
  const [value, setValue] = useState('')

  return (
    <PerdanaAutoComplete
      id="people-search"
      list={people}
      placeholder="Search people"
      value={value} // omit for uncontrolled mode
      onChange={setValue}
      onSelect={(item) => console.log('Selected:', item)}
      withButton={{
        text: 'Search',
        position: 'right',
        backgroundColor: '#007BFF',
        textColor: '#fff',
        onClick: (_id, currentValue) => console.log('Search click', currentValue),
      }}
    />
  )
}

API Props

• id (string, default: "perdana-auto-complete"): id applied to the input.
• list (Array<{ id?: string|number, name: string }>): suggestion source. Filtering is substring, case-insensitive, against name.
• placeholder (string): input placeholder text.
• value (string) and onChange(value, event) (function): provide both for controlled mode. If value is omitted, the component runs uncontrolled.
• onSelect(item) (function): fired when a suggestion is chosen.
• debounce (number, default: 500 ms): wait time before filtering.
• minChars (number, default: 0): minimum characters before suggestions show.
• renderSuggestion(item, { query }) (function): custom renderer for each suggestion row.
• emptyMessage (string, default: "No results found"): text when there are no matches.
• className, style: forwarded to the outer container.
• inputProps (object): extra props for the <input> (e.g., name, aria-*, etc.).

withButton options

Render a button to the left or right of the input by passing an object:

• text (string): button label (ignored if iconSrc is provided).
• iconSrc, iconAlt: optional icon.
• position (left|right, default: right): button position.
• backgroundColor, textColor, style: button style overrides.
• id, className: attributes for <button>.
• onClick(id, value): callback when clicked, receives the input id and current value.

Behavior & Styling

• Filtering is debounced (default 500 ms), substring, case-insensitive against item.name.
• Dropdown closes on blur; clicking a suggestion or the button will not steal focus thanks to preventDefault on mousedown.
• Available CSS hooks:
  • .pg-cont (outer flex container)
  • .pg-input-wrapper (input + dropdown wrapper)
  • .pg-inp-auto-comp (input)
  • .pg-suggest-cont (suggestion list, absolutely positioned)
  • .pg-suggestion-item (suggestion row)
  • .pg-empty-state (“no results” row)
• Base styles are injected automatically via the bundle (style-loader), so you do not need to import CSS separately. You can still override with your own CSS.

Custom Rendering Example

<PerdanaAutoComplete
  list={people}
  renderSuggestion={(item) => (
    <span>
      {item.name} <small style={{ color: '#888' }}>id: {item.id}</small>
    </span>
  )}
/>;

Development Scripts

• npm run dev — Runs the React demo playground (src/demo.jsx) at http://localhost:3000.
• npm run build — Produces the UMD bundle at dist/index.js for consumption by other React apps or for publishing.