{"id":13515831,"url":"https://github.com/afcapel/stimulus-autocomplete","last_synced_at":"2025-03-31T05:31:00.188Z","repository":{"id":33786057,"uuid":"162198666","full_name":"afcapel/stimulus-autocomplete","owner":"afcapel","description":"Stimulus autocomplete component","archived":false,"fork":false,"pushed_at":"2024-08-14T18:11:57.000Z","size":575,"stargazers_count":482,"open_issues_count":25,"forks_count":62,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-11-14T20:50:02.293Z","etag":null,"topics":["autocomplete","autocomplete-search","component","frontend","javascript","stimulus","stimulusjs"],"latest_commit_sha":null,"homepage":"","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/afcapel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-17T22:39:00.000Z","updated_at":"2024-11-08T17:15:40.000Z","dependencies_parsed_at":"2024-04-18T11:48:29.655Z","dependency_job_id":"b15b376e-c198-472b-a0dd-939bec463600","html_url":"https://github.com/afcapel/stimulus-autocomplete","commit_stats":{"total_commits":178,"total_committers":23,"mean_commits":7.739130434782608,"dds":0.5674157303370786,"last_synced_commit":"537644c1ed378b5c201f1f74a61497292ce2db6c"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Fstimulus-autocomplete","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Fstimulus-autocomplete/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Fstimulus-autocomplete/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afcapel%2Fstimulus-autocomplete/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afcapel","download_url":"https://codeload.github.com/afcapel/stimulus-autocomplete/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246423527,"owners_count":20774795,"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","autocomplete-search","component","frontend","javascript","stimulus","stimulusjs"],"created_at":"2024-08-01T05:01:16.418Z","updated_at":"2025-03-31T05:30:59.741Z","avatar_url":"https://github.com/afcapel.png","language":"JavaScript","readme":"# Stimulus Autocomplete controller\n\nThis is a tiny stimulus controller (1.5kB gzipped) to make a selection from a\nlist of results fetched from the server. [See it in action](https://stimulus-autocomplete.netlify.app/).\n\n![Demo](https://media.giphy.com/media/5dYbYLVX4fSbbdyN84/giphy.gif)\n\n## Installation\n\nIf you are using a js bundler with `node_modules` support (such as esbuild, rollup.js or Webpack) install the package from npm:\n\n```plain\nyarn add stimulus-autocomplete\n```\n\nIf you're using [importmap-rails](https://github.com/rails/importmap-rails), you'll need to pin `stimulus-autocomplete`:\n\n```plain\n./bin/importmap pin stimulus-autocomplete\n```\n\n## Usage\n\nLoad your stimulus application as usual and the register the autocomplete\ncontroller with it:\n\n```javascript\nimport { Application } from '@hotwired/stimulus'\nimport { Autocomplete } from 'stimulus-autocomplete'\n\nconst application = Application.start()\napplication.register('autocomplete', Autocomplete)\n```\n\nTo use the autocomplete, you need some markup as this:\n\n```html\n\u003cdiv data-controller=\"autocomplete\" data-autocomplete-url-value=\"/birds/search\" role=\"combobox\"\u003e\n  \u003cinput type=\"text\" data-autocomplete-target=\"input\"/\u003e\n  \u003cinput type=\"hidden\" name=\"bird_id\" data-autocomplete-target=\"hidden\"/\u003e\n  \u003cul class=\"list-group\" data-autocomplete-target=\"results\"\u003e\u003c/ul\u003e\n\u003c/div\u003e\n```\n\nThe component makes a request to the `data-autocomplete-url` to fetch results for\nthe contents of the input field. The server must answer with an html fragment:\n\n```html\n\u003cli class=\"list-group-item\" role=\"option\" data-autocomplete-value=\"1\"\u003eBlackbird\u003c/li\u003e\n\u003cli class=\"list-group-item\" role=\"option\" data-autocomplete-value=\"2\"\u003eBluebird\u003c/li\u003e\n\u003cli class=\"list-group-item\" role=\"option\" data-autocomplete-value=\"3\"\u003eMockingbird\u003c/li\u003e\n```\n\nNote: class `list-group` on `\u003cul\u003e` and `list-group-item` on `\u003cli\u003e` is required to apply the same css as displayed in the gif above.\n\nItems can be included that are not selectable, such as help text or delimiters using `aria-disabled` attribute:\n\n```html\n\u003cli role=\"option\" aria-disabled=\"true\"\u003eStart typing to search...\u003c/li\u003e\n```\n\nIf the controller has a `hidden` target, that field will be updated with the value\nof the selected option. Otherwise, the search text field will be updated.\n\nThe height of the result list can be limited with CSS, e.g.:\n\n```html\n\u003cul class=\"list-group\" data-autocomplete-target=\"results\" style=\"max-height: 10rem; overflow-y: scroll;\"\u003e\u003c/ul\u003e\n```\n\nIf you want a custom query parameter name, use the `data-autocomplete-query-param-value` attribute.\n\n```html\n\u003cdiv data-controller=\"autocomplete\" data-autocomplete-url-value=\"/birds/search\" data-autocomplete-query-param-value=\"name\" ...\u003e\n```\n\nThe above will setup will fetch the results from `/bird/search?name=SEARCH_TEXT`.\n\n## Events\n\nEvents on the main element that registered the controller:\n\n* `autocomplete.change` fires when the users selects a new value from the autocomplete\nfield. The event `detail` contains the `value` and `textValue` properties of the\nselected result.\n* `loadstart` fires before the autocomplete fetches the results from the server.\n* `load` fires when results have been successfully loaded.\n* `error` fires when there's an error fetching the results.\n* `loadend` fires when the request for results ends, successfully or not.\n* `toggle` fires when the results element is shown or hidden.\n\nEvents on the optional hidden input:\n\n* `input` and `change` dispatched to it when the users selects a new value from the autocomplete. This allows you to bind subsequent behavior directly to the `\u003cinput type=hidden\u003e` element.\n\n## Optional parameters\n\n* `autocomplete-min-length` set the minimum number of characters required to make an autocomplete request.\n    ```html\n    \u003cdiv class=\"form-group\" data-controller=\"autocomplete\" data-autocomplete-min-length-value=\"3\" data-autocomplete-url-value=\"/birds/search\"\u003e\n      ...\n    \u003c/div\u003e\n    ```\n* `autocomplete-submit-on-enter` submit the form after the autocomplete selection via enter keypress.\n   ```html\n    \u003cdiv class=\"form-group\" data-controller=\"autocomplete\" data-autocomplete-submit-on-enter-value=\"true\" data-autocomplete-url-value=\"/birds/search\"\u003e\n      ...\n    \u003c/div\u003e\n   ```\n* `autocomplete-selected-class` Stimulus Autocomplete adds a default `.active` class to the currently selected result. You can use another class instead of `.active` with the this attribute.\n   ```html\n    \u003cdiv data-controller=\"autocomplete\" data-autocomplete-url-value=\"/results-plain-text.html\" data-autocomplete-selected-class=\"selected-result\"\u003e\n      ...\n    \u003c/div\u003e\n  ```\n* `autocomplete-label` can be used to define the input label upon selection. That way your option elements can have more elaborate markup, i.e.:\n\n  ```html\n  \u003cli class=\"list-group-item\" role=\"option\" data-autocomplete-value=\"1\" data-autocomplete-label=\"Blackbird\"\u003e\n    \u003cp\u003eBlackbird\u003c/p\u003e\n    \u003cp class=\"text-muted\"\u003e\u003csmall\u003eThat's also the name of an airplane\u003c/small\u003e\u003c/p\u003e\n  \u003c/li\u003e\n  ```\n\n* `autocomplete-delay-value` how long to wait since the user stops typing until the autocomplete makes a request to the server. Defaults to 300 (ms).\n\n  ```html\n    \u003cdiv data-controller=\"autocomplete\" data-autocomplete-url-value=\"/results-plain-text.html\" data-autocomplete-delay-value=\"500\"\u003e\n      ...\n    \u003c/div\u003e\n  ```\n\n## Optional HTML configuration\n\n* If the `\u003cinput\u003e` target has an `autofocus` attribute then the input will be given focus immediately so the user can start typing. This is useful if the `\u003cinput\u003e` is dynamically added/morphed into the DOM (say by a \"edit\" button) and the user expects to start typing immediately.\n\n# Extension points\n\n### URL building\n\nThe autcomplete default behaviour is to add a `q` querystring parameter to the the base `data-autocomplete-url`. If you need a different format, you can override the controllers `buildURL` method.\n\n```js\nimport { Application } from '@hotwired/stimulus'\nimport { Autocomplete } from 'stimulus-autocomplete'\n\nconst application = Application.start()\n\nclass CustomAutocomplete extends Autocomplete {\n  buildURL(query) {\n    return `${new URL(this.urlValue, window.location.href).toString()}/${query}`\n  }\n}\n\napplication.register('autocomplete', CustomAutocomplete)\n```\n\n## Examples\n\n- [The examples directory](https://github.com/afcapel/stimulus-autocomplete/tree/main/examples) contains some examples of how to use the library.\n- [This example Rails app](https://github.com/afcapel/stimulus-autocomplete-rails-example) shows how to use it with  Webpack.\n- [Autocomplete with StimulusJS - Drifting Ruby](https://www.driftingruby.com/episodes/autocomplete-with-stimulusjs)\n- [Search Autocomplete Stimulus](https://itnext.io/search-autocomplete-stimulus-4e941df54d39?sk=a09dbf0e1ca8cd2f544ba34b78f739f0)\n\n\n## Credits\n\nHeavily inspired on [github's autocomplete element](https://github.com/github/auto-complete-element).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at \u003chttps://github.com/afcapel/stimulus-autocomplete\u003e.  This project is intended to be a safe, welcoming space for  collaboration, and contributors are expected to adhere to the  Contributor Covenant code of conduct.\n\n## Release a new version\n\nTo release a new version follow these steps:\n\n1. Update the version number in `package.json`. Try to follow\nsemantic versioning guidelines as much as possible.\n\n2. Publish the package to npmjs.com with `yarn run release`\n\n## License\n\nThis package is available as open source under the terms of the MIT License.\n","funding_links":[],"categories":["JavaScript","Packages"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafcapel%2Fstimulus-autocomplete","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafcapel%2Fstimulus-autocomplete","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafcapel%2Fstimulus-autocomplete/lists"}