v7.0.0

Migrating from Shuffle v6 to v7

Overview

Shuffle v7 is a major modernization that moves the library to pure ESM, TypeScript source code, and ES2024 as the compilation target. While this includes breaking changes around module format and browser support, the public API remains fully backward compatible. For most ESM users, upgrading should be straightforward.

Breaking Changes

1. ESM-Only (No CommonJS Support)

Shuffle v7 is distributed as pure ESM with type=module and no longer provides CommonJS builds.

Before (v6):

// CommonJS
const Shuffle = require('shufflejs');

// ESM
import Shuffle from 'shufflejs';

After (v7):

// ESM only
import Shuffle from 'shufflejs';

Migration: If you're using CommonJS (require), you must migrate your project to use ES modules. Most modern bundlers (Webpack 5+, Vite, Rollup) handle ESM natively.

2. Build Output Changes

The package structure has changed significantly:

v6 Package Exports:

{
  "main": "./dist/shuffle.js",
  "module": "./dist/shuffle.esm.js",
  "exports": {
    "types": "./index.d.ts",
    "require": "./dist/shuffle.js",
    "default": "./dist/shuffle.esm.js"
  },
  "types": "./index.d.ts"
}

v7 Package Exports:

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/shuffle.d.mts",
      "default": "./dist/shuffle.mjs"
    },
    "./package.json": "./package.json"
  },
  "types": "./dist/shuffle.d.mts"
}

What Changed:

• ❌ No more UMD build (dist/shuffle.js)
• ❌ No more separate minified files
• ✅ Single ESM build (dist/shuffle.mjs)
• ✅ TypeScript definitions generated from source (.d.mts)

Migration: If you were directly referencing build files (e.g., in a <script> tag), you'll need to use a bundler or import maps. For users importing via a package manager, no changes needed.

3. ES2024 Target

Shuffle v7 is compiled to ES2024, which means older browsers may need transpilation.

Minimum Browser Versions:

• Chrome 123+ (March 2024)
• Firefox 125+ (April 2024)
• Safari 17.4+ (March 2024)
• Edge 123+ (March 2024)
• Node.js 24+ (for server-side usage)

Migration: If you need to support older browsers:

• Configure your bundler (Webpack, Vite, etc.) to transpile node_modules/shufflejs
• Use Babel or SWC with appropriate presets
• Ensure polyfills are available if needed

4. Private Class Fields

