How to Add an FAQ Widget to Any Website in 5 Minutes

Add a FAQ Section to Your Website Without Building One from Scratch

Every website needs a FAQ section. It reduces support requests, improves SEO with structured content, and helps users find answers without leaving your site.

But building a FAQ system from scratch — with a database, admin panel, API, and frontend components — takes days of development time. And maintaining it takes even more.

With thefaq.app, you can have a working FAQ widget on your website in under 5 minutes. Here is exactly how to do it.

What You Will Build

By the end of this tutorial, you will have:

• A FAQ widget embedded on your website that loads your FAQ content dynamically
• A dashboard where you can add, edit, and organize your FAQs without touching code
• An API-backed system that you can extend later with the thefaq.app SDK

The widget works on any website: static HTML, WordPress, Webflow, Shopify, React, Next.js, Vue — anything that can load a script tag or npm package.

Step 1: Create Your Account (1 minute)

Go to app.thefaq.app and sign up. The free plan gives you:

• 50 FAQs
• 1,000 API requests per month
• 1 API key
• Widget embedding

No credit card required.

Once signed up, you will have an organization with a slug (e.g., my-company). This slug is your identifier for the API and widget.

Step 2: Add Your FAQ Content (2 minutes)

From the dashboard, navigate to your organization and start adding FAQs. Each FAQ has:

• Question — The question your users ask
• Answer — The answer, supporting markdown formatting
• Collection (optional) — Group related FAQs together (e.g., "Billing", "Getting Started")

Add at least 5-10 FAQs to start. If you already have FAQ content elsewhere, you can use the API to bulk-import:

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I reset my password?",
    "answer": "Go to **Settings > Security** and click **Reset Password**. You will receive an email with a reset link."
  }' \
  https://app.thefaq.app/api/v1/your-org/faqs

Pro tip: On the Pro plan, you can use AI-powered generation to create FAQs from your existing documentation or product descriptions.

Step 3: Embed the Widget (2 minutes)

Now the part you are here for. Choose your integration method:

Option A: Script Tag (Any Website)

This works on any website — HTML, WordPress, Webflow, Shopify, Squarespace, or any platform that lets you add custom HTML.

<!-- Add this where you want the FAQ widget to appear -->
<div id="faq-widget"></div>

<!-- Add this before </body> -->
<script src="https://widget.thefaq.app/embed.js"
  data-org="your-org-slug"
  data-theme="light"
  data-target="#faq-widget">
</script>

That is it. The widget will:

• Fetch your FAQ content from the API
• Render an interactive accordion with search
• Match your data-theme setting (light or dark)
• Load asynchronously without blocking your page

Option B: React / Next.js

If you are using React or Next.js, install the SDK for a tighter integration:

npm install @faqapp/core
# or for Next.js specifically:
npm install @faqapp/nextjs

Then use it in your component:

// Next.js example
import { FAQList } from '@faqapp/nextjs'

export default function FAQPage() {
  return (
    <main>
      <h1>Frequently Asked Questions</h1>
      <FAQList organizationSlug="your-org-slug" />
    </main>
  )
}

Or with the core SDK for more control:

'use client'

import { TheFAQApp } from '@faqapp/core'
import { useEffect, useState } from 'react'

const faq = new TheFAQApp({
  apiKey: process.env.NEXT_PUBLIC_FAQ_API_KEY!,
  organizationSlug: 'your-org'
})

export function FAQSection() {
  const [faqs, setFaqs] = useState([])

  useEffect(() => {
    faq.faqs.list().then(setFaqs)
  }, [])

  return (
    <div>
      {faqs.map((item) => (
        <details key={item.id}>
          <summary>{item.question}</summary>
          <p>{item.answer}</p>
        </details>
      ))}
    </div>
  )
}

Option C: Vue / Svelte / Other Frameworks

Use the core SDK with your framework's reactivity system:

npm install @faqapp/core

<!-- Vue 3 example -->
<script setup>
import { TheFAQApp } from '@faqapp/core'
import { ref, onMounted } from 'vue'

const faq = new TheFAQApp({
  apiKey: import.meta.env.VITE_FAQ_API_KEY,
  organizationSlug: 'your-org'
})

const faqs = ref([])

