www/docs/client/links/splitLink.mdx - main - githubmirror/trpc

www/docs/client/links/splitLink.mdx
155 строк5 KB
Nick Lucas
feat(docs): revamp docs content for 2026, more framework agnostic, improved Next.js docs (#7193)
08 мар 2026, 12:14
08 мар 2026, 12:142bf122d
---
id: splitLink
title: Split Link
sidebar_label: Split Link
slug: /client/links/splitLink
---

import SplitLinkDiagram from '../../../static/img/split-link-diagram.svg';

`splitLink` is a link that allows you to branch your link chain's execution depending on a given condition. Both the `true` and `false` branches are required. You can provide just one link, or multiple links per branch via an array.

It's important to note that when you provide links for `splitLink` to execute, `splitLink` will create an entirely new link chain based on the links you passed. Therefore, you need to use a [**terminating link**](./overview.md#the-terminating-link) if you only provide one link or add the terminating link at the end of the array if you provide multiple links to be executed on a branch. Here's a visual representation of how `splitLink` works:

<div align="center" style={{ marginBottom: '12px' }}>
  <SplitLinkDiagram style={{ width: '100%', height: '100%' }} />
</div>

## Usage Example

### Disable batching for certain requests

Let's say you're using `httpBatchLink` as the terminating link in your tRPC client config. This means request batching is enabled in every request. However, if you need to disable batching only for certain requests, you would need to change the terminating link in your tRPC client config dynamically between `httpLink` and `httpBatchLink`. This is a perfect opportunity for `splitLink` to be used:

#### 1. Configure client / `utils/trpc.ts`

```ts twoslash title="client/index.ts"
// @filename: server.ts
import { initTRPC } from '@trpc/server';
const t = initTRPC.create();
export const appRouter = t.router({});
export type AppRouter = typeof appRouter;

// @filename: client.ts
// ---cut---
import {
  createTRPCClient,
  httpBatchLink,
  httpLink,
  splitLink,
} from '@trpc/client';
import type { AppRouter } from './server';

const url = `http://localhost:3000`;

const client = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      condition(op) {
        // check for context property `skipBatch`
        return Boolean(op.context.skipBatch);
      },
      // when condition is true, use normal request
      true: httpLink({
        url,
      }),
      // when condition is false, use batching
      false: httpBatchLink({
        url,
      }),
    }),
  ],
});
```

#### 2. Perform request without batching

```ts twoslash title='client.ts'
// @filename: server.ts
import { initTRPC } from '@trpc/server';
const t = initTRPC.create();
export const appRouter = t.router({
  posts: t.procedure.query(() => []),
});
export type AppRouter = typeof appRouter;

// @filename: client.ts
import { createTRPCClient, httpBatchLink, splitLink, httpLink } from '@trpc/client';
import type { AppRouter } from './server';
const proxy = createTRPCClient<AppRouter>({
  links: [
    splitLink({
      condition(op) { return Boolean(op.context.skipBatch); },
      true: httpLink({ url: 'http://localhost:3000' }),
      false: httpBatchLink({ url: 'http://localhost:3000' }),
    }),
  ],
});
// ---cut---
const postResult = proxy.posts.query(undefined, {
  context: {
    skipBatch: true,
  },
});
```

or:

```tsx twoslash title='MyComponent.tsx'
// @jsx: react-jsx
// @filename: server.ts
import { initTRPC } from '@trpc/server';
const t = initTRPC.create();
export const appRouter = t.router({
  posts: t.procedure.query(() => [{ id: 1, title: 'Hello' }]),
});
export type AppRouter = typeof appRouter;

// @filename: trpc.ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from './server';
export const trpc = createTRPCReact<AppRouter>();

// @filename: MyComponent.tsx
// ---cut---
import { trpc } from './trpc';

export function MyComponent() {
  const postsQuery = trpc.posts.useQuery(undefined, {
    trpc: {
      context: {
        skipBatch: true,
      },
    }
  });
  return (
    <pre>{JSON.stringify(postsQuery.data ?? null, null, 4)}</pre>
  )
}
```

## `splitLink` Options

The `splitLink` function takes an options object that has three fields: `condition`, `true`, and `false`.

```ts twoslash
type AnyRouter = any;
type Operation = any;
type TRPCLink<T> = any;
// ---cut---
declare function splitLink<TRouter extends AnyRouter = AnyRouter>(opts: {
  condition: (op: Operation) => boolean;
  /**
   * The link to execute next if the test function returns `true`.
   */
  true: TRPCLink<TRouter> | TRPCLink<TRouter>[];
  /**
   * The link to execute next if the test function returns `false`.
   */
  false: TRPCLink<TRouter> | TRPCLink<TRouter>[];
}): TRPCLink<TRouter>;
```

## Reference

You can check out the source code for this link on [GitHub.](https://github.com/trpc/trpc/blob/main/packages/client/src/links/splitLink.ts)