NPM Package Guide

Integrate Classy Comments into your JavaScript/TypeScript application

Installation

npm install @classy-comments/core

Don't use npm?

If you don't use build tools, check out our Direct Install (CDN) docs for a simple copy/paste solution that works on any website.

Requirements

  • Node.js 16+ (or modern browser)
  • Framework: React, Vue, Angular, Svelte, or vanilla JS
  • TypeScript 4.5+ (optional, but recommended)

Quick Start

import { ClassyComments } from '@classy-comments/core'
import '@classy-comments/core/styles.css'

const classy = new ClassyComments({
  apiBaseUrl: 'https://api.classycomments.com',
  apiKey: 'cc_live_sk_your_api_key',

  // REQUIRED: Specify which form and field to attach to
  formSelector: '#comment-form',      // CSS selector for the form
  fieldSelector: '#comment-text'      // CSS selector for the textarea
})

await classy.init()

Settings come from your dashboard

When using AI mode, refinement settings (formality, tone, profanity handling, etc.) are fetched from your dashboard configuration. You don't pass them here—they're managed centrally.

Specifying Which Field to Enhance

This is the most important configuration! You must tell Classy Comments which form and field to attach to.

Method 1: CSS Selectors (Recommended)

const classy = new ClassyComments({
  apiKey: 'your_api_key',
  formSelector: '#comment-form',       // Find the form by ID
  fieldSelector: '#comment-text'       // Find the textarea by ID
})

Method 2: Field Name

If your field has a name attribute:

const classy = new ClassyComments({
  apiKey: 'your_api_key',
  formSelector: '.comment-form',
  fieldSelector: 'comment'            // Will find [name="comment"]
})

Examples by Framework

React

import { useEffect } from 'react'
import { ClassyComments } from '@classy-comments/core'
import '@classy-comments/core/styles.css'

function CommentForm() {
  useEffect(() => {
    const classy = new ClassyComments({
      apiBaseUrl: 'https://api.classycomments.com',
      apiKey: process.env.REACT_APP_CLASSY_API_KEY,
      formSelector: '#my-comment-form',
      fieldSelector: '#comment-textarea'
    })

    classy.init()
  }, [])

  return (
    <form id="my-comment-form">
      <textarea
        id="comment-textarea"
        name="comment"
        rows={5}
      />
      <button type="submit">Post Comment</button>
    </form>
  )
}

Vue

<template>
  <form id="comment-form">
    <textarea id="comment-field" v-model="comment" />
    <button type="submit">Submit</button>
  </form>
</template>

<script>
import { ClassyComments } from '@classy-comments/core'
import '@classy-comments/core/styles.css'

export default {
  mounted() {
    const classy = new ClassyComments({
      apiKey: process.env.VUE_APP_CLASSY_API_KEY,
      formSelector: '#comment-form',
      fieldSelector: '#comment-field'
    })

    classy.init()
  }
}
</script>

Vanilla JavaScript

<form id="contact-form">
  <textarea id="message-field" name="message"></textarea>
  <button type="submit">Send</button>
</form>

<script type="module">
  import { ClassyComments } from '@classy-comments/core'
  import '@classy-comments/core/styles.css'

  const classy = new ClassyComments({
    apiKey: 'cc_live_sk_your_key',
    formSelector: '#contact-form',
    fieldSelector: '#message-field'
  })

  await classy.init()
</script>

Configuration Options

Constructor Options

OptionTypeRequiredDescription
apiKeystringYesYour API key from the dashboard
formSelectorstringYesCSS selector for the form
fieldSelectorstringYesCSS selector or name of the textarea
apiBaseUrlstringNoDefault: https://api.classycomments.com
onApprovefunctionNoCallback when comment is approved
validateBeforeInterceptbooleanNoCheck HTML5 validation before showing modal (default: true)
onApprovefunctionNoCallback when comment is approved
onCancelfunctionNoCallback when user cancels

Form Validation Control

By default, Classy Comments respects HTML5 form validation. If a form has validation errors (required fields, invalid email, etc.), the browser will show validation messages BEFORE the modal appears.

validateBeforeIntercept: true (default)

HTML5 validation runs first. If the form is invalid, browser shows validation errors and the modal won't appear. This is the recommended approach for most use cases.

validateBeforeIntercept: false

Modal appears immediately without checking HTML5 validation first. Use this if you want users to refine their comment before validating other fields.

const classy = new ClassyComments({
  apiKey: 'your_key',
  formSelector: '#contact-form',
  fieldSelector: '#message',
  validateBeforeIntercept: false  // Skip HTML5 validation
})

Manual Mode

Don't want automatic form interception? Use manual mode to trigger refinement programmatically:

const classy = new ClassyComments({
  apiKey: 'your_api_key'
  // No formSelector or fieldSelector needed!
})

await classy.init()

// Trigger manually whenever you want
const commentText = 'THIS IS AWESOME!!!'
await classy.processCommentManual(commentText, {
  onApprove: (refinedText) => {
    console.log('Approved:', refinedText)
    // Do something with the refined text
    submitToBackend(refinedText)
  },
  onCancel: () => {
    console.log('User cancelled')
  }
})

Use Cases for Manual Mode

  • Custom UI/UX flows
  • Chat applications
  • Rich text editors (CKEditor, TinyMCE, etc.)
  • Non-standard form implementations
  • Mobile apps (React Native, Ionic)

Where Do Refinement Settings Come From?

Dashboard Configuration (Recommended)

Configure formality, tone, profanity handling, and all other settings in your dashboard. The npm package automatically fetches these settings when you call init().

Benefits of dashboard configuration:

  • Change settings without redeploying your app
  • Same settings across all your tools (WordPress, extension, npm)
  • Test different configs easily
  • A/B test refinement strategies

TypeScript Support

Full TypeScript support with type definitions included:

import { ClassyComments, ClassyCommentsOptions } from '@classy-comments/core'

const options: ClassyCommentsOptions = {
  apiKey: 'cc_live_sk_your_key',
  apiBaseUrl: 'https://api.classycomments.com',
  formSelector: '#comment-form',
  fieldSelector: '#comment-field',
  onApprove: (approvedText: string) => {
    console.log(approvedText)
  }
}

const classy = new ClassyComments(options)
await classy.init()

Customizing Styles

The modal uses CSS variables that you can override:

:root {
  --classy-primary-color: #9333ea;      /* Purple */
  --classy-accent-color: #f59e0b;       /* Gold */
  --classy-gold-light: #fbbf24;
  --classy-purple-dark: #7c3aed;
  /* ... and more */
}

/* Override modal background */
.classy-comments-overlay {
  backdrop-filter: blur(12px) !important;
}

/* Customize buttons */
.classy-btn-primary {
  background: your-gradient !important;
}

Troubleshooting

Modal not appearing

  • Verify formSelector and fieldSelector are correct
  • Check browser console for errors
  • Ensure CSS is imported: import '@classy-comments/core/styles.css'
  • Verify init() completed successfully

Can't find the field

  • Try using document.querySelector('your-selector') in console to test
  • Make sure the element exists in the DOM when init() is called
  • For SPAs, wait for component mount before calling init()

API errors

  • Check API key is correct
  • Verify you haven't exceeded quota
  • Check Network tab for API response details

Complete Example

Find a complete working example in our GitHub repository:

React Demo

Full React app with Classy Comments integration

Need Help?

For npm package support: