react-wp-post

A powerful, headless React component library designed to connect seamlessly with the WordPress REST API and WooCommerce REST API. It includes ready-to-use hooks and Tailwind CSS-powered components for rapidly building WordPress frontends in React.

Features

• Built-in Data Fetching: Provides data hooks like useWpPosts, useWpPost, useWcProducts, etc.
• Headless WordPress & WooCommerce: Read articles, loop product grids, list categories, post threaded comments, and natively render author biographies.
• Tailwind CSS Ready: Extremely customizable layouts using embedded Tailwind CSS utility classes.
• Flexible Layouts: Effortlessly switch your post loops through grid, list, compact, and full layouts out of the box.
• Context API Context: Centrally configure your remote WordPress URL and API keys without prop drilling.

Installation

Install the package via npm:

npm install react-wp-post

Tailwind CSS Configuration

Because this library ships with raw Tailwind CSS class names inside its components, your project's tailwind.config.js must scan the package to dynamically build the corresponding styles.

Add react-wp-post to your content array inside tailwind.config.js:

export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    // Add this line to scan the library for CSS classes
    "./node_modules/react-wp-post/**/*.js"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Quick Start

1. Setup the WordPress Provider

Wrap your React application (or specific route) with the <WpProvider> to configure the remote endpoint.

Alternatively, you can skip passing siteUrl as a prop if you define it in your .env file! We automatically detect:

• VITE_WP_SITE_URL (Vite)
• NEXT_PUBLIC_WP_SITE_URL (Next.js)
• REACT_APP_WP_SITE_URL (Create-React-App)

import { WpProvider } from 'react-wp-post';

function App() {
  return (
    <WpProvider 
      // If VITE_WP_SITE_URL is in .env, you can omit the siteUrl prop perfectly!
      siteUrl="https://your-wordpress-site.com"
      
      // Optional: Add WooCommerce keys if you plan to use WcProduct components
      // Also automatically detected via VITE_WC_CONSUMER_KEY & VITE_WC_CONSUMER_SECRET
      wcConsumerKey="ck_your_woo_key"
      wcConsumerSecret="cs_your_woo_secret"
    >
      <MyBlogPage />
    </WpProvider>
  );
}

export default App;

2. Basic Example: Listing Posts

You can quickly fetch and render a list of WordPress posts using the <WpPostList /> component. Switch between layouts effortlessly using the layout prop!

import { WpPostList } from 'react-wp-post';

function MyBlogPage() {
  return (
    <div className="container mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">Latest News</h1>
      
      {/* 
        The layout prop transforms the card design.
        Options: "grid" | "list" | "compact"
      */}
      <WpPostList 
        layout="grid" 
        params={{ per_page: 6, _embed: true }} 
      />
    </div>
  );
}

3. Basic Example: Individual Post details

Fetch and render a specific individual WordPress post, complete with content structure, authors, timestamps, categories, and tags.

import { WpPost, WpComments, WpShare } from 'react-wp-post';

function SinglePostView({ postId }) {
  return (
    <div className="max-w-4xl mx-auto p-4">
      <WpPost id={postId} layout="full" />
      
      {/* Easily drop in social sharing elements */}
      <WpShare 
        url="https://your-frontend-url.com/post/current" 
        title="Check out this post" 
      />

      <hr className="my-10" />

      {/* Integrate the threaded commenting system easily */}
      <WpComments postId={postId} />
    </div>
  );
}

4. Basic Example: WooCommerce

If you configured your provider with WooCommerce keys, fetch and map eCommerce widgets directly.

import { WcProductList } from 'react-wp-post';

function StoreFront() {
  return (
    <div className="store">
      <h2 className="text-2xl font-bold">Featured Products</h2>
      <WcProductList grid mixBlend />
    </div>
  );
}

Available Components

• Hooks: useWpPosts, useWpPost, useWpCategories, useWpPage, useWpMedia, useWpComments, usePostComment, useWpTags, useWpAuthor, useWcProducts, useWcProduct, useWcProductCategories.
• WordPress Core: <WpPost />, <WpPostList />, <WpPage />, <WpCategory />, <WpMedia />
• WooCommerce: <WcProduct />, <WcProductList />, <WcProductCategory />
• User Engagement: <WpComments />, <WpShare />, <WpAuthor />, <WpTags />

Component Props Reference

<WpPost /> & <WpPostList />

| Prop | Type | Default | Description | |------|------|---------|-------------| | layout | 'grid' \| 'list' \| 'compact' \| 'full' | 'full' | The visual layout of the post. | | LinkComponent | React.ElementType | undefined | Custom link component (e.g. Link from react-router-dom). | | baseUrl | string | '/blog' | Prefix for the post detail links. | | imageClassName | string | '' | Custom classes for the img tag. | | imageContainerClassName | string | '' | Custom classes for the image wrapper/link. | | itemClassName | string | '' | Custom classes for each individual post item card. | | showExcerpt | boolean | false | Show the post excerpt. | | showContent | boolean | true | Show the full content. | | showAuthor | boolean | true | Show author info. | | showDate | boolean | true | Show post date. | | showCategories | boolean | true | Show category labels. | | showTags | boolean | true | Show tag labels (full layout only). |

<WcProduct /> & <WcProductList />

| Prop | Type | Default | Description | |------|------|---------|-------------| | imageClassName | string | '' | Custom classes for the product img tag. | | imageContainerClassName | string | '' | Custom classes for the image wrapper. | | itemClassName | string | '' | Custom classes for each product card in a list. | | grid | boolean | true | (WcProductList only) Whether to show in a grid. | | showPrice | boolean | true | Show product price. | | showRating | boolean | true | Show average rating. | | showDescription | boolean | true | Show short description. |