{"id":13525863,"url":"https://github.com/xiaody/react-touch-carousel","last_synced_at":"2025-05-16T15:09:32.007Z","repository":{"id":22777749,"uuid":"97292798","full_name":"xiaody/react-touch-carousel","owner":"xiaody","description":"Ultra-customizable carousel framework for React.JS","archived":false,"fork":false,"pushed_at":"2024-06-18T05:36:15.000Z","size":5202,"stargazers_count":298,"open_issues_count":20,"forks_count":64,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-12T14:17:19.201Z","etag":null,"topics":["carousel","inversion-of-control","javascript","react","react-component","swipe"],"latest_commit_sha":null,"homepage":"https://xiaody.github.io/react-touch-carousel/docs/","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/xiaody.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,"zenodo":null}},"created_at":"2017-07-15T04:47:11.000Z","updated_at":"2024-07-10T18:09:41.000Z","dependencies_parsed_at":"2024-01-13T22:25:00.617Z","dependency_job_id":"fa44d3fe-0da7-477e-b2a2-8d19714b9858","html_url":"https://github.com/xiaody/react-touch-carousel","commit_stats":{"total_commits":115,"total_committers":6,"mean_commits":"19.166666666666668","dds":"0.32173913043478264","last_synced_commit":"376e90121939bcf2e9395d091ed6200ad45600dd"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaody%2Freact-touch-carousel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaody%2Freact-touch-carousel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaody%2Freact-touch-carousel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaody%2Freact-touch-carousel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaody","download_url":"https://codeload.github.com/xiaody/react-touch-carousel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254057665,"owners_count":22007544,"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":["carousel","inversion-of-control","javascript","react","react-component","swipe"],"created_at":"2024-08-01T06:01:22.926Z","updated_at":"2025-05-16T15:09:26.999Z","avatar_url":"https://github.com/xiaody.png","language":"JavaScript","readme":"[![Node.js CI](https://github.com/xiaody/react-touch-carousel/actions/workflows/node.js.yml/badge.svg)](https://github.com/xiaody/react-touch-carousel/actions/workflows/node.js.yml)\n[![npm version](https://badge.fury.io/js/react-touch-carousel.svg)](https://www.npmjs.com/package/react-touch-carousel)\n[![dependencies Status](https://david-dm.org/xiaody/react-touch-carousel/status.svg)](https://david-dm.org/xiaody/react-touch-carousel)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://standardjs.com/)\n\n# react-touch-carousel\n\nMicro carousel framework for React.JS https://xiaody.github.io/react-touch-carousel/docs/\n\nYes, there are [a][slick] [few][Swiper] [carousel][Owl Carousel 2] [libraries][react-swipe] out there.\nMost of them are mature and easy to use for common usage,\nbut none of them are convenient for the highly customized fancy UX that your team's cool designer wants.\n\nreact-touch-carousel does it in a different way.\nInstead of accepting some static DOM nodes and providing a thousand options,\nit does an inversion of control and lets you decide\nwhat content inside carousel are rendered and how they are styled, totally and dynamically.\n\n## Installation\n\nTo install the stable version:\n\n```\nnpm install --save react-touch-carousel\n```\n\n## Usage\n\n```jsx\nimport TouchCarousel from 'react-touch-carousel'\n\nconst listOfData = [\n  // your data array here\n]\n\nfunction CarouselContainer (props) {\n  // render the carousel structure\n}\n\nfunction renderCard (index, modIndex, cursor) {\n  const item = listOfData[modIndex]\n  // render the item\n}\n\n\n\u003cTouchCarousel\n  component={CarouselContainer}\n  cardCount={listOfData.length}\n  cardSize={375}\n  renderCard={renderCard}\n  loop\n  autoplay={3000}\n/\u003e\n```\n\nThe `CarouselContainer()` and `renderCard()` are where all the magic happens,\nwhich shall be directed by you.\nSee some detailed [examples](https://github.com/xiaody/react-touch-carousel/tree/master/examples).\n\n## Options\n\n### props.component {Component}\n\nYour container component of the carousel.\n\nreact-touch-carousel will pass it's touch listeners, dragging/active state, current position cursor to this component.\n\nIt is actually called like this:\n\n```jsx\n\u003cComponent\n  cursor={usedCursor}\n  carouselState={carouselState}\n  onTouchStart={onTouchStart}\n  onTouchMove={onTouchMove}\n  onTouchEnd={onTouchEnd}\n  onTouchCancel={onTouchCancel}\n\u003e\n  {allYourRenderedCards}\n\u003c/Component\u003e\n```\n\n### props.renderCard(index, modIndex, cursor, carouselState) {Function}\n\nThe card renderer.\n\nAll rendered cards joined as an array will be passed to props.component as it's `children`.\n\n### props.cardCount {Number}\n\nThe count of your cards, not including the padded ones.\n\n### props.cardPadCount {Number}\n\nThe count of padded cards, necessary for looping.\n\nIgnored if `loop` is `false`.\n\n### props.cardSize {Number}\n\nThe width (or height if `vertical` is `true`) in pixels of a card.\n\n### props.vertical {Boolean}\n\nListen to vertical touch moves instead of horizontal ones. Default `false`.\n\n### props.loop {Boolean}\n\nTail to head, head to tail. Default `true`.\n\n### props.autoplay {Number}\n\nInterval in milliseconds, 0 as disabled. Default `0`.\n\n### props.defaultCursor {Number}\n\nThe cursor value for initial render.\n\nNotice the sign of the number, normally it should be negative or zero(default).\n\n### props.onRest(index, modIndex, cursor, carouselState) {Function}\n\nCallback when the carousel is rested at a card.\n\n### props.onDragStart/onDragEnd/onDragCancel\n\nAdd some listeners if you need.\n\n### props.ignoreCrossMove {Number|Boolean}\n\nIf `deltCrossAxis * ignoreCrossMove \u003e deltMainAxis`, carousel would ignore the dragging.\n\n`true` as `1` and `false` as `0`. Default `true`.\n\n## Concepts\n\n### Cursor\n\nA cursor indicates the transition position of the carousel.\n\nWhen the user swipes right, the number gets bigger. When the user swipes left, the number get smaller.\n\nThere are three steps to calculating the cursor's final value:\nspecified, computed, used.\n\nIn most cases you just use the used cursor value to render your carousel content.\n\n### CarouselState\n\nA carouselState is always passed to your `component` and `renderCard`.\n\nIt contains:\n```js\n{\n  cursor, // the specified cursor\n  active, // is user interacting with the component, no matter dragging or pressing or clicking?\n  dragging, // is user dragging the component?\n  springing, // has user dragged and released the component, and the component is transitioning to the specified cursor?\n  moding // is the cursor moding?\n}\n```\n\n### Mod\n\nThis happens if you enable `loop`. We keep the cursor in a valid range by \"moding\" it.\n\n## Advanced options\n\nThere are some advanced options, but normally you don't need to touch them.\n\n## Methods\n\n### go(targetCursor)\n\nTransition to a position.\n\n### next()\n\nTransition to next card.\n\n### prev()\n\nTransition to previous card.\n\n### modAs(targetCursor)\n\nHard jump to a position.\n\n## Mouse support\n\nWe provide an HOC for very basic mouse support. Internally it simulates touch events with the mouse events.\n\n```jsx\nimport touchWithMouseHOC from 'react-touch-carousel/lib/touchWithMouseHOC'\n\nconst Container = touchWithMouseHOC(CarouselContainer)\n\n\u003cTouchCarousel\n  component={Container}\n/\u003e\n```\n\n[slick]: https://kenwheeler.github.io/slick/\n[Swiper]: http://idangero.us/swiper/\n[Owl Carousel 2]: https://owlcarousel2.github.io/OwlCarousel2/\n[react-swipe]: https://github.com/voronianski/react-swipe\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaody%2Freact-touch-carousel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaody%2Freact-touch-carousel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaody%2Freact-touch-carousel/lists"}