📚
Slickgrid-Universal
Live DemoGitHubOther Frameworks
  • Introduction
  • Getting Started
    • Quick start
    • Salesforce (LWC)
    • Vanilla Installation
  • Styling
    • Dark Mode
    • Styling CSS/SASS/Themes
  • Column Functionalities
    • Cell Menu (Action Menu)
    • Editors
      • Autocomplete
      • old Date Picker (flatpickr)
      • new Date Picker (vanilla-calendar)
      • LongText (textarea)
      • Select Dropdown Editor (single/multiple)
    • Filters
      • Input Filter (default)
      • Select Filter (dropdown)
      • Compound Filters
      • Range Filters
      • Styling Filled Filters
      • Single Search Filter
    • Formatters
    • Sorting
  • Events
    • Available events
    • On Events
  • Grid Functionalities
    • Auto-Resize / Resizer Service
    • Resize by Cell Content
    • Column Picker
    • Composite Editor Modal
    • Custom Tooltip
    • Column & Row Spanning
    • Context Menu
    • Custom Footer
    • Excel Copy Buffer Plugin
    • Export to Excel
    • Export to File (csv/txt)
    • Grid Menu
    • Grid State & Presets
    • Grouping & Aggregators
    • Header Menu & Header Buttons
    • Pagination
    • Infinite Scroll
    • Pinning (frozen) of Columns/Rows
    • Row Detail
    • Row Selection
    • Tree Data Grid
    • Row Based Editing Plugin
  • Developer Guides
    • CSP Compliance
  • Localization
    • with I18N
    • with Custom Translate Service
    • with Single Locale
  • Backend Services
    • Custom Backend Service
    • OData
    • GraphQL
      • JSON Result Structure
      • Filtering Schema
      • Pagination Schema
      • Sorting Schema
  • Migrations
    • Migration Guide to 1.x (2021-12-11)
    • Migration Guide to 2.x (2022-10-17)
    • Migration Guide to 3.x (2023-05-29)
    • Migration Guide to 4.x (2023-12-15)
    • Migration Guide to 5.x (2024-05-10)
    • Versions 6 to 8 are skipped...
    • Migration Guide to 9.x (2025-05-10)
Powered by GitBook
On this page
  • Using collection or collectionAsync
  • Using External Remote API
  • Autocomplete - force user input
  • Animated Gif Demo
  1. Column Functionalities
  2. Editors

Autocomplete

PreviousEditorsNextold Date Picker (flatpickr)

Last updated 2 days ago

Index

    • See the for more general info about Editors (validators, event handlers, ...)

Demo

|

Introduction

AutoComplete is a functionality that let the user start typing characters and the autocomplete will try to give suggestions according to the characters entered. The collection can be a fixed JSON files (collection of strings or objects) or can also be an external remote resource to an external API. For a demo of what that could look like, take a look at the below.

We use an external lib named (aka autocompleter on npm) by Kraaden.

Using collection or collectionAsync

If you want to pass the entire list to the AutoComplete (like a JSON file or a Web API call), you can do so using the collection or the collectionAsync (the latter will load it asynchronously). You can also see that the Editor and Filter have almost the exact same configuration (apart from the model that is obviously different).

Component

export class GridBasicComponent {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset: any[];

  attached(): void {
    // your columns definition
    this.columnDefinitions = [
      {
        id: 'countryOfOrigin', name: 'Country of Origin', field: 'countryOfOrigin',
        formatter: Formatters.complexObject,
        dataKey: 'code', // our list of objects has the structure { code: 'CA', name: 'Canada' }, since we want to use the code`, we will set the dataKey to "code"
        labelKey: 'name', // while the displayed value is "name"
        type: 'object',
        sorter: Sorters.objectString, // since we have set dataKey to "code" our output type will be a string, and so we can use this objectString, this sorter always requires the dataKey
        filterable: true,
        sortable: true,
        minWidth: 100,
        editor: {
          model: Editors.autocompleter,
          customStructure: { label: 'name', value: 'code' },
          collectionAsync: this.http.get('assets/data/countries.json'), // this demo will load the JSON file asynchronously
          onInstantiated: (instance) => console.log('instance', instance), // get instance from 3rd party lib
        },
        filter: {
          model: Editors.autocompleter,
          customStructure: { label: 'name', value: 'code' },
          collectionAsync: this.http.get('assets/data/countries.json'),
          onInstantiated: (instance) => console.log('instance', instance), // get instance from 3rd party lib
        }
      }
    ];

    this.gridOptions = {
      // your grid options config
    }
  }
}

