Installation & Setup

Quick Start

SEO Select is available as an NPM package and can be integrated into any modern web project. Choose your preferred installation method and framework below.

NPM Installation

Install via NPM for most JavaScript projects:

npm install seo-select

Basic Import & Usage

After installation, import the components and TypeScript types into your project:

// Import the components (auto-registers custom elements)
import 'seo-select';

// Import search-enabled select component
import 'seo-select/components/seo-select-search';

// Import Style
import 'seo-select/styles'

// Import TypeScript types for better development experience
import 'seo-select/types';

// Optional: Import specific component types for custom integrations
import type { SeoSelectElement, SeoSelectSearchElement } from 'seo-select/types';

📦 Single import enables global component availability across your entire application

HTML Usage Examples

Once imported, use the components directly in your HTML with full TypeScript support:


<seo-select name="example" width="200px">
    <option value="option1">Option 1</option>
    <option value="option2" selected>Option 2</option>
    <option value="option3">Option 3</option>
</seo-select>


<seo-select-search multiple name="skills" width="300px">
    <option value="js">JavaScript</option>
    <option value="ts">TypeScript</option>
    <option value="react">React</option>
</seo-select-search>


<seo-select 
    dark 
    theme="float" 
    texts='{"placeholder": "Choose an option"}'
    name="themed">
    <option value="1">Dark Option 1</option>
    <option value="2">Dark Option 2</option>
</seo-select>

🏷️ Standard HTML syntax with enhanced attributes and automatic TypeScript IntelliSense

JavaScript API Usage

Programmatic control and dynamic option management:

// Get element reference
const selectElement = document.querySelector('seo-select[name="example"]');

// Set options programmatically
selectElement.optionItems = [
    { value: 'js', label: 'JavaScript' },
    { value: 'ts', label: 'TypeScript' },
    { value: 'react', label: 'React' }
];

// Set/get current selection
selectElement.value = 'js';
console.log(selectElement.value); // 'js'

// Multiple selection
selectElement.selectedValues = ['js', 'react'];
console.log(selectElement.selectedValues); // ['js', 'react']

// Dynamic option management
selectElement.addOption({ value: 'vue', label: 'Vue.js' });
selectElement.clearOption('js');
selectElement.clearAllOptions();

⚙️ Rich JavaScript API for dynamic option management and programmatic control

Event Handling

Comprehensive event system for user interactions and form integration:

const selectElement = document.querySelector('seo-select[name="example"]');

// Custom component events
selectElement.addEventListener('onSelect', (event) => {
    console.log('Selected:', event.detail);
    // { label: 'JavaScript', value: 'js' }
});

selectElement.addEventListener('onDeselect', (event) => {
    console.log('Deselected:', event.detail);
});

selectElement.addEventListener('onReset', (event) => {
    console.log('Reset to:', event.detail);
});

// Standard form events
selectElement.addEventListener('change', (event) => {
    console.log('Form change:', event.target.value);
});

// For search components
const searchElement = document.querySelector('seo-select-search');
searchElement.addEventListener('onSearch', (event) => {
    console.log('Search query:', event.detail.query);
});

📡 Rich event system supporting both custom component events and standard form events

Basic Select Usage

Overview

SEO Select provides two main implementation methods: the recommended slot-based approach using standard HTML option tags, and a fallback array-based method for dynamic content. Both methods support full keyboard navigation, form integration, and accessibility features.

Slot Method (Recommended)

The slot-based approach uses standard HTML <option> tags as children, providing semantic HTML structure and better SEO compatibility. This method maintains the original HTML form behavior while adding enhanced functionality.

<seo-select name="brand" width="200px">
    <option value="kia">Kia Motors</option>
    <option value="hyundai" selected>Hyundai Motor</option>
    <option value="bmw">BMW</option>
    <option value="benz">Mercedes-Benz</option>
</seo-select>

💡 Uses standard HTML option tags with selected attribute support

Array Method (Fallback)

When slot content is not available or when options need to be populated dynamically through JavaScript, the array method provides a programmatic interface using the optionItems property.

// JavaScript to populate the select
const selectElement = document.querySelector('seo-select[name="brand-alt"]');
selectElement.optionItems = [
    { value: 'kia', label: 'Kia Motors' },
    { value: 'hyundai', label: 'Hyundai Motor' },
    { value: 'bmw', label: 'BMW' },
    { value: 'benz', label: 'Mercedes-Benz' }
];
selectElement.value = 'hyundai';

🔧 Populated via JavaScript optionItems property - ideal for dynamic content

Keyboard Navigation & Accessibility

Full keyboard navigation support includes Tab for focus, Arrow keys for option navigation, Enter for selection, Escape to close, and Space for dropdown toggle. Screen reader compatible with proper ARIA attributes.

⌨️ Try Tab, Tab + Shift, Arrow keys, Enter, Escape - fully accessible navigation

Event Handling System

Comprehensive event system with custom events (onSelect, onDeselect, onReset) and standard form events (change, input). All events provide detailed information about the selection state and can be used for form validation and data processing.

