Vue Alphabetical Scroll Bar

A highly responsive, simple, and customizable alphabetical scroll bar for Vue 3 projects.

This is a migration of the original Angular project alphabetical-scroll-bar to Vue 3.

Features

• ✅ Custom alphabet: Use your own alphabet
• ✅ Ñ support: Includes the Ñ letter in the default alphabet
• ✅ Cross-platform: iOS, Android, and Web
• ✅ Responsive: Adapts to different screen sizes
• ✅ Visual effects: Letter magnification on touch/hover
• ✅ Valid letters: Only shows letters that exist in your content
• ✅ Hover navigation: Works with both touch and hover
• ✅ TypeScript: Full type support
• ✅ Vue 3: Composition API friendly

Installation

npm install vue-alphabetical-scroll-bar

Quick Start

Global Import

import { createApp } from 'vue'
import VueAlphabeticalScrollBar from 'vue-alphabetical-scroll-bar'
import 'vue-alphabetical-scroll-bar/dist/style.css'

const app = createApp(App)
app.use(VueAlphabeticalScrollBar)
app.mount('#app')

Local Import

<template>
  <div class="content-wrapper">
    <AlphabeticalScrollBar
      :alphabet="'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ'"
      :valid-letters="letterGroups"
      :letter-magnification="true"
      :navigate-on-hover="true"
      @letter-change="goToLetterGroup"
      @is-active="handleActiveChange"
    />
    
    <div class="names-container">
      <!-- Your content here -->
    </div>
  </div>
</template>

<script setup lang="ts">
import { AlphabeticalScrollBar } from 'vue-alphabetical-scroll-bar'

const letterGroups = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'Ñ', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z']

const goToLetterGroup = (letter: string) => {
  const element = document.getElementById(`section-${letter}`)
  element?.scrollIntoView({ behavior: 'smooth' })
}

const handleActiveChange = (active: boolean) => {
  console.log('Scroll bar active:', active)
}
</script>

Import Styles

Don't forget to import the CSS styles:

// In your main.ts or main.js
import 'vue-alphabetical-scroll-bar/dist/style.css'

Or in your component:

<style>
@import 'vue-alphabetical-scroll-bar/dist/style.css';
</style>

Ñ Support

The component includes native support for the Ñ letter in the Spanish alphabet. Ñ is correctly positioned between N and O, following the standard Spanish alphabetical order.

Default Alphabet

ABCDEFGHIJKLMNÑOPQRSTUVWXYZ

Spanish Sorting

The component uses localeCompare with the 'es' locale to properly sort words containing Ñ and other Spanish-specific characters.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | alphabet | string \| string[] | 'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ' | Custom alphabet | | overflowDivider | string \| undefined \| null | '·' | Divider for small screens | | validLetters | string[] | [...'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ'] | Available valid letters | | disableInvalidLetters | boolean | false | Disable invalid letters | | prioritizeHidingInvalidLetters | boolean | false | Prioritize hiding invalid letters | | letterMagnification | boolean | true | Magnification effect | | magnifyDividers | boolean | false | Magnify dividers | | magnificationMultiplier | number | 2 | Magnification multiplier | | magnificationCurve | number[] | [1, 0.7, 0.5, 0.3, 0.1] | Magnification curve | | exactX | boolean | false | Exact navigation on the X axis | | navigateOnHover | boolean | false | Navigate on hover | | letterSpacing | string \| number | '1%' | Spacing between letters | | offsetSizeCheckInterval | number | 0 | Interval for size checks |

Events

| Event | Payload | Description | |-------|---------|-------------| | letterChange | string | Emitted when a new letter is selected | | isActive | boolean | Emitted when the active state changes |

Examples

Basic Example

Simple alphabetical list with names:

<template>
  <div class="example">
    <AlphabeticalScrollBar
      :alphabet="'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ'"
      :valid-letters="availableLetters"
      @letter-change="goToLetter"
    />
    <div class="content">
      <div v-for="letter in alphabet" :key="letter" :id="`section-${letter}`">
        <h2>{{ letter }}</h2>
        <ul>
          <li v-for="name in getNamesByLetter(letter)" :key="name">{{ name }}</li>
        </ul>
      </div>
    </div>
  </div>
</template>

List Example

Enhanced list with search functionality:

<template>
  <div class="list-example">
    <input v-model="searchTerm" placeholder="Search names..." />
    <AlphabeticalScrollBar
      :alphabet="'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ'"
      :valid-letters="availableLetters"
      @letter-change="goToLetter"
    />
    <div class="names-list">
      <div v-for="letter in sortedLetters" :key="letter" :id="`section-${letter}`">
        <h2>{{ letter }}</h2>
        <div class="names-grid">
          <div v-for="name in getNamesByLetter(letter)" :key="name" class="name-item">
            <div class="avatar">👤</div>
            <span class="name">{{ name }}</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

Custom Components Example

Advanced example with custom card components:

<template>
  <div class="custom-example">
    <input v-model="searchTerm" placeholder="Search items..." />
    <div class="filters">
      <button v-for="category in categories" :key="category">
        {{ category }}
      </button>
    </div>
    
    <AlphabeticalScrollBar
      :alphabet="'ABCDEFGHIJKLMNÑOPQRSTUVWXYZ'"
      :valid-letters="availableLetters"
      @letter-change="goToLetter"
    />
    
    <div class="items-grid">
      <div v-for="letter in sortedLetters" :key="letter" :id="`section-${letter}`">
        <h2>{{ letter }}</h2>
        <div class="cards-grid">
          <ItemCard 
            v-for="item in getItemsByLetter(letter)" 
            :key="item.id"
            :item="item"
            @quantity-change="updateQuantity"
          />
        </div>
      </div>
    </div>
  </div>
</template>

Development

# Install dependencies
npm install

# Run dev server
npm run dev

# Build for production
npm run build

# Type-check
npm run type-check

Browser Support

• Chrome >= 60
• Firefox >= 60
• Safari >= 12
• Edge >= 79

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

1.0.0

• Initial release
• Vue 3 support with Composition API
• TypeScript support
• Ñ letter support for Spanish alphabet
• Responsive design
• Touch and hover navigation
• Customizable alphabet and styling