onMounted(async () => {
  faqs.value = await faq.faqs.list()
})
</script>

<template>
  <details v-for="item in faqs" :key="item.id">
    <summary>{{ item.question }}</summary>
    <p>{{ item.answer }}</p>
  </details>
</template>

Option D: WordPress

For WordPress sites, add the script tag widget using one of these methods:

1. Theme editor: Add the script to your theme's footer.php before </body>
2. Custom HTML block: In the Gutenberg editor, add a Custom HTML block where you want the FAQ
3. Plugin: Use a "Header/Footer Scripts" plugin to add the embed code site-wide

<!-- WordPress Custom HTML block -->
<div id="faq-widget" style="max-width: 800px; margin: 0 auto;"></div>
<script src="https://widget.thefaq.app/embed.js"
  data-org="your-org-slug"
  data-theme="light"
  data-target="#faq-widget">
</script>

For a more detailed WordPress guide, see our WordPress FAQ plugin alternatives post.

Step 4: Customize the Appearance

Widget Configuration Options

The script tag widget supports these attributes:

Attribute	Values	Default	Description
data-org	Your org slug	Required	Your thefaq.app organization
data-theme	light, dark, auto	light	Color theme
data-target	CSS selector	#faq-widget	Where to render
data-collection	Collection slug	All	Show specific collection
data-search	true, false	true	Show search bar
data-limit	Number	20	Max FAQs to display

Example: Dark Theme, Specific Collection

<script src="https://widget.thefaq.app/embed.js"
  data-org="your-org-slug"
  data-theme="dark"
  data-collection="billing"
  data-search="true"
  data-target="#billing-faq">
</script>

Step 5: Add FAQ Schema Markup (Bonus SEO)

FAQ schema markup tells Google to display your questions and answers directly in search results as rich snippets. This can significantly increase click-through rates.

thefaq.app can generate the JSON-LD schema markup for you via the API:

curl -H "Authorization: Bearer your-api-key" \
  "https://app.thefaq.app/api/v1/your-org/faqs?format=jsonld"

Or add it manually using the data from the API:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How do I reset my password?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Go to Settings > Security and click Reset Password."
      }
    }
  ]
}
</script>

For a complete guide on FAQ schema markup, see our FAQ Schema Markup Guide.

What You Can Do Next

Now that your FAQ widget is live, here are ways to extend it:

Use the API for Dynamic Content

Fetch FAQs based on context — show billing FAQs on the pricing page, getting-started FAQs during onboarding:

// Show contextual FAQs based on the current page
const billingFaqs = await faq.faqs.list({ collection: 'billing' })
const setupFaqs = await faq.faqs.list({ collection: 'getting-started' })

Add Search

Let users search across all your FAQ content:

const results = await faq.faqs.search('cancel subscription')

Track What Users Ask

Use the thefaq.app dashboard analytics to see which FAQs get the most views, which searches return no results, and where you have content gaps.

Set Up a Public FAQ Page

Every organization gets a hosted FAQ page at yourorg.thefaq.app. On the Pro plan, map it to a custom domain like faq.yourdomain.com.

Learn more about public FAQ pages.

Common Questions About FAQ Widgets

Does the widget slow down my website?

No. The widget script loads asynchronously and does not block page rendering. It is lightweight (under 15KB gzipped) and fetches FAQ content after the page loads.

Can I style the widget to match my brand?

Yes. The widget inherits your page's font family by default. You can override styles with CSS using the widget's class selectors. For full custom rendering, use the SDK to fetch data and build your own UI.

How many FAQs can I display?

The free plan supports up to 50 FAQs. Starter supports 500. Pro is unlimited. The widget respects the data-limit attribute to control how many display on a single page.

Does it work with single-page applications?

Yes. The script tag widget works with SPAs. For React/Next.js/Vue apps, the SDK integration is recommended for tighter lifecycle management.

Is the widget accessible?

The widget uses semantic HTML (details/summary elements), supports keyboard navigation, and includes proper ARIA attributes.

Get Started

1. Sign up for free (no credit card)
2. Add your FAQ content in the dashboard
3. Copy the embed code to your website
4. Done

Your FAQ widget is now live, backed by an API you can extend at any time.

---

Want to go deeper? Read our complete widget integration guide or learn how to build a FAQ page with the API.