# itemslide: a touch carousel in plain JavaScript, with no build step

> ItemSlide is a single-file vanilla JavaScript carousel that you drop into a page with a script tag, a list element and a few lines of CSS. It handles touch swiping, mousewheel scrolling, swipe out, centered or left sided layouts, and exposes eleven options, eight methods and six events, with a package version of 2.0.1 and no GitHub releases.

**nir9/itemslide** — JavaScript Touch Carousel Library with Zero Dependencies

- Repository: https://github.com/nir9/itemslide
- Website: https://itemslide.org
- Stars: 650 · Forks: 84
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nir9-itemslide

## One file, one script tag, no dependencies

ItemSlide is described in the project description as a JavaScript touch carousel library with zero dependencies, and in the README as a simple and beautiful vanilla JavaScript touch carousel. Both phrasings point at the same decision: this is a single file you load, not a package you install and bundle.

The repository layout confirms it. At the root there is itemslide.js, an index.html, a package.json, a CNAME file and a LICENSE. There is no src/ directory, no build configuration, no test directory and no linting setup. The devDependencies block in package.json is empty and the scripts block has no entries. The CNAME file is what points a GitHub Pages site at a custom domain, which for this project is itemslide.org, the homepage in the package metadata.

So the delivery model is the pre-module era of the web. You copy itemslide.js next to your page, you add a script tag, and you write the CSS yourself. There is no toolchain to adopt, no version of the toolchain to agree on, and nothing in the repository that can go stale between your build and your users' browsers.

That is a real advantage in a specific situation. A marketing site, a documentation page, a small application that has no build step at all, these are projects where adding a bundler to get a carousel would be the most expensive part of the feature. The audience is those developers, plus anyone who has inherited a static site and needs a swipeable list.

The licence is MIT, and the package metadata records the author as Nir Lichtman with the bugs and repository links pointing at the nir9/itemslide repository.

## You write the markup and the CSS, and it is only a few rules

The getting started section is short because there is very little to it. The markup is a container with a list inside it:

```html
    <div id="scrolling">
        <ul>
            <li>Slide #1</li>
            <li>Slide #2</li>
        </ul>
    </div>
```

The README says the CSS example assumes the carousel is contained within an element with the id scrolling, and the rules it needs are these:

```css
#scrolling {
    overflow: hidden;
}

#scrolling ul {
    margin: 0;
    padding: 0;
    list-style-type: none;
    position: absolute;
    transform-style: preserve;
}

#scrolling ul li {
    float: left;
}
```

Three ideas are doing the work. The container hides the overflow, which is what turns a wide row of slides into a window. The list is taken out of normal flow with position absolute, so the carousel can be moved sideways by a transform. And the slides are floated left so they sit next to each other in a single line, which is what gives the library a width to calculate and a distance to pan across.

The consequence is that the structure is not negotiable in the same way a component library's is. The library is initialized on a list element, it measures the list, and it moves that list. If your markup is not a ul of li inside a container, the width calculation has nothing sensible to work with.

Including the script is the last mechanical step:

```html
<script src="itemslide.js"></script>
```

The library is also published as a package, with the main field pointing at itemslide.js, so the same file can come in through a package manager if that suits your setup better.

## Eleven options decide how the carousel feels

Options are passed as key and value pairs into the object the Itemslide constructor receives as its second parameter, and the README gives the example:

```js
new Itemslide(element, { duration: 100 });
```

The full list is what makes the library usable, and each entry has a documented default.

duration is the duration of the slide animation, 350 milliseconds by default. swipeSensitivity sets the swiping sensitivity, 150 by default. disableSlide disables swiping and panning, false by default. disableClickToSlide disables click to slide, false by default. disableAutoWidth disables the automatic calculation of width so you can do it manually, false by default. disableScroll disables the sliding triggered by mousewheel scrolling, false by default. start is the index of the slide that appears when initializing, 0 by default.

panThreshold is described as panning sensitivity, 0.3 by default, and the README notes it is a percentage of slide width. oneItem sets whether the navigation is full screen or one slide at a time. parentWidth makes the width of the slides equal to the width of the parent of the ul. swipeOut enables the swipe out feature. And leftSided gives you a left sided carousel instead of the default force-centered one.

Two of these deserve a note. The percentage unit on panThreshold means the threshold scales with the size of a slide, so the same value behaves differently on a phone and on a desktop. And leftSided interacts with the force-centered default, which is why the README describes it as an alternative rather than a modifier.

The last entry, swipeOut, is listed with an opening parenthesis that the README never closes, so its description is cut off. That is a documentation gap rather than a mystery, and the events section tells you what the feature does.

## Eight methods, and the resize call you have to remember

The method list is small and mostly self explanatory. getActiveIndex() returns the current active slide index, getCurrentPos() returns the current position of the carousel in pixels, nextSlide() and previousSlide() move one slide in either direction, and gotoSlide(i) goes to a slide by index.

Then there are the three that matter for a real application.

reload() recalculates the width and centers the object, and the README explicitly recommends calling it when a resize occurs. This is the library's most significant rough edge. The carousel measures its container once at initialization, and the README does not describe any window resize listener, so a responsive layout that changes width will leave the carousel with a stale measurement until you tell it otherwise. If your page is inside a resizable panel, or the device rotates, you need to call reload() yourself, for example from your own resize handler.

addSlide(data) appends a new item to the end of the carousel, and the README notes that it automatically adds li tags, so you pass content rather than markup. removeSlide(index) removes a slide by index. Together they let you build a carousel from data that arrives after the page has loaded, which is the usual reason to reach for a script at all rather than writing the list in HTML.

