react-auto-complete

Description

A search auto-completer with dynamic backend support.

Table of Contents

1. Main Features 
2. Installation
3. Basic Usage 
4. Props
5. License

Features

• Provide list of all suggestions
• Accepts fully customized component as suggestion item
• Accepts input component as input element from MUI,Bootstrap or any other library even your own customized component
• Suggestions are highlighted and can be navigated with arrow keys or by mouse
• Bolding already entered text that match any part of suggestion list
• Accept your component to handle error and loading states
• Ability to controll refs and also forward passed ref
• Full controll on each part of component for styling purpose
• Pass through arbitrary props to the input (e.g. placeholder, type, onChange, onBlur, or any other)
• Support Free-solo mode
• And more yet to discover!

Installation

Install by npm:

npm install amirkzm/react-auto-complete"

Or:

yarn add amirkzm/react-auto-complete"

Usage

import React, { useState } from "react";
import AutoCompleteInput, {
  RenderFunctionParams,
} from "@amirkzm/react-auto-complete"";
import TextField from "@mui/material/TextField";

//Transform the returned reponse from server to an array (array of suggestions)
const transformResult = (response: any) => {
  return response.data;
};

// Extract a displayable value for representation purpose from a suggestion
const getLabel = (item: any) => {
  if (typeof item === "string") {
    return item;
  } else {
    return item.fact;
  }
};

// Generating address for entered query
const addressGenerator = (query: string) => {
  return "some url";
};

// Display each suggestion item. It receive data of selected suggestion, getLabel function, props (including onClick,onMouseEnter,key, className and style)
//and finally boldedMatchText that contains suggestion display text with bolded matched entered value.
//
const renderFunction = ({
  data,
  getLabel,
  props,
  boldedMatchText,
}: RenderFunctionParams) => {
  return <div {...props}>{boldedMatchText}</div>;
};

function App() {
  const [selectedItem, setSelectedItem] = useState<any>();
  const [value, setValue] = useState<string>("");

  // This function will be called everytime user select a suggestion
  const onChange = (selectedItem: any) => {
    setSelectedItem(newValue);
    setValue(getLabel(newValue));
  };

  // This will be called everytime user enter a character
  const inputChangeHandler = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  return (
    <div>
      <AutoCompleteInput
        renderFunction={renderFunction}
        transformResult={transformResult}
        addressGenerator={addressGenerator}
        onChange={onChange}
        onInputChange={inputChangeHandler}
        userInputValue={value}
        value={selectedItem}
        freeSolo
        getLabel={getLabel}
        keyGenerator={keyGenerator}
        itemHeight={50}
        InputComponent={TextField}
      />
    </div>
  );
}

Props

| Props | Types | Required | Description | |-------------------------|:---------:|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | renderFunction | Function | ✓ | React component responsible for rendering the each individual item of the suggestion's list. | | addressGenerator | Function | ✓ | A function that receives query entered by user and generate the address for that input to fetch data from. | | getLabel | Function | ✓ | This function will be used when we want to show string representation of an suggestion item received from server. | | transformResult | Function | ✓ | This function will be used to extract or (transform server's response) an array of suggestions from the server response. | | value | Any | ✓ | Use this if you want to pass your own item (object, string or anything else) to the component. If you use this the input field will be getLabel(item) no matter what user has typed already. | | userInputValue | String | ✓ | The input value from the user that should be displayed in the input field. | | itemHeight | Number | ✓ | Height of each suggestion item. | | loadingElement | ReactNode | | An Optional ReactNode element if we want to show user as loading | | InputComponent | Element | | An input component to be used as the main input element. default is HTML input tag. | | errorElement | ReactNode | | An Optional ReactNode element if we want to show user as error | | keyGenerator | Function | | A function to generate key. It accepts a suggested item and the index and return a key. | | onChange | Function | | This function will be called when an item has been selected from suggestion's list or when user types a character(only if freeSolo is true otherwise it won't be called when user types) | | onInputChange | Function | | This function will be called when user types a character. | | wrapperProps | Object | | Pass through arbitrary props to the root wrapper of the component. | | placeholder | String | | Placeholder for the component. | | outerWrapperRef | ref | | This ref prop target the root div. | | innerWrapperRef | ref | | This ref prop target the inner(suggestions div) div. | | freeSolo | Boolean | | Use this if you want user can have the ability of not choosing any suggestion and use it's own entered input. Default is true. | | inputComponenProps | Object | | Pass through arbitrary props to the input. It is useful when you define your own component as input component(e.g. MUI textField or your own customized components with specified props set). | | maxSuggestionListHeight | number | | Max height of suggestion list. | |

renderFunction(Required)

This function is reposible to display each suggestion item. It receives:

• data : the entire data received from server for this item. It's actually the corresponding item from suggestion list.
• getLabel : this function receives an item as input and display string representation of that item.
• props : including:
  • onClick
  • key
  • style
  • classsName
  • onMouseEnter
• boldedMatchText : resresents each suggestions with entered text as bold

const renderFunction = ({
  data,
  getLabel,
  props,
  boldedMatchText,
}: RenderFunctionParams) => {
  const { onClick, key, style, className, onMouseEnter } = props; // if you want to use each one seperatedly
  return <div {...props}>{boldedMatchText}</div>;
  //return <div {...props}>{getLabel(data)}</div> if you don't want to use boldMatchedText
};

license

MIT