Widget Integration

Quick Install

Install the TheFAQApp SDK to embed a fully functional FAQ widget in your website.

npm install @faq/sdk

yarn add @faq/sdk

pnpm add @faq/sdk

bun add @faq/sdk

Basic Usage

import { createFaqClient } from '@faq/sdk';

const client = createFaqClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: 'your-org',
});

// Fetch all published FAQs
const { data } = await client.getFaq();

Render in HTML

<div id="faq-widget"></div>

<script type="module">
  import { createFaqClient } from 'https://unpkg.com/@faq/sdk';

  const client = createFaqClient({
    apiKey: 'faq_your-public-read-key',
    organizationSlug: 'your-org',
  });

  const { data } = await client.getFaq();
  const container = document.getElementById('faq-widget');

  data.forEach((item) => {
    const details = document.createElement('details');
    details.innerHTML = `
      <summary>${item.question}</summary>
      <div>${item.answer}</div>
    `;
    container.appendChild(details);
  });
</script>

Next.js Integration

For Next.js applications, use the dedicated @faq/nextjs package which provides React components and server-side data fetching.

npm install @faq/nextjs

Server Component (Recommended)

import { FaqWidget } from '@faq/nextjs';

export default function FaqPage() {
  return (
    <FaqWidget
      apiKey={process.env.FAQ_API_KEY!}
      organizationSlug="your-org"
    />
  );
}

With Categories

import { FaqWidget } from '@faq/nextjs';

export default function FaqPage() {
  return (
    <FaqWidget
      apiKey={process.env.FAQ_API_KEY!}
      organizationSlug="your-org"
      showCategories
      defaultCategory="getting-started"
    />
  );
}

Client-Side with Search

'use client';

import { FaqSearch } from '@faq/nextjs';

export default function SearchableFaq() {
  return (
    <FaqSearch
      apiKey={process.env.NEXT_PUBLIC_FAQ_API_KEY!}
      organizationSlug="your-org"
      placeholder="Search FAQs..."
    />
  );
}

See TypeScript SDK and Next.js SDK for the full API reference.

Configuration

The SDK client accepts these configuration options:

Option	Type	Required	Description
`apiKey`	string	Yes	Your API key (use `read` scope)
`organizationSlug`	string	Yes	Your organization slug
`baseUrl`	string	No	API base URL (default: `https://app.thefaq.app`)
`timeout`	number	No	Request timeout in ms (default: 10000)

const client = createFaqClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: 'your-org',
  baseUrl: 'https://app.thefaq.app',
  timeout: 5000,
});

Customization

Theme Colors

The @faq/nextjs components accept theme customization:

<FaqWidget
  apiKey={process.env.FAQ_API_KEY!}
  organizationSlug="your-org"
  theme={{
    primaryColor: '#0066cc',
    backgroundColor: '#ffffff',
    textColor: '#1a1a1a',
    borderRadius: '8px',
    fontFamily: 'Inter, sans-serif',
  }}
/>

Custom CSS

Override default styles with CSS custom properties:

.faq-widget {
  --faq-primary: #0066cc;
  --faq-bg: #ffffff;
  --faq-text: #1a1a1a;
  --faq-border: #e5e7eb;
  --faq-radius: 8px;
  --faq-font: 'Inter', sans-serif;
}

Custom Rendering

For full control, fetch data with the SDK and render your own UI:

import { createFaqClient } from '@faq/sdk';

const client = createFaqClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: 'your-org',
});

// Fetch questions by category
const { data: questions } = await client.getQuestions({
  category: 'getting-started',
  status: 'published',
});

// Render with your own components
questions.forEach((q) => {
  console.log(q.question, q.answer);
});

Widget Integration

On this page