Collection Label Render HTML

By default HTML is not rendered and the label will simply show HTML as text. But in some cases you might want to render it, you can do so by enabling the enableRenderHtml flag.

NOTE: this is currently only used by the Editors that have a collection which are the MultipleSelect & SingleSelect Editors.

this.columnDefinitions = [
  {
    id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven',
    formatter: Formatters.checkmark,
    type: 'boolean',
    editor: {
      model: Editors.autocompleter,
      placeholder: '🔍 search city',

      // example with a fixed Collection (or collectionAsync)
      // previously known as `editorOptions` for < 9.0
      options: {
        showOnFocus: true, // display the list on focus of the autocomplete (without the need to type anything)
      } as AutocompleterOption,
      enableRenderHtml: true, // this flag only works with a fixed Collection
      // collectionAsync: this.http.get(COUNTRIES_COLLECTION_URL),
      collection: [
        { value: '', label: '' },
        { value: true, label: 'True', labelPrefix: `<i class="mdi mdi-plus"></i> ` },
        { value: false, label: 'False', labelPrefix: `<i class="mdi mdi-minus"></i> ` }
      ],
    }
  }
];

Editor Options (AutocompleterOption interface)

editor: {
  model: Editors.autocompleter,
  // previously known as `editorOptions` for < 9.0
  options: {
    minLength: 3,
  } as AutocompleterOption
}