📊 Watch console and event log above for detailed interaction tracking

Search Select Components

Multilingual Search Engine

Advanced search functionality supporting Korean initial consonants (초성), Japanese romaji conversion, Chinese pinyin, and fuzzy English matching. Optimized for large datasets with virtual scrolling and intelligent caching.

Multilingual Search Capabilities

The search system supports multiple languages and input methods: Korean initial consonant matching (ㅅㅇ → 서울), Japanese romaji conversion (tokyo → 東京), Chinese pinyin support, and English fuzzy matching. Case-insensitive with accent normalization.

🔍 Search Examples:

Korean: "서울", "ㅅㅇ" (initial consonants), "런던", "ㄹㄷ"
Japanese: "東京", "とうきょう", "tokyo" (romaji)
Chinese: "北京", "上海", "beijing", "shanghai"
English: "new", "NEW", "london" (case insensitive)

🌏 Advanced multilingual search with intelligent matching algorithms

Asynchronous Loading States

Built-in loading state management for asynchronous data fetching. Displays loading indicators and handles empty states gracefully. Supports progressive loading and lazy data fetching patterns.

⏳ Simulates API data loading with proper loading states and transitions

Virtual Scrolling for Large Datasets

Efficient rendering of large datasets (10,000+ items) using virtual scrolling techniques. Only renders visible items to maintain smooth performance. Includes intelligent search indexing and result caching for instant response times.

🚀 Virtual scrolling handles massive datasets without performance degradation

Theme System

Adaptive Theme Engine

Flexible theming system with light/dark mode support, customizable color schemes, and responsive design patterns. Themes automatically adapt to system preferences and can be dynamically switched at runtime.

Float Theme (Default)

Modern floating design with subtle shadows, smooth animations, and rounded corners. Optimized for contemporary UI designs with enhanced visual hierarchy and depth perception.

✨ Modern floating design with smooth animations

Basic Theme

Clean, minimal design with sharp edges and immediate visual feedback. Perfect for data-dense applications and professional interfaces where clarity and simplicity are prioritized.

📋 Clean minimal design for professional interfaces

Dark Mode - Float Theme

Dark theme variant with optimized contrast ratios, reduced eye strain colors, and enhanced focus indicators. Automatically adapts to system dark mode preferences.

🌙 Optimized dark theme with proper contrast ratios

Dark Mode - Search Select

Dark theme search component with enhanced search input styling, improved placeholder text visibility, and optimized dropdown contrast for better multilingual text readability.

🔍 Dark search variant with enhanced multilingual text support

Dynamic Theme Switching

Runtime theme switching capabilities allow dynamic adaptation to user preferences or system changes. Themes transition smoothly without layout shifts or visual glitches.

🎨 Real-time theme switching with smooth transitions

Multiple Selection

Advanced Multi-Selection System

Sophisticated multiple selection with tag-based display, batch operations, and intelligent selection management. Supports keyboard shortcuts, bulk actions, and customizable selection limits.

Tag-Based Multiple Selection

Multiple selection with visual tag representation. Each selected item appears as a removable tag with individual deselection capability. Supports drag-and-drop reordering and bulk operations.

🏷️ Visual tag system with individual item removal and batch operations

Multiple Selection with Multilingual Search

Combines the power of multilingual search with multiple selection capabilities. Users can search in their preferred language while building complex selection sets. Includes intelligent duplicate prevention and selection validation.

🌏 Multilingual search combined with tag-based multiple selection

Dark Theme Multiple Selection

Dark theme variant optimized for multiple selection interfaces. Enhanced tag visibility, improved contrast for selected states, and better focus indicators for keyboard navigation in multi-select scenarios.

🌙 Dark theme optimized for multi-selection interfaces

Dynamic Option Management

Real-time Option Manipulation

Advanced dynamic option management system supporting real-time option addition, removal, and updates with instant virtual scroll synchronization. Ideal for applications requiring live data updates, user-generated content, or API-driven option sets.

Batch Option Management

Replace all options at once while optionally preserving current selections. Perfect for loading new datasets from APIs, switching between different option categories, or implementing filtered views with state management.

🔄 Batch option replacement with optional selection preservation

Advanced Features

Essential Features

Provides core functionality such as easy setup, responsive design, and simple customization options. Ideal for building straightforward applications with common requirements.

Form Integration

Complete form integration with validation, error handling, and submission management. Supports HTML5 validation attributes, custom validators, and integration with popular form libraries and frameworks.

Preferred Language (Required):

Technical Interests (Multiple Selection):

📝 Complete form integration with validation and error handling

Framework Integration

Universal Framework Support

SEO Select components work seamlessly across all modern frameworks as Web Components. Each framework requires slight integration differences for optimal TypeScript support and event handling.

React Integration

React integration requires custom event handling and ref management for optimal TypeScript support:

// React Component Example
import React, { useRef, useEffect, useState } from 'react';
import 'seo-select';
import 'seo-select/styles';
import 'seo-select/types';

