@clutch-wp/react

React hooks and context provider for the Clutch WordPress SDK.

Installation

npm install @clutch-wp/react
# or
yarn add @clutch-wp/react
# or
bun add @clutch-wp/react

Usage

1. Setup the Provider

Wrap your app with the WordPressProvider to provide the WordPress client context:

import { WordPressProvider } from '@clutch-wp/react';

const config = {
  apiUrl: 'https://your-wordpress-site.com',
  authToken: 'your-auth-token', // Optional
  cacheDisabled: false, // Optional
  draftMode: false, // Optional
};

function App() {
  return (
    <WordPressProvider config={config}>
      <YourAppComponents />
    </WordPressProvider>
  );
}

2. Use the Hooks

Basic Hooks

import {
  useWordPress,
  useWordPressClient,
  useIsConnected,
} from '@clutch-wp/react';

function MyComponent() {
  const { client, isConnected, wpUrl } = useWordPress();
  const client = useWordPressClient(); // Direct client access
  const isConnected = useIsConnected(); // Connection status only

  return (
    <div>
      <p>Connected to: {wpUrl}</p>
      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
    </div>
  );
}

Data Fetching Hooks

import {
  usePosts,
  usePost,
  useUsers,
  useUser,
  useTaxonomyTerms,
  useTaxonomyTerm,
  useSearch,
  useMenu,
} from '@clutch-wp/react';

function BlogPosts() {
  const {
    data: posts,
    loading,
    error,
    refetch,
  } = usePosts({
    post_type: 'post',
    per_page: 10,
    page: 1,
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {posts?.posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <div dangerouslySetInnerHTML={{ __html: post.excerpt }} />
        </article>
      ))}
    </div>
  );
}

function SinglePost({ slug }: { slug: string }) {
  const { data: post, loading, error } = usePost('post', slug, true);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!post) return <div>Post not found</div>;

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

function CategoryList() {
  const {
    data: terms,
    loading,
    error,
  } = useTaxonomyTerms({
    taxonomy: 'category',
    per_page: 20,
  });

  if (loading) return <div>Loading categories...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {terms?.terms.map(term => (
        <li key={term.id}>
          <a href={term.link}>{term.name}</a>
          {term.description && <p>{term.description}</p>}
        </li>
      ))}
    </ul>
  );
}

function SearchResults({ query }: { query: string }) {
  const {
    data: results,
    loading,
    error,
  } = useSearch({
    search: query,
    per_page: 10,
  });

  if (loading) return <div>Searching...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>Search Results for "{query}"</h2>
      {results.map(result => (
        <div key={result.id}>
          <h3>{result.title}</h3>
          <p>{result.excerpt}</p>
        </div>
      ))}
    </div>
  );
}

Available Hooks

• useWordPressClient() - Direct access to the WordPress HTTP client
• useIsConnected() - Check WordPress connection status
• usePosts(args) - Fetch multiple posts with pagination
• usePost(postType, slug, includeSeo) - Fetch a single post by slug
• useUsers(args) - Fetch multiple users
• useUser(identifier, type) - Fetch a single user by slug or ID
• useTaxonomyTerms(args) - Fetch taxonomy terms
• useTaxonomyTerm(taxonomy, identifier, type, includeSeo) - Fetch a single term
• useSearch(args) - Search WordPress content
• useMenu(id) - Fetch a WordPress menu
• useDraftMode() - Check if WordPress is in draft mode

All data fetching hooks return an object with:

• data - The fetched data
• loading - Loading state boolean
• error - Error object if request failed
• refetch - Function to manually refetch the data

TypeScript Support

The package includes full TypeScript support with proper type definitions for all hooks and components.

Error Handling

All hooks include built-in error handling. The useWordPress hook will throw an error if used outside of a WordPressProvider.

import { useWordPress } from '@clutch-wp/react';

function MyComponent() {
  try {
    const { client } = useWordPress();
    // Component logic
  } catch (error) {
    // Handle the case where component is not wrapped in provider
    return <div>WordPress provider not found</div>;
  }
}