🌌 Cosmic Quiz Component

A revolutionary circular quiz interface with cosmic animations, particle effects, and sound feedback. The first quiz component where options orbit around questions in a mesmerizing cosmic dance.

✨ Features

• 🌀 Circular Orbital Interface: Answer options orbit around questions in a continuous rotation
• 🎆 Particle Effects: Exploding particles celebrate correct answers
• 🎵 Cosmic Sound Feedback: Web Audio API generates unique tones for interactions
• 🌟 Animated Starfield: Dynamic cosmic background with drifting nebulae
• 📊 Visual Progress: Circular progress indicator and glowing score orb
• 📱 Fully Responsive: Scales perfectly from desktop to mobile
• 🎨 Customizable Themes: Multiple built-in themes + custom styling support
• 🚀 Framework Agnostic: Works with React, Vue, Angular, or vanilla JavaScript
• ♿ Accessible: Keyboard navigation and screen reader support
• 🌍 i18n Ready: Built-in localization support

🚀 Installation

npm install cosmic-quiz-component

or

yarn add cosmic-quiz-component

📖 Quick Start

Vanilla JavaScript

import CosmicQuiz from 'cosmic-quiz-component';
import 'cosmic-quiz-component/dist/cosmic-quiz.css';

const questions = [
  {
    question: "What is the answer to life, universe, and everything?",
    options: ["42", "Love", "Pizza", "Cosmic Energy"],
    correctAnswer: 0
  },
  // ... more questions
];

const quiz = new CosmicQuiz('#quiz-container', {
  questions: questions,
  onComplete: (result) => {
    console.log(`Score: ${result.score}/${result.total}`);
  },
  onAnswer: (answer) => {
    console.log(`Question ${answer.questionIndex}: ${answer.isCorrect ? 'Correct!' : 'Wrong'}`);
  }
});

React/Preact

import { CosmicQuizReact } from 'cosmic-quiz-component';
import 'cosmic-quiz-component/dist/cosmic-quiz.css';

function App() {
  const questions = [
    {
      question: "What is the answer to life, universe, and everything?",
      options: ["42", "Love", "Pizza", "Cosmic Energy"],
      correctAnswer: 0
    },
    // ... more questions
  ];

  const handleComplete = (result) => {
    console.log(`Quiz completed! Score: ${result.score}/${result.total}`);
  };

  return (
    <CosmicQuizReact
      questions={questions}
      onComplete={handleComplete}
      soundEnabled={true}
      particleEnabled={true}
      theme="cosmic"
    />
  );
}

Vue 3

<template>
  <div ref="quizContainer" style="width: 100%; height: 100vh;"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import CosmicQuiz from 'cosmic-quiz-component';
import 'cosmic-quiz-component/dist/cosmic-quiz.css';

const quizContainer = ref(null);
let quizInstance = null;

const questions = [
  {
    question: "What is the answer to life, universe, and everything?",
    options: ["42", "Love", "Pizza", "Cosmic Energy"],
    correctAnswer: 0
  }
];

onMounted(() => {
  quizInstance = new CosmicQuiz(quizContainer.value, {
    questions,
    onComplete: (result) => {
      console.log(`Score: ${result.score}`);
    }
  });
});

onUnmounted(() => {
  if (quizInstance) {
    quizInstance.destroy();
  }
});
</script>

🎨 Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | questions | Array | [] | Array of question objects | | onComplete | Function | () => {} | Callback when quiz completes | | onAnswer | Function | () => {} | Callback for each answer | | soundEnabled | Boolean | true | Enable/disable sound effects | | particleEnabled | Boolean | true | Enable/disable particle effects | | rotationSpeed | Number | 0.5 | Speed of orbital rotation (degrees per frame) | | theme | String | 'cosmic' | Theme: 'cosmic', 'minimal', 'neon', or 'custom' | | locale | String | 'en' | Language locale for UI text | | showProgress | Boolean | true | Show progress indicator | | showScore | Boolean | true | Show score counter | | autoAdvance | Boolean | true | Auto-advance to next question | | advanceDelay | Number | 1500 | Delay before advancing (ms) |

🎭 Themes

Built-in Themes

// Cosmic theme (default)
new CosmicQuiz('#container', {
  theme: 'cosmic',
  questions: [...]
});

// Minimal theme
new CosmicQuiz('#container', {
  theme: 'minimal',
  questions: [...]
});

// Neon theme
new CosmicQuiz('#container', {
  theme: 'neon',
  questions: [...]
});

Custom Theme

new CosmicQuiz('#container', {
  theme: 'custom',
  customStyles: `
    .cosmic-quiz-container {
      background: linear-gradient(45deg, #ff006e, #8338ec);
    }
    .cq-option-orb {
      background: rgba(255, 255, 255, 0.1);
      border-color: #fff;
    }
  `,
  questions: [...]
});

🌍 Internationalization

new CosmicQuiz('#container', {
  locale: 'es',
  questions: [...],
  // Custom translations
  translations: {
    complete: 'Viaje Completo!',
    score: 'Puntuación',
    restart: 'Comenzar de Nuevo'
  }
});

📱 Mobile Optimization

The component automatically adapts to mobile devices with:

• Touch-friendly orbital controls
• Optimized particle count for performance
• Responsive text sizing
• Reduced rotation speed on small screens

♿ Accessibility

• Full keyboard navigation (Tab, Enter, Arrow keys)
• ARIA labels and roles
• Screen reader announcements
• Respects prefers-reduced-motion
• High contrast mode support

🎮 Advanced Usage

Custom Particle Effects

const quiz = new CosmicQuiz('#container', {
  questions: [...],
  particleEnabled: true,
  particleConfig: {
    correctCount: 50,
    incorrectCount: 20,
    colors: {
      correct: ['#00ff00', '#00cc00', '#00aa00'],
      incorrect: ['#ff0000', '#cc0000', '#aa0000']
    },
    gravity: 0.2,
    spread: 360
  }
});

Custom Sound Configuration

const quiz = new CosmicQuiz('#container', {
  questions: [...],
  soundEnabled: true,
  soundConfig: {
    correct: { frequency: 523.25, duration: 0.4, type: 'sine' },
    incorrect: { frequency: 261.63, duration: 0.2, type: 'square' },
    complete: { frequency: 440, duration: 1, type: 'triangle' }
  }
});

Save/Load Progress

// Save progress
const progress = quiz.getProgress();
localStorage.setItem('quizProgress', JSON.stringify(progress));

// Load progress
const savedProgress = JSON.parse(localStorage.getItem('quizProgress'));
quiz.loadProgress(savedProgress);

🛠️ API Reference

Methods

• reset() - Reset quiz to beginning
• destroy() - Clean up and remove quiz
• getProgress() - Get current progress state
• loadProgress(state) - Load saved progress
• setTheme(theme) - Change theme dynamically
• toggleSound() - Toggle sound effects
• toggleParticles() - Toggle particle effects

Events

quiz.on('answer', (data) => {
  console.log('Answer selected:', data);
});

quiz.on('complete', (result) => {
  console.log('Quiz completed:', result);
});

quiz.on('progress', (progress) => {
  console.log('Progress update:', progress);
});

🎯 Examples

Check out the examples directory for:

• Basic vanilla JS implementation
• React integration
• Vue 3 integration
• Angular integration
• Custom themes showcase
• Multiplayer quiz demo
• Educational quiz with explanations

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🙏 Credits

Created with cosmic love by the Maranasati Project team.

Inspired by Buddhist cosmology and the orbital dance of celestial bodies.

Demo | Documentation | Report Issues