const MySelectComponent = () => {
    const selectRef = useRef(null);
    const [selectedValue, setSelectedValue] = useState('');

    useEffect(() => {
        const selectElement = selectRef.current;
        if (!selectElement) return;

        const handleSelect = (event) => {
            console.log('Selected:', event.detail);
            setSelectedValue(event.detail.value);
        };

        selectElement.addEventListener('onSelect', handleSelect);

        return () => {
            selectElement.removeEventListener('onSelect', handleSelect);
        };
    }, []);

    return (
        <div>
            <seo-select 
                ref={selectRef}
                name="framework" 
                width="200px"
                theme="float"
            >
                <option value="react">React</option>
                <option value="vue">Vue.js</option>
                <option value="angular">Angular</option>
            </seo-select>
            
            <p>Selected: {selectedValue}</p>
        </div>
    );
};

Vue.js Integration

Vue integration with composition API and reactive data binding:

<template>
  <div>
    <seo-select 
      ref="selectRef"
      name="framework" 
      width="200px"
      @onSelect="handleSelect"
    >
      <option value="vue">Vue.js</option>
      <option value="nuxt">Nuxt.js</option>
      <option value="quasar">Quasar</option>
    </seo-select>
    
    <p>Selected: {{ selectedValue }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import 'seo-select';
import 'seo-select/styles';
import 'seo-select/types';

const selectRef = ref(null);
const selectedValue = ref('');

const handleSelect = (event) => {
  selectedValue.value = event.detail.value;
};
</script>

Angular Integration

Angular integration with custom elements schema and TypeScript decorators:

// Angular Component
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import 'seo-select';
import 'seo-select/styles';
import 'seo-select/types';

@Component({
  selector: 'app-select-demo',
  template: `
    <seo-select 
      name="framework" 
      width="200px"
      (onSelect)="handleSelect($event)"
    >
      <option value="angular">Angular</option>
      <option value="ionic">Ionic</option>
    </seo-select>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class SelectDemoComponent {
  handleSelect(event: any) {
    console.log('Selected:', event.detail);
  }
}

Svelte Integration

Svelte integration with reactive stores and custom event handling:

<script>
  import { onMount } from 'svelte';
  import 'seo-select';
  import 'seo-select/styles';
  import 'seo-select/types';

  let selectElement;
  let selectedValue = '';

  onMount(() => {
    if (selectElement) {
      selectElement.addEventListener('onSelect', handleSelect);
    }
  });

  function handleSelect(event) {
    selectedValue = event.detail.value;
  }
</script>

<seo-select 
  bind:this={selectElement}
  name="framework" 
  width="200px"
>
  <option value="svelte">Svelte</option>
  <option value="sveltekit">SvelteKit</option>
</seo-select>

<p>Selected: {selectedValue}</p>

Next.js Integration

Next.js integration with SSR considerations and dynamic imports:

// Next.js Component with SSR Support
import { useEffect, useState } from 'react';
import dynamic from 'next/dynamic';

const SeoSelectWrapper = dynamic(() => 
  import('../components/SeoSelectWrapper'), {
    ssr: false,
    loading: () => <p>Loading...</p>
  }
);

export default function NextSelectPage() {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
    import('seo-select').then(() => {
      import('seo-select/styles');
      import('seo-select/types');
    });
  }, []);

  if (!mounted) return <div>Loading...</div>;

  return <SeoSelectWrapper />;
}

Vanilla JavaScript

Pure JavaScript integration without framework dependencies:

// Import SEO Select components
import 'seo-select';
import 'seo-select/styles';
import 'seo-select/types';

// Wait for components to be defined
await customElements.whenDefined('seo-select');

// Get element reference
const selectElement = document.querySelector('seo-select');

// Add event listeners
selectElement.addEventListener('onSelect', (event) => {
  console.log('Selected:', event.detail);
});

// Set options programmatically
selectElement.optionItems = [
  { value: 'js', label: 'JavaScript' },
  { value: 'ts', label: 'TypeScript' }
];

Universal Framework Support

🎯 Zero Configuration

🔒 Type Safety

⚡ Future Proof

Installation & Setup

Quick Start

NPM Installation

Basic Import & Usage

HTML Usage Examples

JavaScript API Usage

Event Handling

Basic Select Usage

Overview

Slot Method (Recommended)

Array Method (Fallback)

Keyboard Navigation & Accessibility

Event Handling System

Search Select Components

Multilingual Search Engine

Multilingual Search Capabilities

Asynchronous Loading States

Virtual Scrolling for Large Datasets

Theme System

Adaptive Theme Engine

Float Theme (Default)

Basic Theme

Dark Mode - Float Theme

Dark Mode - Search Select

Dynamic Theme Switching

Multiple Selection

Advanced Multi-Selection System

Tag-Based Multiple Selection

Multiple Selection with Multilingual Search

Dark Theme Multiple Selection

Dynamic Option Management

Real-time Option Manipulation

Batch Option Management

Advanced Features

Essential Features

Form Integration

Framework Integration

Universal Framework Support

React Integration

Vue.js Integration

Angular Integration

Svelte Integration

Next.js Integration

Vanilla JavaScript