Docs

colinhacks · colinhacks · commit 4755ac7544c1 · 2025-07-28T17:00:36.000-07:00
diff --git a/packages/docs/content/api.mdx b/packages/docs/content/api.mdx
@@ -2147,6 +2147,9 @@ schema.parse({
 
 ### `.superRefine()`
     
+
+The regular `.refine` API only generates a single issue with a `"custom"` error code, but `.superRefine()` makes it possible to create multiple issues using any of Zod's [internal issue types](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/errors.ts).
+
 <Tabs groupId="lib" items={["Zod", "Zod Mini"]}>
 <Tab value="Zod">
 ```ts
@@ -2204,7 +2207,12 @@ const UniqueStringArray = z.array(z.string()).check(
 
 ### `.check()`
 
+<Callout>
+**Note** — The `.check()` API is a more low-level API that's generally more complex than `.superRefine()`. It can be faster in performance-sensitive code paths, but it's also more verbose.
+</Callout>
 
+<Accordions>
+<Accordion title="View example">
 The `.refine()` API is syntactic sugar atop a more versatile (and verbose) API called `.check()`. You can use this API to create multiple issues in a single refinement or have full control of the generated issue objects.
 
 <Tabs groupId="lib" items={["Zod", "Zod Mini"]}>
@@ -2263,8 +2271,8 @@ const UniqueStringArray = z.array(z.string()).check((ctx) => {
 ```
 </Tab>
 </Tabs>
-
-The regular `.refine` API only generates issues with a `"custom"` error code, but `.check()` makes it possible to throw other issue types. For more information on Zod's internal issue types, read the [Error customization](./error-customization) docs.
+</Accordion>
+</Accordions>
 
 ## Pipes
 
diff --git a/packages/zod/src/v4/core/api.ts b/packages/zod/src/v4/core/api.ts
@@ -1449,13 +1449,6 @@ export function _custom<O = unknown, I = O>(
   return schema as any;
 }
 
-// export function _refine<T>(
-//   Class: util.SchemaClass<schemas.$ZodCustom>,
-//   fn: (arg: NoInfer<T>) => util.MaybeAsync<unknown>,
-//   _params: string | $ZodCustomParams = {}
-// ): checks.$ZodCheck<T> {
-//   return _custom(Class, fn, _params);
-// }
 // same as _custom but defaults to abort:false
 export function _refine<O = unknown, I = O>(
   Class: util.SchemaClass<schemas.$ZodCustom>,
