@myquizbot/react

A React component library for embedding interactive quizzes with API integration and event handling.

Installation

npm install @myquizbot/react

Usage

import { Quiz } from '@myquizbot/react';
import '@myquizbot/react/dist/style.css';

function App() {
  return (
    <Quiz
      quizId="procrastinacao"
      apiKey="pk_live"
      mode="steps"
      onStart={(e) => {
        console.log('Quiz started:', e);
      }}
      onAnswer={(e) => {
        console.log('Question answered:', e);
      }}
      onProgress={(e) => {
        console.log('Progress:', e.percentage + '%');
      }}
      onComplete={(e) => {
        console.log('Quiz completed:', e);
      }}
      onError={(e) => {
        console.error('Error:', e.message);
      }}
    />
  );
}

Props

Required Props

| Prop | Type | Description | |------|------|-------------| | quizId | string | Unique identifier for the quiz to load | | apiKey | string | API key for authentication |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | mode | 'steps' \| 'single' \| 'flow' | 'steps' | Render mode for the quiz | | baseUrl | string | http://localhost:5003 | Base URL for API calls | | className | string | - | Custom CSS class name | | style | React.CSSProperties | - | Custom inline styles |

Event Handlers

| Handler | Type | Description | |---------|------|-------------| | onStart | (event: QuizStartEvent) => void | Called when the quiz starts | | onAnswer | (event: QuizAnswerEvent) => void | Called when a question is answered | | onProgress | (event: QuizProgressEvent) => void | Called when progress is made | | onComplete | (event: QuizCompleteEvent) => void | Called when the quiz is completed | | onError | (event: QuizErrorEvent) => void | Called when an error occurs |

Event Types

QuizStartEvent

interface QuizStartEvent {
  quizId: string;
  timestamp: number;
}

QuizAnswerEvent

interface QuizAnswerEvent {
  questionId: string;
  answer: any;
  timestamp: number;
}

QuizProgressEvent

interface QuizProgressEvent {
  currentStep: number;
  totalSteps: number;
  percentage: number;
}

QuizCompleteEvent

interface QuizCompleteEvent {
  quizId: string;
  answers: Record<string, any>;
  timestamp: number;
  sessionId?: string;
}

QuizErrorEvent

interface QuizErrorEvent {
  error: Error;
  message: string;
  timestamp: number;
}

Modes

Steps Mode (default)

Displays questions one at a time with a progress bar and navigation.

<Quiz quizId="my-quiz" apiKey="pk_live" mode="steps" />

Single Mode

(Coming soon) Displays all questions on a single page.

Flow Mode

(Coming soon) Displays questions in a visual flow diagram.

Customization

You can customize the appearance using CSS:

/* Override default styles */
.quiz-container {
  max-width: 1000px;
}

.quiz-steps-option {
  background: #your-color;
}

Or pass custom styles via props:

<Quiz
  quizId="my-quiz"
  apiKey="pk_live"
  className="my-custom-quiz"
  style={{ maxWidth: '600px' }}
/>

API Configuration

The component connects to your MyQuizBot backend API. Configure the base URL:

<Quiz
  quizId="my-quiz"
  apiKey="pk_live"
  baseUrl="http://localhost:8080"
/>

Or set it via environment variable:

VITE_API_BASE_URL=http://localhost:8080

Current Backend Integration

The library currently uses the following backend endpoints:

• GET /core/quiz - Fetches all quizzes (requires authentication)

The component filters the quiz list client-side to find the requested quizId.

Session Management

Note: Quiz sessions are currently managed client-side using localStorage. This means:

• Session data is stored in the browser
• Answers are tracked locally
• No server-side session persistence yet

Recommended Backend Improvements:

For production use, consider adding these endpoints to your backend:

GET  /core/quiz/:id              - Fetch specific quiz by ID
POST /core/quiz/session          - Create new quiz session
POST /core/quiz/session/:id/answer - Submit answer
POST /core/quiz/session/:id/complete - Complete session

This will enable:

• Server-side session tracking
• Answer persistence
• Analytics and reporting
• Multi-device session continuity

TypeScript Support

The library is written in TypeScript and includes full type definitions. Import types as needed:

import { Quiz, QuizProps, QuizCompleteEvent } from '@myquizbot/react';

License

MIT