useRateLimit

React hook for real-time rate limit status in your components

Overview

The useRateLimit hook provides real-time rate limit information in your React components. It monitors the current rate limit status and automatically updates when capacity changes, allowing you to show users when they can retry an action.

Function Signature

function useRateLimit(
  getRateLimitValueQuery: GetRateLimitValueQuery,
  opts?: UseRateLimitOptions
): {
  status: { ok: true; retryAt: undefined } | { ok: false; retryAt: number } | undefined;
  check: (ts?: number, count?: number) => CheckResult | undefined;
}

Type Definitions

type GetRateLimitValueQuery = FunctionReference<
  "query",
  "public",
  GetValueArgs,
  GetValueReturns
>;

type UseRateLimitOptions = {
  name?: string;
  key?: string;
  count?: number;
  sampleShards?: number;
  getServerTimeMutation?: GetServerTimeMutation;
  config?: RateLimitConfig;
};

type GetServerTimeMutation = FunctionReference<
  "mutation",
  "public",
  Record<string, never>,
  number
>;

Parameters

getRateLimitValueQuery · GetRateLimitValueQuery · required

The query function returned by rateLimiter.hookAPI().getRateLimit. This query retrieves the current rate limit value from the server.

opts · UseRateLimitOptions

Optional configuration object for the hook.

Show properties

name · string

The name of the rate limit. If not provided, uses the name from the server configuration.

key · string

The key for a per-user/per-session rate limit. Only works if the server-side hookAPI() configuration allows client-provided keys.

count · number · default: "1"

The number of tokens to check against. Used to determine if there’s enough capacity for an operation that consumes multiple tokens.

sampleShards · number · default: "1"

Number of shards to sample when checking rate limit status. Higher values provide more accurate results for sharded rate limits.

getServerTimeMutation · GetServerTimeMutation

A mutation that returns the current server time (Date.now()). Highly recommended for accurate time synchronization between client and server. Use the mutation returned by rateLimiter.hookAPI().getServerTime.

config · RateLimitConfig

Inline rate limit configuration. Only needed if the rate limit wasn’t defined in the RateLimiter constructor and isn’t provided by the server query.

Return Value

status · object | undefined

The current rate limit status. undefined while loading.

When ok: true:

Show properties

ok · true

The rate limit check passed - there’s enough capacity.

retryAt · undefined

No retry needed.

When ok: false:

Show properties

ok · false

The rate limit would be exceeded.

retryAt · number

Client-time timestamp (in milliseconds) when the action can be retried with enough capacity.

check · function

A function to manually check the rate limit at a specific time or for a different token count.

Signature: (ts?: number, count?: number) => CheckResult | undefined

Show parameters

ts · number

Client timestamp to check the rate limit at. Defaults to Date.now().

count · number

Number of tokens to check. Defaults to the count from hook options or 1.

Returns CheckResult | undefined:

type CheckResult = {
  value: number;        // Current token value
  ts: number;          // Client timestamp of the value
  config: RateLimitConfig;  // The rate limit configuration
  shard: number;       // The shard number
  ok: boolean;         // Whether the check passed
  retryAt?: number;    // Client timestamp when retry would succeed
}

Usage Example

Basic React Component

import { useRateLimit } from "@convex-dev/rate-limiter/react";
import { api } from "./convex/_generated/api";

function SendMessageButton() {
  const { status, check } = useRateLimit(
    api.messages.getRateLimit,
    {
      // Recommended: sync client/server clocks
      getServerTimeMutation: api.messages.getServerTime,
      // Check if we have capacity for 1 message
      count: 1,
    }
  );

  if (!status) {
    return <button disabled>Loading...</button>;
  }

  if (!status.ok) {
    const waitSeconds = Math.ceil((status.retryAt - Date.now()) / 1000);
    return (
      <button disabled>
        Wait {waitSeconds}s before sending
      </button>
    );
  }

  return <button onClick={handleSend}>Send Message</button>;
}

With Manual Checking

function TokenConsumer() {
  const [tokenCount, setTokenCount] = useState(10);
  const { status, check } = useRateLimit(
    api.llm.getRateLimit,
    {
      getServerTimeMutation: api.llm.getServerTime,
    }
  );

  // Check if we have capacity for the current token count
  const result = check(Date.now(), tokenCount);

  return (
    <div>
      <input
        type="number"
        value={tokenCount}
        onChange={(e) => setTokenCount(Number(e.target.value))}
      />
      {result && (
        <div>
          {result.ok ? (
            <p>Available capacity: {result.value} tokens</p>
          ) : (
            <p>Retry in {Math.ceil((result.retryAt - Date.now()) / 1000)}s</p>
          )}
        </div>
      )}
    </div>
  );
}

Time Synchronization

The hook uses getServerTimeMutation to synchronize the client and server clocks. This is highly recommended because:

1. Client clocks can be inaccurate or intentionally set incorrectly
2. The rate limit calculations happen server-side using server time
3. Without synchronization, retryAt values may be incorrect

How It Works

// The hook measures latency and calculates the offset
const clientTime = Date.now();
const serverTime = await convex.mutation(getServerTimeMutation, {});
const latency = Date.now() - clientTime;
const timeOffset = serverTime - clientTime - latency / 2;

// All times are then adjusted
const adjustedRetryAt = serverRetryTime - timeOffset;

Server Setup

The getServerTime mutation is automatically included when you use hookAPI():

// In convex/messages.ts
export const { getRateLimit, getServerTime } = rateLimiter.hookAPI(
  "sendMessage",
  {
    key: async (ctx) => await getUserId(ctx),
  }
);

Advanced Patterns

See React Hooks Guide for more examples including:

• Displaying countdown timers
• Optimistic UI updates
• Multi-token operations
• Custom retry strategies

Related

• hookAPI() - Set up server-side queries for the hook
• React Hooks Guide - Advanced usage patterns
• getValue() - Direct value fetching