{"id":13519625,"url":"https://github.com/swiftype/swiftype-autocomplete-jquery","last_synced_at":"2025-03-31T14:30:43.964Z","repository":{"id":2304566,"uuid":"3263546","full_name":"swiftype/swiftype-autocomplete-jquery","owner":"swiftype","description":"Elastic Site Search jQuery autocomplete plugin","archived":false,"fork":false,"pushed_at":"2021-02-02T03:50:45.000Z","size":90,"stargazers_count":47,"open_issues_count":6,"forks_count":50,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-11-02T02:32:54.820Z","etag":null,"topics":["autocomplete","autocompletion","browser","elastic","elastic-site-search","javascript","jquery","jquery-autocomplete-plugin","jquery-plugin","search","swiftype"],"latest_commit_sha":null,"homepage":"https://swiftype.com/documentation/site-search/overview","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swiftype.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-01-25T09:00:59.000Z","updated_at":"2024-05-24T10:59:04.000Z","dependencies_parsed_at":"2022-08-26T21:40:58.641Z","dependency_job_id":null,"html_url":"https://github.com/swiftype/swiftype-autocomplete-jquery","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftype%2Fswiftype-autocomplete-jquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftype%2Fswiftype-autocomplete-jquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftype%2Fswiftype-autocomplete-jquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftype%2Fswiftype-autocomplete-jquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swiftype","download_url":"https://codeload.github.com/swiftype/swiftype-autocomplete-jquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246482865,"owners_count":20784792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","autocompletion","browser","elastic","elastic-site-search","javascript","jquery","jquery-autocomplete-plugin","jquery-plugin","search","swiftype"],"created_at":"2024-08-01T05:02:01.267Z","updated_at":"2025-03-31T14:30:43.707Z","avatar_url":"https://github.com/swiftype.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/swiftype/swiftype-autocomplete-jquery/blob/master/logo-site-search.png?raw=true\" alt=\"Elastic Site Search Logo\"\u003e\u003c/p\u003e\n\n\u003e A first-party [Elastic Site Search](https://swiftype.com/documentation/site-search/overview) jQuery plugin for search autocomplete.\n\n## Contents\n\n+ [Getting started](#getting-started-)\n+ [Usage](#usage)\n+ [Customization Tutorial](#customization-tutorial)\n+ [FAQ](#faq-)\n+ [Contribute](#contribute-)\n+ [License](#license-)\n\n***\n\n## Getting started 🐣\n\nRequirements:\n\n1. Site Search account. Sign up at [swiftype.com](https://app.swiftype.com/signup).\n2. Site Search engine with some data in it.\n\nInclude the following in the header of your webpage:\n\n* the latest version of jQuery\n* the Swiftype jQuery plugin\n* (optional) the Swiftype Autocomplete stylesheet\n\nAll together it should look like this:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"jquery.swiftype.autocomplete.js\"\u003e\u003c/script\u003e\n\u003clink type=\"text/css\" rel=\"stylesheet\" href=\"autocomplete.css\" media=\"all\" /\u003e\n```\n\n\u003e **Note:** This client has been developed for the [Elastic Site Search](https://www.swiftype.com/site-search) API endpoints only. You may refer to the [Elastic Site Search API Documentation](https://swiftype.com/documentation/site-search/overview) for additional context.\n\n## Usage\n\nSimply apply the swiftype method to an existing search input field on your webpage. For example, add it to a search input field with id `st-search-input` as follows:\n\n```javascript\n$('#st-search-input').swiftype({\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\nBe sure to change the `engineKey` attribute shown above to match the one assigned to your Swiftype search engine. If you are using the web interface, the search engine key is listed on the first page of your dashboard.\n\nThis simple installation will by default match the string a user is typing into your search input to any of the items indexed in your search engine. By default, the string is matched against any fields you have indexed with type `string`.\n\n## Customization tutorial\n\nThis plugin is written to be flexible based on your specific use-case.\nFor example you might want to retrieve more data for each element in the dropdown, customize\nthe way data is display to the user, or restrict the autocomplete query to certain elements of your search engine.\n\nLet's go through an example that does all of this. For this example, let's assume you followed the QuickStart tutorial for our [Ruby Gem](https://github.com/swiftype/swiftype-rb), and now you have data for a Bookstore indexed in your example search engine.\n\n### Changing the number of results\n\nTo specify the number of results you would like returned from the API, set the `resultLimit` attribute as follows:\n\n```javascript\n$('#st-search-input').swiftype({\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK',\n  resultLimit: 20\n});\n```\n\n### Fetching only the fields you specify\n\nTo specify the fields you would like returned from the API, set the `fetchFields` attribute to a hash containing an array listing the fields you want returned for each document type. For example, if you have indexed `title`, `genre`, and `published_on` fields for each document, you can have them returned as follows:\n\n```javascript\n$('#st-search-input').swiftype({\n  fetchFields: { 'books': ['title', 'genre', 'published_on'] },\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\nThese additional fields will be returned with each item in the autocomplete, and they can be accessed in the rendering function as shown in the next section.\n\n### Customizing the display\n\nNow that you have more data for each autocomplete item, you'll want to customize the item rendering function to make use of them.\n\nThe default rendering function is shown below:\n\n```javascript\nvar defaultRenderFunction = function(document_type, item) {\n  return '\u003cp class=\"title\"\u003e' + Swiftype.htmlEscape(item['title']) + '\u003c/p\u003e';\n};\n```\n\nThe additional fields are available as keys in the item dictionary, so you could customize this to make use of the `genre` field as follows:\n\n```javascript\nvar customRenderFunction = function(document_type, item) {\n  var out = '\u003ca href=\"' + Swiftype.htmlEscape(item['url']) + '\" class=\"st-search-result-link\"\u003e' + item.highlight['title'] + '\u003c/a\u003e';\n  return out.concat('\u003cp class=\"genre\"\u003e' + item.highlight['genre'] + '\u003c/p\u003e');\n};\n```\n\nNow simply set the `renderFunction` attribute in the options dictionary to your `customRenderFunction` to tell our plugin to use your function to render results:\n\n```javascript\n$('#st-search-input').swiftype({\n  renderFunction: customRenderFunction,\n  fetchFields: { 'books': ['url'] }, // Fetch the URL field as a raw field.\n  highlightFields: { 'books': { 'title': { 'size': 60, 'fallback': true }, 'genre': { 'size': 60, 'fallback': true }, 'published_on': { 'size': 15, 'fallback':true } } },\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\n#### Restricting matching to particular fields\n\nBy default, the Swiftype autocomplete library will match the string the user is typing to any `string` field indexed for your documents. So if you would like to ensure that it only matches entries in the `title` field, for example, you can specify the `searchFields` option:\n\n```javascript\n$('#st-search-input').swiftype({\n  renderFunction: customRenderFunction,\n  fetchFields: { 'books': ['title', 'genre', 'published_on'] },\n  searchFields: { 'books': ['title'] },\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\nSimilarly to the `fetchFields` option, `searchFields` accepts a hash containing an array of fields for each document_type on which you would like the user's query to match.\n\n### Specifying additional query conditions\n\nNow let's say you only want your autocomplete to display books that are of the **fiction** `genre` and are **in_stock**. In order to restrict search results, you can pass additional query conditions to the search API by specifying them as a dictionary in the `filters` field. Multiple clauses in the filters field are combined with AND logic:\n\n```javascript\n$('#st-search-input').swiftype({\n  renderFunction: customRenderFunction,\n  fetchFields: { 'books': ['title', 'genre', 'published_on'] },\n  filters: { 'books': { 'genre': 'fiction', 'in_stock': true } },\n  searchFields: { 'books': ['title'] },\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\n### Changing what happens when an item is selected in the dropdown\n\nIn order to change what happens when clicking on an item, you need to provide an `onComplete` handler function.\n\nBy default, clicking on an item in the dropdown will execute the following `onComplete` handler, which routes a user to the `url` property of the selected item:\n\n```javascript\nvar defaultOnComplete = function(item, prefix) {\n  window.location = item['url'];\n};\n```\n\nTo change this, simply provide a new handler function in the `onComplete` option when initializing your autocomplete.\n\nHere is an example that updates the input value with the selected item's title:\n\n```javascript\nvar input; // Save a reference to the autocomplete dropdown\ninput = $('#st-search-input').swiftype({\n  onComplete: function(selectedItem) {\n    input.val(selectedItem['title']); // Update the autocomplete dropdown's value\n  },\n  fetchFields: { 'books': ['title'] },\n  engineKey: 'jaDGyzkR6iYHkfNsPpNK'\n});\n```\n\n## FAQ 🔮\n\n### Can I use this with the Swiftype Search Plugin?\n\nYes! If you are looking for core search functionality, checkout out the [Swiftype Search Plugin](https://github.com/swiftype/swiftype-search-jquery).\n\n### Where do I report issues with the client?\n\nIf something is not working as expected, please open an [issue](https://github.com/swiftype/swiftype-autocomplete-jquery/issues/new).\n\n### Where can I learn more about Site Search?\n\nYour best bet is to read the [documentation](https://swiftype.com/documentation/site-search).\n\n### Where else can I go to get help?\n\nYou can checkout the [Elastic Site Search community discuss forums](https://discuss.elastic.co/c/site-search).\n\n## Contribute 🚀\n\nWe welcome contributors to the project. Before you begin, a couple notes...\n\n+ Before opening a pull request, please create an issue to [discuss the scope of your proposal](https://github.com/swiftype/swiftype-autocomplete-jquery/issues).\n+ Please write simple code and concise documentation, when appropriate.\n\n## License 📗\n\n[MIT](https://github.com/swiftype/swiftype-autocomplete-jquery/blob/master/LICENSE) © [Elastic](https://github.com/elastic)\n\nThank you to all the [contributors](https://github.com/swiftype/swiftype-autocomplete-jquery/graphs/contributors)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftype%2Fswiftype-autocomplete-jquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswiftype%2Fswiftype-autocomplete-jquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftype%2Fswiftype-autocomplete-jquery/lists"}