Stream Object

The streamObject function allows you to specify different output strategies using the output parameter. By default, the output mode is set to object, which will generate exactly the structured object that you specify in the schema option.

### Schema

It is helpful to set up the schema in a separate file that is imported on both the client and server.

import { z } from 'zod';

// define a schema for the notifications

export const notificationSchema = z.object({

notifications: z.array(

z.object({

name: z.string().describe('Name of a fictional person.'),

message: z.string().describe('Message. Do not use emojis or links.'),

}),

),

});

### Client

The client uses `useObject` to stream the object generation process.

The results are partial and are displayed as they are received.

Please note the code for handling undefined values in the JSX.

'use client';

import { experimental_useObject as useObject } from '@ai-toolkit/react';

import { notificationSchema } from './api/use-object/schema';

export default function Page() {

const { object, submit } = useObject({

api: '/api/use-object',

schema: notificationSchema,

});

return (

<div>

<button onClick={() => submit('Messages during finals week.')}>

Generate notifications

</button>

{object?.notifications?.map((notification, index) => (

<div key={index}>

<p>{notification?.name}</p>

<p>{notification?.message}</p>

</div>

))}

</div>

);

}

### Server

On the server, we use `streamObject` to stream the object generation process.

import { streamObject } from 'ai-toolkit';

import { notificationSchema } from './schema';

// Allow streaming responses up to 30 seconds

export const maxDuration = 30;

export async function POST(req: Request) {

const context = await req.json();

const result = streamObject({

model: 'openai/gpt-4.1',

schema: notificationSchema,

prompt:

Generate 3 notifications for a messages app in this context: + context,

});

return result.toTextStreamResponse();

}

You can use the loading state to display a loading indicator while the object is being generated.

You can also use the stop function to stop the object generation process.

'use client';

import { experimental_useObject as useObject } from '@ai-toolkit/react';

import { notificationSchema } from './api/use-object/schema';

export default function Page() {

const { object, submit, isLoading, stop } = useObject({

api: '/api/use-object',

schema: notificationSchema,

});

return (

<div>

<button

onClick={() => submit('Messages during finals week.')}

disabled={isLoading}

>

Generate notifications

</button>

{isLoading && (

<div>

<div>Loading...</div>

<button type="button" onClick={() => stop()}>

Stop

</button>

</div>

)}

{object?.notifications?.map((notification, index) => (

<div key={index}>

<p>{notification?.name}</p>

<p>{notification?.message}</p>

</div>

))}

</div>

);

}

The "array" output mode allows you to stream an array of objects one element at a time. This is particularly useful when generating lists of items.

### Schema

First, update the schema to generate a single object (remove the z.array()).

import { z } from 'zod';

// define a schema for a single notification

export const notificationSchema = z.object({

name: z.string().describe('Name of a fictional person.'),

message: z.string().describe('Message. Do not use emojis or links.'),

});

### Client

On the client, you wrap the schema in z.array() to generate an array of objects.

'use client';

import { experimental_useObject as useObject } from '@ai-toolkit/react';

import { notificationSchema } from '../api/use-object/schema';

import z from 'zod';

export default function Page() {

const { object, submit, isLoading, stop } = useObject({

api: '/api/use-object',

schema: z.array(notificationSchema),

});

return (

<div>

<button

onClick={() => submit('Messages during finals week.')}

disabled={isLoading}

>

Generate notifications

</button>

{isLoading && (

<div>

<div>Loading...</div>

<button type="button" onClick={() => stop()}>

Stop

</button>

</div>

)}

{object?.map((notification, index) => (

<div key={index}>

<p>{notification?.name}</p>

<p>{notification?.message}</p>

</div>

))}

</div>

);

}

### Server

On the server, specify output: 'array' to generate an array of objects.

import { streamObject } from 'ai-toolkit';

import { notificationSchema } from './schema';

export const maxDuration = 30;

export async function POST(req: Request) {

const context = await req.json();

const result = streamObject({

model: 'openai/gpt-4.1',

output: 'array',

schema: notificationSchema,

prompt:

Generate 3 notifications for a messages app in this context: + context,

});

return result.toTextStreamResponse();

}

The "no-schema" output mode can be used when you don't want to specify a schema, for example when the data structure is defined by a dynamic user request. When using this mode, omit the schema parameter and set output: 'no-schema'. The model will still attempt to generate JSON data based on the prompt.

### Client

On the client, you wrap the schema in z.array() to generate an array of objects.

'use client';

import { experimental_useObject as useObject } from '@ai-toolkit/react';

import { z } from 'zod';

export default function Page() {

const { object, submit, isLoading, stop } = useObject({

api: '/api/use-object',

schema: z.unknown(),

});

return (

<div>

<button

onClick={() => submit('Messages during finals week.')}

disabled={isLoading}

>

Generate notifications

</button>

{isLoading && (

<div>

<div>Loading...</div>

<button type="button" onClick={() => stop()}>

Stop

</button>

</div>

)}

{JSON.stringify(object, null, 2)}

</div>

);

}

### Server

On the server, specify output: 'no-schema'.

import { streamObject } from 'ai-toolkit';

export const maxDuration = 30;

export async function POST(req: Request) {

const context = await req.json();

const result = streamObject({

model: 'openai/gpt-4o',

output: 'no-schema',

prompt:

Generate 3 notifications (in JSON) for a messages app in this context: +

context,

});

return result.toTextStreamResponse();

}