The combination of addSlide and removeSlide with an index-based API does mean you are responsible for keeping indices meaningful yourself. If you remove a slide, the active index may now point at a different piece of content, and the library gives you no callback for that.

## Six events, one class and one escape hatch

ItemSlide triggers events on the element it was initialized on, which is the integration point for anything the library does not do for you.

The six events are carouselChangePos, triggered when the position of the carousel changes, carouselPan, triggered when the user pans, carouselChangeActiveIndex, triggered when the current active item changes, carouselSwipeOut, triggered when the user swipes out a slide if swipeOut is enabled, and carouselClickSlide, triggered when clicking or tapping a slide.

Two of them carry data. The swipe out event exposes event.slideIndex, the index of the swiped out slide, and the click event exposes event.slideIndex for the clicked slide. Those two indices are what you need in order to do something in response, such as removing the element from the DOM or opening a detail view.

For state, there is a single class. The current active slide gets the itemslide-active class, which means you can style the active item from CSS and you can query it from your own code, since the class is applied to the DOM rather than tracked only inside the library.

And there is one escape hatch for the common annoyance case. The no-drag attribute disables dragging on a particular element inside the carousel, with the example given as an li with no-drag="true". That is how you keep a control inside a slide, a link or a button, from starting a pan when the user touches it.

## Swipe out needs a handler, and the README leaves a gap

Swipe out is the one feature that is not a vanilla carousel behaviour, and it is off by default.

The option is set to true to enable it, and the corresponding event is carouselSwipeOut, which carries the index of the swiped slide. In other words, the library detects the gesture and tells you about it, and what happens to the slide is your code's business. That is a sensible division of labour, since deleting content is not something a carousel should decide on its own, and it lets you show a confirmation, animate the removal, or undo it.

The gap is in the documentation. The options list describes swipeOut as set this to true to enable the swipe out feature, and the line ends with an opening parenthesis that is never closed, so whatever the original sentence intended to say about the behaviour of the swiped slide is missing from the README. The events section says only that the event is triggered when the user swipes out a slide, and that event.slideIndex gives the index.

If swipe out is the feature you are after, that is the question to ask on the project issue tracker rather than to assume. The wiki on the repository, and the homepage at itemslide.org, are where the rest of the documentation lives.

For everyone else, the rest of the option list is complete enough to build with, and the only behaviour worth planning around is the manual resize handling.

## The repository is one file, and the last push was in April

The maintenance picture is the part to weigh before you depend on this.

The last push to the repository was on 2026-04-10, and there are no GitHub releases. The package version in package.json is 2.0.1, and the repository entries are .github/, .gitignore, CNAME, LICENSE, README.md, index.html, itemslide.js and package.json. There is no CHANGELOG, no test suite and no CI configuration beyond the .github directory.

So this is a project whose entire deliverable is a single JavaScript file, and that file is small enough to read in full. That cuts both ways. It means there is no dependency to break, no build output to regenerate and no framework version to align with, and the risk of adopting it is close to zero. It also means that if a browser changes a behaviour the library depends on, there is no test suite to catch the regression and no release process to ship a fix through.

The absence of releases is consistent with that. With one file and a stable interface, a tagged release adds little, so the download is the master branch. The trade is that you are tracking a moving file rather than a pinned version, and if you need reproducibility, copy itemslide.js into your own repository instead of linking to it.

The licence is MIT, so embedding and modifying the file carries no obligation beyond the notice, which is the least complicated licensing situation a front end component can have.

## Conclusion

itemslide suits teams that want a swipeable carousel in a page that has no build pipeline, since the whole library is one file loaded with a script tag and the only CSS you must write is the overflow and float rules the README shows. It does not suit a project that needs server rendering, framework lifecycle integration or automated layout on resize, and it does not suit a team that wants a maintained release train. Check three things before you adopt it: that you are willing to call reload() on resize, since the README recommends it and the library does not observe the window for you, that your slides are list items in a single list element, which is what the CSS and the width calculation assume, and that you read the option list rather than the marketing, because the swipe out option is off by default and its documentation is incomplete in the README. The last push to the repository was on 2026-04-10.

## FAQ

### How do I add itemslide to a page?

Load the script with a script tag pointing at itemslide.js, put your slides in a ul inside a container, add the CSS from the README, then initialize it on the list element with new Itemslide(element, {}) inside a window load listener.

### What are the available itemslide options?

duration, swipeSensitivity, disableSlide, disableClickToSlide, disableAutoWidth, disableScroll, start, panThreshold, oneItem, parentWidth, swipeOut and leftSided, each with a documented default such as a 350ms animation duration and a pan threshold of 0.3 of the slide width.

### What happens when the window is resized?

The carousel does not recalculate itself. The README says reload() recalculates the width and centers the object and recommends calling it when a resize occurs, so you need to trigger it yourself from your own resize handling.

### Which events does itemslide trigger?

carouselChangePos, carouselPan, carouselChangeActiveIndex, carouselSwipeOut, which carries event.slideIndex, and carouselClickSlide, which also carries event.slideIndex. The current active slide also receives the itemslide-active class.

### Can I stop dragging on a single element inside a slide?

Yes. Add the no-drag attribute to that element, with the README giving an li with no-drag="true" as the example, and dragging is disabled on it only.

## Sources

- [Issues](https://github.com/nir9/itemslide/issues)
- [License: MIT](https://github.com/nir9/itemslide/blob/master/LICENSE)
- [nir9/itemslide on GitHub](https://github.com/nir9/itemslide)
- [Project website](https://itemslide.org)
- [README](https://github.com/nir9/itemslide/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nir9-itemslide