{"id":13804510,"url":"https://github.com/html-next/ember-gestures","last_synced_at":"2025-04-04T15:07:39.183Z","repository":{"id":36091244,"uuid":"40392194","full_name":"html-next/ember-gestures","owner":"html-next","description":"Gesture support for Ember Applications","archived":false,"fork":false,"pushed_at":"2023-11-27T21:43:33.000Z","size":597,"stargazers_count":160,"open_issues_count":28,"forks_count":57,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-27T18:57:53.131Z","etag":null,"topics":[],"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/html-next.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-08-08T05:07:10.000Z","updated_at":"2024-02-10T18:29:06.000Z","dependencies_parsed_at":"2023-12-07T23:35:00.690Z","dependency_job_id":"dc88971a-cb02-45dc-b079-9c3681e98793","html_url":"https://github.com/html-next/ember-gestures","commit_stats":{"total_commits":198,"total_committers":33,"mean_commits":6.0,"dds":0.5151515151515151,"last_synced_commit":"561cacc01d65e37e0c4bb8d544e7a06c14536f15"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/html-next%2Fember-gestures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/html-next%2Fember-gestures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/html-next%2Fember-gestures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/html-next%2Fember-gestures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/html-next","download_url":"https://codeload.github.com/html-next/ember-gestures/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246651799,"owners_count":20812027,"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":[],"created_at":"2024-08-04T01:00:49.124Z","updated_at":"2025-04-04T15:07:39.161Z","avatar_url":"https://github.com/html-next.png","language":"JavaScript","funding_links":[],"categories":["Packages"],"sub_categories":["a11y"],"readme":"Ember Gestures [](http://badge.fury.io/js/ember-gestures)\n==============\n\n[](https://travis-ci.org/html-next/ember-gestures)\n[](http://emberobserver.com/addons/ember-gestures)\n\nEmber Gestures provides an easy way to use gestures by making it simple to define and use [HammerJS](https://github.com/hammerjs/hammer.js) managers\n and recognizers throughout your app.\n\nWhen installed via `ember install ember-gestures`, it will additionally install [ember-hammertime](https://github.com/runspired/ember-hammertime)\nto use for \"fastclick\" support.\n\n## Support, Questions, Collaboration\n\nJoin the [Ember community on Discord](https://discord.gg/zT3asNS)\n\n### Status\n\n[Changelog](./CHANGELOG.md)\n\n[](https://david-dm.org/html-next/ember-gestures)\n[](https://david-dm.org/runspired/ember-gestures#info=devDependencies)\n\n## Usage\n\n`ember install ember-gestures`\n\nThis will run the default blueprint which additionally installs `HammerJS`.\n\n\n#### Recognizers and Managers\n\nA `Recognizer` detects a gesture on a target element by listening to received touch, mouse, and pointer events\nand passing through a series of rules to determine whether it's gesture is occurring.\n\n`Recognizer`s are registered with a `Manager`, which emits the recognized gestures for consumption by your app.\nThis addon does the grunt work of creating Managers and wiring up Recognizers for you. All you need to do\nto use gestures is tell your app where you want a Manager to be created and what Recognizers it should have.\n\nExample\n```js\nimport RecognizerMixin from 'ember-gestures/mixins/recognizers';\nimport Ember from 'ember';\n\nconst {\n Component\n} = Ember;\n\nexport default Component.extend(RecognizerMixin, {\n recognizers: 'pan tap press'\n});\n```\n\nThe component would create a new Manager and add the recognizers for [pan](./addon/recognizers/pan.js),\n[tap](./addon/recognizers/tap.js), and [press](./addon/recognizers/press.js).\n\nThe component would recognize gestures based on events originating on it or it's child elements.\nThe corresponding gesture would be capable of being handled anywhere in the DOM branch in which the component\nexists.\n\nExample Dom Tree\n```\nbody\n|_ div 1\n |_ component A\n |_ div 2\n |_ component B (with recognizers)\n |_ div 3\n```\n\nIn the above example, input events originating on `component B` or `div 3` would be passed to the recognizers.\nThe emitted gestures are triggered on the element which began the gesture (also `component B` or `div 3` and\nbubble up to `body`. This means that component A would also be capable of handling gestures emitted by the\nmanager on component B. If `div 3` had an action handler that utilized a gesture, it too would be able to use\ngestures emitted by component B if they had begun on or within `div 3`.\n\nThis means you should be strategic about where you put your components with Managers. You don't need a lot of\nManagers, you just need them placed strategically. You could even put one at the base of your app, but be\nwarned `pinch` `rotate` `pan` and `swipe` can break scrolling behavior if not placed correctly.\n\n##### Note\n\n`pan` and `swipe` are horizontal only (configured this way to avoid breaking vertical scroll).\n`vertical-pan` and `vertical-swipe` are vertical only (configured this way to avoid breaking horizontal scroll).\n\n##### Modifier\nAs an alternative to using the `RecognizerMixin`, you may use the `{{recognize-gesture}}` modifier. This is particularly useful when you are applying the recognizer to an element within the handlebars of your component, rather than to the root element of a component, and vital when your component _has_ no root element, as when you use Glimmer components or components with `tagName=\"\"`.\n\nExample\n```hbs\n\u003cdiv {{recognize-gesture \"pan\" \"tap\" \"press\" }}\u003e\n```\nGestures to recognize are supplied using positional parameters on the modifier. Hammer manager options can be supplied using named parameters on the modifier.\n\nWhen using `{{ember-on-modifier}}` with these events, you must use the real DOM event names, which are lowercase without hyphens. So your event for \"double-tap\" would be \"doubletap\". \n\nAlso, if you are using objects derived from `EmberObject`, like Ember components, avoid using action names that are the camel-case form of the gesture names, like `doubleTap`, as these are also the names for the component's generated event listeners, and may get unexpectedly triggered when an event bubbles up to the component as well as when your `{{on}}` action fires on the element. (This is one more reason to migrate to Glimmer components, which don't automatically add event handlers to your namespace.) \n\nThe modifier can only be used with Ember 2.18 or later.\n\n#### Using Gestures\n\nUsing gestures emitted by Hammer recognizers with Ember is almost like using any other event with Ember.\nYour recognizers will be configured to emit `Events`, so to consume a gesture, you just need to add an\nevent handler to your component. The handler's name just needs to match the camelCase version of a gesture\nevent.\n\nExample\n```js\nimport Ember from 'ember';\n\nconst {\n Component\n} = Ember;\n\nexport default Component.extend({\n panStart(e) {\n // do something with the event\n }\n});\n```\n\nGesture events bubble through the DOM, so you can use them with actions as well.\n\n```hbs\n\u003cdiv {{action \"foo\" on=\"swipeRight\"}}\u003e\n```\n\n#### Create A Recognizer\n\n`ember g recognizer \u003cname\u003e`\n\nThis will generate the file `ember-gestures/recognizers/name.js`.\nOnce you've filled out the recognizer (see [./addon/recognizers/](./addon/recognizers/) for examples),\nit will be available to use in your app just like the default recognizers.\n\n##### Note\n\nAlthough we have provided an example for `double-tap` and `single-tap` in the `addon/recognizers` folder, they\nare for demo purposes only and do not ship with the actual addon because they are non-standard. \nIf you'd like to enable these recognizers for your own app; for instance `double-tap`; execute:\n\n`ember g recognizer double-tap`\n\nAn `.app/ember-gestures/recognizers/double-tap.js` file will be created. Inspect its contents and replace\nit with the example `double-tap.js` from this addon's codebase.\n\n#### Increase the size of touchable areas to improve user experience on small controls\n\nSometimes smaller buttons or critical buttons need a larger capture area than their visible area.\nYou can increase the area that recognizes touch events for a specific button with a little bit of CSS.\n\n[Example Gist](https://gist.github.com/runspired/506f39a4abb2be48d63f)\n\n\n### Components\n\nComponents available by default include `context-element`, `fast-action`, and `fast-async`.\n\n\n### Testing\n\n\nThe jQuery events you need to trigger are the Hammer variant, meaning it is entirely lowercase `swiperight`, `panup`.\n\njQuery events come with baggage, and using the `trigger` helper executes handlers in a different order than they\nwould otherwise execute, and in some situations will cause a handler to execute twice. If you are experiencing\nissues with testing gesture events, try creating your own `trigger` helper that uses native APIs instead of jQuery\nto trigger the event.\n\n## Tips and Tricks\n\nDon't add recognizers to components created within an `{{#each}}` loop. Use a recognizer at the base of the\n`each` instead.\n\n\n## Contributing\n\nContributions are very welcome.\n\nWhen making a PR try to use the following conventions:\n\n**Commit Messages:**\n\n`type(shortname): action based description`\n\nExamples:\n\n- chore(deps): bump deps in package.json and bower.json\n- docs(component): document the `fast-action` component\n\n**Branch Naming:**\n\n`type/short-description`\n\nExamples:\n\n- chore/bump-deps\n- docs/fast-action-component\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtml-next%2Fember-gestures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhtml-next%2Fember-gestures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtml-next%2Fember-gestures/lists"}