Grid Option `defaultEditorOptions

You could also define certain options as a global level (for the entire grid or even all grids) by taking advantage of the defaultEditorOptions Grid Option. Note that they are set via the editor type as a key name (autocompleter, date, ...) and then the content is the same as editor options (also note that each key is already typed with the correct editor option interface), for example

this.gridOptions = {
  defaultEditorOptions: {
    autocompleter: { debounceWaitMs: 150 }, // typed as AutocompleterOption
  }
}

Using External Remote API

You could also use external 3rd party Web API (can be JSONP query or regular JSON). This will make a much shorter result since it will only return a small subset of what will be displayed in the AutoComplete Editor or Filter. For example, we could use GeoBytes which provide a JSONP Query API for the cities of the world, you can imagine the entire list of cities would be way too big to download locally, so this is why we use such API.

Remote API (basic)

The basic functionality will use built-in 3rd party lib styling that is to display a label/value pair item result.

Component

export class GridBasicComponent {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset: any[];

  initializeGrid() {
    // your columns definition
    this.columnDefinitions = [
      {
        id: 'product', name: 'Product', field: 'product',
        filterable: true,
        minWidth: 100,
        editor: {
          model: Editors.autocompleter,
          alwaysSaveOnEnterKey: true,
          // previously known as `editorOptions` for < 9.0
          options: {
            showOnFocus: true,
            minLength: 1,
            fetch: (searchText, updateCallback) => {
              // assuming your API call returns a label/value pair
              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
                 .catch(error => console.log('Error:', error));
            },
          } as AutocompleterOption,
        },
      },
    ];

    this.gridOptions = {
      // your grid options config
    }
  }
}

Remote API (basic with object result)

This is the preferred way of dealing with the AutoComplete, the main reason is because the AutoComplete uses an <input/> and that means we can only keep 1 value and if we do then we lose the text label and so using an Object Result makes more sense. Note however that you'll need a bit more code that is because we'll use the 'object' and so we need to provide a custom SortComparer and also a custom Formatters and for them to work we also need to provide a dataKey (the value) and a labelKey (text label) as shown below.

this.columnDefinitions = [
  {
    id: 'product', name: 'Product', field: 'product',
    dataKey: 'id',
    labelKey: 'name', // (id/name) pair to override default (value/label) pair
    editor: {
      model: Editors.autocompleter,
      alwaysSaveOnEnterKey: true,
      type: 'object',
      sortComparer: SortComparers.objectString,
      options: {
      showOnFocus: true,
      minLength: 1,
      fetch: (searchText, updateCallback) => {
        // assuming your API call returns a label/value pair
        yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
          .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
          .catch(error => console.log('Error:', error));
        },
      } as AutocompleterOption,
    }
  },
];

Remote API with renderItem + custom layout (twoRows or fourCorners)

The lib comes with 2 built-in custom layouts, these 2 layouts also have SASS variables if anyone wants to style it differently. When using the renderItem, it will require the user to provide a layout (2 possible options twoRows or fourCorners) and also a templateCallback that will be executed when rendering the AutoComplete Search List Item. For example:

Component

export class GridBasicComponent {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset: any[];

  initializeGrid() {
      // your columns definition
    this.columnDefinitions = [
      {
        id: 'product', name: 'Product', field: 'product',
        filterable: true,
        minWidth: 100,
        editor: {
          model: Editors.autocompleter,
          alwaysSaveOnEnterKey: true,
          customStructure: {
            label: 'itemName',
            value: 'id'
          },
          // previously known as `editorOptions` for < 9.0
          options: {
            showOnFocus: true,
            minLength: 1,
            fetch: (searchText, updateCallback) => {
              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
                .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
                .catch(error => console.log('Error:', error));
            },
            renderItem: {
              layout: 'twoRows',
              templateCallback: (item: any) => `<div class="autocomplete-container-list">
                <div class="autocomplete-left">
                  <span class="mdi ${item.icon} mdi-26px"></span>
                </div>
                <div>
                  <span class="autocomplete-top-left">
                    <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
                    ${item.itemName}
                  </span>
                <div>
              </div>
              <div>
                <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
              </div>`,
            },
          } as AutocompleterOption,
        },
      }
    ];

    this.gridOptions = {
      // your grid options config
    }
  }
}

Remote API renderItem callback + custom layout (twoRows or fourCorners)

The previous example can also be written using the renderItem callback and adding classes, this is actually what Slickgrid-Universal does internally, you can do it yourself if you wish to have more control on the render callback result.

Component

export class GridBasicComponent {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset: any[];

  initializeGrid() {
      // your columns definition
    this.columnDefinitions = [
      {
        id: 'product', name: 'Product', field: 'product',
        filterable: true,
        minWidth: 100,
        editor: {
          model: Editors.autocompleter,
          alwaysSaveOnEnterKey: true,
          customStructure: {
            label: 'itemName',
            value: 'id'
          },
          options: {
            showOnFocus: true,
            minLength: 1,
            fetch: (searchText, updateCallback) => {
              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
                .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
                .catch(error => console.log('Error:', error));
            },
            renderItem: {
              layout: 'twoRows',
              templateCallback: (item: any) => `<div class="autocomplete-container-list">
                <div class="autocomplete-left">
                  <span class="mdi ${item.icon} mdi-26px"></span>
                </div>
                <div>
                  <span class="autocomplete-top-left">
                    <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
                    ${item.itemName}
                  </span>
                <div>
              </div>
              <div>
                <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
              </div>`,
            },
          } as AutocompleterOption,
          callbacks: {
            // callback on the AutoComplete on the instance
            renderItem: {
              templateCallback: (item: any) => {
                return `<div class="autocomplete-container-list">
                  <div class="autocomplete-left">
                    <!--<img src="http://i.stack.imgur.com/pC1Tv.jpg" width="50" />-->
                    <span class="mdi ${item.icon} mdi-26px"></span>
                  </div>
                  <div>
                    <span class="autocomplete-top-left">
                      <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
                      ${item.itemName}
                    </span>
                    <span class="autocomplete-top-right">${formatNumber(item.listPrice, 2, 2, false, '$')}</span>
                  <div>
                </div>
                <div>
                  <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
                  <span class="autocomplete-bottom-right">Type: <b>${item.itemTypeName === 'I' ? 'Item' : item.itemTypeName === 'C' ? 'PdCat' : 'Cat'}</b></span>
                </div>`;
              }
            },
          },
        },
      }
    ];

    this.gridOptions = {
      // your grid options config
    }
  }
}

with JSONP

Example from an external remote API (geobytes) returning a JSONP response.

Component

export class GridBasicComponent {
  columnDefinitions: Column[];
  gridOptions: GridOption;
  dataset: any[];

  attached(): void {
      // your columns definition
    this.columnDefinitions = [
      {
        id: 'cityOfOrigin', name: 'City of Origin', field: 'cityOfOrigin',
        filterable: true,
        minWidth: 100,
        editor: {
          model: Editors.autocompleter,
          placeholder: 'search city', //  you can provide an optional placeholder to help your users

          // use your own autocomplete options, instead of $.ajax, use http
          // here we use $.ajax just because I'm not sure how to configure http with JSONP and CORS
          options: {
            minLength: 3, // minimum count of character that the user needs to type before it queries to the remote
            fetch: (searchText, updateCallback) => {
              $.ajax({
                url: 'http://gd.geobytes.com/AutoCompleteCity',
                dataType: 'jsonp',
                data: {
                  q: searchText // geobytes requires a query with "q" queryParam representing the chars typed (e.g.:  gd.geobytes.com/AutoCompleteCity?q=van
                },
                success: (data) => updateCallback(data)
              });
            }
          },
        },
        filter: {
          model: Editors.autocompleter,
          // placeholder: '&#128269; search city', // &#128269; is a search icon, this provide an option placeholder

          // use your own autocomplete options, instead of $.ajax, use http
          // here we use $.ajax just because I'm not sure how to configure http with JSONP and CORS
          options: {
            minLength: 3, // minimum count of character that the user needs to type before it queries to the remote
            fetch: (searchText, updateCallback) => {
              $.ajax({
                url: 'http://gd.geobytes.com/AutoCompleteCity',
                dataType: 'jsonp',
                data: {
                  q: searchText
                },
                success: (data) => {
                  updateCallback(data);
                }
              });
            }
          },
        }
      }
    ];

    this.gridOptions = {
      // your grid options config
    }
  }
}

Autocomplete - force user input

If you want to add the autocomplete functionality but want the user to be able to input a new option, then follow the example below:

this.columnDefinitions = [
  {
    id: 'area',
    name: 'Area',
    field: 'area',
    editor: {
      model: Editors.autocompleter,
      // previously known as `editorOptions` for < 9.0
      options: {
        minLength: 0,
        forceUserInput: true,
        fetch: (searchText, updateCallback) => {
          updateCallback(this.areas); // add here the array
        },
      }
    }
  },
];

You can also use the minLength to limit the autocomplete text to 0 characters or more, the default number is 3.

How to change drop container dimensions?

You might want to change the dimensions of the drop container, this 3rd party library has a customize method to deal with such a thing. Slickgrid-Universal itself is removing the width using this method, you can however override this method to change the drop container dimensions

this.columnDefinitions = [
  {
    id: 'product', name: 'Product', field: 'product', filterable: true,
    editor: {
      model: Editors.autocompleter,
      alwaysSaveOnEnterKey: true,

      // example with a Remote API call
      options: {
        minLength: 1,
        fetch: (searchTerm, callback) => {
          // ...
        },
        customize: (_input, _inputRect, container) => {
          // change drop container dimensions
          container.style.width = '250px';
          container.style.height = '325px';
        },
      } as AutocompleterOption,
    },
  }
];

Animated Gif Demo

Basic (default layout)

with twoRows custom layout (without optional left icon)

with fourCorners custom layout (with extra optional left icon)

All the available options that can be provided as editor options to your column definitions can be found under this and you should cast your editor options to that interface to make sure that you use only valid options of the autocomplete library.

See animated gif ( or )

See animated gif ( or )

AutocompleterOption interface
Custom Styling - SASS variables
Editors - Wiki
Demo Page
Demo Component
Autocomplete
Using fixed collection or collectionAsync
Editor Options (AutocompleterOption interface)
Using Remote API
Basic Usage
Basic Usage with Object Result (preferred way)
with renderItem + custom Layout (twoRows or fourCorners)
Force User Input
How to change drop container dimensions?
Animated Gif Demo
animated gif demo
twoRows
fourCorners
twoRows
fourCorners