Internal methods now use JavaScript private fields (#method) instead of underscore-prefixed methods (_method).

v6:

// These were technically accessible (but undocumented)
shuffle._filter(items);
shuffle._layout();

v7:

// These are now truly private and will throw errors
shuffle.#filter(items); // ❌ SyntaxError
shuffle.#layout(); // ❌ SyntaxError

Migration: If you were accessing private methods, you'll need to use the public API equivalents:

5. Private Static Fields

The double-underscored static methods have been removed.

6. External Dependencies

The external dependencies tiny-emitter and array-parallel have been copied and migrated to TS + ESM.

New Features & Improvements

TypeScript Type Exports

All types are now properly exported for enhanced type safety:

import Shuffle, {
  type ShuffleOptions,
  type FilterArg,
  type FilterFunction,
  type SortOptions,
  type ShuffleEventData,
  type ShuffleEventCallback,
  type InlineCssStyles,
} from 'shufflejs';

const options: ShuffleOptions = {
  itemSelector: '.card',
  speed: 500,
};

const shuffleInstance = new Shuffle(element, options);

Typed Event System

Events are now fully typed for better autocomplete and type checking:

import Shuffle, { type ShuffleEventData } from 'shufflejs';

const shuffle = new Shuffle(element);

// Type-safe event handlers
shuffle.on('shuffle:layout', (data: ShuffleEventData) => {
  console.log(data.shuffle); // Correctly typed as Shuffle instance
});

shuffle.once('shuffle:removed', (data) => {
  // data is automatically typed
  console.log(data.collection); // HTMLElement[]
});

v6.1.2

Update old username links and dev dependencies

Full Changelog: v6.1.1...v6.1.2

6.1.1

What's Changed

• Fix copy paste in docs by @vestride in https://github.com/Vestride/Shuffle/pull/497
• Fix some typos by @ydah in https://github.com/Vestride/Shuffle/pull/555
• Fix missing types when resolving from exports field in package.json by @Schleuse in https://github.com/Vestride/Shuffle/pull/561
• update dependencies by @vestride in https://github.com/Vestride/Shuffle/pull/562

New Contributors

• @ydah made their first contribution in https://github.com/Vestride/Shuffle/pull/555
• @Schleuse made their first contribution in https://github.com/Vestride/Shuffle/pull/561

Full Changelog: vestride/Shuffle@v6.1.0...v6.1.1

v6.1.0

New features

• The package.json now contains sideEffects: false to improve dead code removal and tree shaking.
  • https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free
• The package.json now contains an export-map to assist bundlers in choosing the correct file.

Bug fixes

• Update index.d.ts (in #402) to be more accurate with the real code.

Internal

• Shuffle is now a monorepo, built with turborepo (#399).
• Rewrote the website with Docusaurus.

Full Changelog: vestride/Shuffle@v6.0.0...v6.1.0

v6

Breaking

• Remove IE 11 from browsers list. If you need to support IE 11 (sorry), please use v5. Did you know Microsoft 365 apps and services stopped supporting IE 11 in August 2021?
• Remove matches-selector package and use the native matches (see browser support).
• Remove deprecated delimeter option (the misspelled one). Use the delimiter option instead.
• Replace window resize event listener with ResizeObserver (#321). Browser support for it is very good, but if you want to support a browser that doesn't have it, you can manually add a window resize event and call update() within the event callback.
  • Removed throttleit dependency
  • Removed throttle option.
  • Removed throttleTime option.
• Changed the method signature for update().

  -shuffle.update(true);
  +shuffle.update({ recalculateSizes: false });

• Changed how data attribute are accessed. Previously, Shuffle used element.getAttribute('data-groups'). Now, it uses element.dataset.groups. dataset is very well supported now.

New features

• Minified file size
  • Before: 20.8 kB
  • After: 16.9 kB
• Added force option to update method to force shuffle to update even if it's disabled (#321).

  shuffle.update({ force: true });
  

Other

• Convert demos to ES6 classes.
• Move browsers list to .browserslistrc.
• Add prettier
• Add BMC button.
• Remove polyfill.io links -- they add nothing with current versions of Chrome and others.
• Run sass division migration
• Remove dist files from git
• Recreate demos to codepen. Collection.
  • basic layout
  • homepage demo
  • compound filters
  • images
  • image problems
  • adding and removing
  • animated viewport entry
  • bootstrap 3 grid
  • bootstrap 4 grid
  • flexbox grid
  • with react
  • ajax
  • Shuffle v5 with IE9

v5.4.1

• Add sortedItems property which is the shuffle items in sorted order. Only visible items are in this array.
• Fix Chrome DPI bug described in #314 that was causing column sizes to be calculated incorrectly.

v5.3.0

Add isRTL option thanks to @AmirHosseinKarimi

Add TinyEmitter methods to TypeScript definitions

The TypeScript definitions were missing on, once, emit, and off because the definitions file did not have extends TinyEmitter. These methods now work correctly and contain type information for the data object in the event callback.

v5.2.2

Jest

Moved to jest for testing #278

TypeScript definitions #287

Fixes

• Fix bad default parameters for enable, update, and getSize.
• Fix missing Css export on Shuffle.ShuffleItem.Css.
• Fix Shuffle.ALL_ITEMS and Shuffle.FILTER_ATTRIBUTE_KEY not being overridable.

New

• Add types for .sort() method's options: SortOptions.
• Add types for .filter()'s function signature.
• Add types for ShuffleItem.Css.

Tests

• Add test ts file.
• Run tsc on test file during tests.

Breaking for TypeScript users:

• Changed all Element to HTMLElement.
• Shuffle.ShuffleOptions is now exported top-level.

  import Shuffle, { ShuffleOptions, SortOptions } from 'shufflejs';

Full changes: vestride/Shuffle@v5.2.1...v5.2.2

v5.2.1

Change typings to use default export #214

-export = Shuffle;
+export default Shuffle;

Upgraded dev dependencies to their latest versions:

• rollup
• terser
• babel
• eslint

Removed @odopod/eslint as I no longer have write access to Odopod's repos.

vestride/Shuffle@v5.2.0...v5.2.1