@meaple-com/react-query

React Query (TanStack Query) hooks for the Meaple ticketing platform. Fetch and mutate Meaple data in React with caching, loading and error states.

Installation

npm install @meaple-com/react-query @meaple-com/core @meaple-com/types
# or
pnpm add @meaple-com/react-query @meaple-com/core @meaple-com/types
# or
bun add @meaple-com/react-query @meaple-com/core @meaple-com/types

Peer dependencies:

• react ^19.0.0
• @tanstack/react-query ^5.90.7
• axios ^1.12.2
• date-fns ^4.0.0

Install them if not already in your project.

Setup

Wrap your app with QueryClientProvider (from TanStack Query) and MeapleSDKProvider:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { MeapleSDKProvider } from '@meaple-com/react-query';
import { MeapleSDK } from '@meaple-com/core';

const queryClient = new QueryClient();
const sdk = new MeapleSDK({
  publicKey: 'YOUR_CHANNEL_ID',
  baseURL: 'https://api.meaple.com',
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MeapleSDKProvider sdk={sdk}>
        {/* Your app */}
      </MeapleSDKProvider>
    </QueryClientProvider>
  );
}

Optional: set the user token when they log in:

sdk.setGlobalToken('user-jwt-token');

Hooks

All hooks use the SDK from MeapleSDKProvider and return standard TanStack Query results (data, isPending, error, refetch, etc.). You can pass the same options as useQuery / useMutation (e.g. enabled, staleTime).

Events

• useEvents(params?, options?) – List events
• useEvent(eventId, slug, options?) – Single event
• useEventTickets(eventId, slug, options?) – Event tickets
• useEventProducts(eventId, slug, options?) – Event products

Categories

• useCategories(options?) – List categories

Coupon

• useCheckCoupon() – Mutation to validate a coupon (code + eventId)

Orders

• useOrder(orderId, options?) – Single order
• useUserOrders(params?, options?) – Current user orders
• useCreateOrder() – Mutation to create an order

Payments

• usePlatformFee(eventId, amount?, options?) – Platform fee for an amount

Tickets (user)

• useUserEvents(params?, options?) – Current user events
• useUserEventTickets(eventId, options?) – Current user tickets for an event
• useTransferTicket() – Mutation to transfer a ticket
• useEditUserTicket() – Mutation to edit user ticket
• useCreateTicketFile() – Mutation to create ticket file
• useRefundUserOrder() – Mutation to refund user order

Context

• useMeapleSDK() – Access the Meaple SDK instance (throws if used outside MeapleSDKProvider)

Example

import { useEvents, useEvent } from '@meaple-com/react-query';

function EventList() {
  const { data, isPending, error } = useEvents({ limit: 20 });

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

  return (
    <ul>
      {data?.events.map((event) => (
        <li key={event.id}>{event.name}</li>
      ))}
    </ul>
  );
}

function EventDetail({ eventId, slug }: { eventId: string; slug: string }) {
  const { data: event } = useEvent(eventId, slug);
  // ...
}

With headless components

Use @meaple-com/react-headless-components for render-props components that call these hooks and expose data, isPending, error (and mutations where relevant), so you can focus on styling and layout.

Documentation

https://docs.meaple.com.br/