Xer - Simple Horizontal Scroll Component

A lightweight, accessible horizontal drag-to-scroll component for React and vanilla JavaScript.

Features

• 🎯 Simple Integration: Just wrap your items and it works
• ♿ Accessible: Built-in accessibility features
• 📱 Touch Friendly: Optimized for touch devices
• ⚡ Lightweight: Minimal bundle size
• 🎭 Smooth Animations: Inertia scrolling and smooth interactions
• 🎨 Customizable: Flexible styling options
• 🔄 Auto-Structure: Automatically creates proper ul/li structure
• 🌐 SSR Compatible: Works with Next.js, Gatsby, and other SSR frameworks
• 🚀 Universal Import: One import works for both React and Vanilla

Installation

npm install @pierregoeddertz/ii-ii-ii

Usage

Universal Import (Recommended)

// Works in both React and Vanilla environments!
import Xer from '@pierregoeddertz/ii-ii-ii';
import '@pierregoeddertz/ii-ii-ii/css';

// React
function MyComponent() {
  return (
    <Xer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </Xer>
  );
}

// Vanilla
const container = document.getElementById('my-scroll-container');
const xer = new Xer(container, { center: true });

Next.js (App Router)

// app/page.tsx
import Xer from '@pierregoeddertz/ii-ii-ii';
import '@pierregoeddertz/ii-ii-ii/css';

export default function Page() {
  return (
    <div>
      <h1>My App</h1>
      <Xer>
        <div>Item 1</div>
        <div>Item 2</div>
        <div>Item 3</div>
      </Xer>
    </div>
  );
}

Explicit Version Selection

// React-specific import
import Xer from '@pierregoeddertz/ii-ii-ii/react';

// Vanilla-specific import
import Xer from '@pierregoeddertz/ii-ii-ii/vanilla';

// CSS
import '@pierregoeddertz/ii-ii-ii/css';

Vanilla JavaScript Version

<ul id="my-scroll-container">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <!-- Add more items -->
</ul>

<script type="module">
  import Xer from '@pierregoeddertz/ii-ii-ii';
  import '@pierregoeddertz/ii-ii-ii/css';
  
  const container = document.getElementById('my-scroll-container');
  const xer = new Xer(container, {
    center: true,
    direction: 'ltr',
    gap: '1rem',
    padding: '1rem'
  });
</script>

SSR Compatibility

Xer is fully SSR compatible and works with:

• ✅ Next.js (App Router & Pages Router)
• ✅ Gatsby
• ✅ Remix
• ✅ Nuxt.js
• ✅ Vite SSR
• ✅ Any React SSR framework

The component automatically:

• Renders the correct HTML structure during SSR
• Hydrates interactivity on the client
• Handles browser APIs safely
• Maintains accessibility during SSR

How It Works

The component automatically:

• Creates the proper ul/li structure
• Handles drag-to-scroll interactions
• Provides smooth inertia scrolling
• Works on both desktop and mobile
• Hides scrollbars for a clean look
• Includes full accessibility support
• Renders safely during SSR
• Auto-detects React vs Vanilla environment

API

React Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | React.ReactNode | - | Content to render | | className | string | '' | Additional CSS classes | | ariaLabel | string | 'Horizontal list frame' | ARIA label | | ariaDescription | string | - | ARIA description | | role | string | 'region' | ARIA role | | center | boolean | true | Center content | | direction | 'ltr' \| 'rtl' | 'ltr' | Text direction | | gap | string | '1rem' | Gap between items | | padding | string | '1rem' | Container padding |

Vanilla JavaScript Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | center | boolean | true | Center content | | direction | 'ltr' \| 'rtl' | 'ltr' | Text direction | | gap | string | '1rem' | Gap between items | | padding | string | '1rem' | Container padding | | inertiaDecay | number | 0.92 | Inertia scroll decay | | dragThreshold | number | 10 | Drag threshold in pixels |

Examples

Basic Usage

// Universal import - works everywhere!
import Xer from '@pierregoeddertz/ii-ii-ii';

// React
<Xer>
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</Xer>

// Vanilla
const container = document.querySelector('.scroll-container');
new Xer(container);

Custom Styling

// React
<Xer className="custom-scroll" gap="2rem" padding="2rem">
  <div>Item 1</div>
  <div>Item 2</div>
</Xer>

// Vanilla
new Xer(container, {
  gap: '2rem',
  padding: '2rem'
});

RTL Support

// React
<Xer direction="rtl">
  <div>Item 1</div>
  <div>Item 2</div>
</Xer>

// Vanilla
new Xer(container, { direction: 'rtl' });

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT © II-II-II