The custom segment — your own message content (generative UI)

Custom segment - one escape hatch for the views an app draws itself.

Renderers are keyed on type, so subType never reaches the registry: you register ONE renderer for custom and switch on subType inside it, with fallback as the default branch. Independent views take their own type instead — register a chart renderer for a chart — and custom is for a family of small views an app would rather keep behind one key.

A segment is data, not an element — it has no tag and dispatches nothing. This one is AparteCustomSegment, and it is the object you push into a bubble; something else draws it.

Width 375 768 Full Open in a tab

Core's own renderer, drawing the example printed below inside a real viewport. A segment is data — this is what the library makes of it, and it looks the same in every framework.

Example

registerSegmentRenderer<AparteCustomSegment>({
  type: 'custom',
  render(segment) {
    const data = (segment.data ?? {}) as Record<string, unknown>;
    const el = document.createElement('div');
    switch (segment.subType) {
      case 'weather':
        el.className = 'weather';
        el.textContent = `${data['city']} — ${data['celsius']}°C`;
        break;
      case 'poll':
        el.className = 'poll';
        el.textContent = String(data['question']);
        break;
      default:
        // A subType this build does not know: the sentence, not nothing.
        el.textContent = segment.fallback ?? '';
    }
    return el;
  },
});

// The segments that renderer draws:
{ id: 's1', type: 'custom', subType: 'weather', data: { city: 'Lille', celsius: 11 } }
{ id: 's2', type: 'custom', subType: 'gantt', fallback: 'Three tasks, ending Friday.' }

Shape

Discriminated by type: 'custom'.

Field	Type	Required	Description
subType	string	yes	Which view inside the custom renderer draws this segment (e.g. ‘weather’, ‘poll’, ‘onboarding’).
data	unknown	—	Arbitrary data payload for the component

Shared by every segment

From AparteSegmentBase, which is also what a segment type of your own extends.

Field	Type	Required	Description
id	string	yes	Unique segment identifier
type	string	yes	Segment type discriminator
isStreaming	boolean	—	Whether segment is currently being streamed
fallback	string	—	One sentence standing in for the segment when no renderer claims its type — DRAWN for every type, not only for custom. More
messageId	string	—	Id of the message this segment belongs to. Stamped on insertion.
index	number	—	Position in the owning message’s segments[], maintained across insertions and removals.
meta	Record<string, unknown> & { aparte?: AparteSegmentTiming }	—	Extras the producer of the segment knows — token counts, cost, compute device — plus aparte, the one sub-object core writes. More

Notes on individual fields

fallback

One sentence standing in for the segment when no renderer claims its type — DRAWN for every type, not only for custom.

It is the answer to a real moment: a conversation replayed in another app, a client that loads its views lazily, an export. Core draws it as text (no markup) under .aparte-segment-fallback. Supplying one also silences the “no renderer” developer warning: an author who wrote a fallback has already said this can happen.

In the HISTORY sent back to the model it stands in for the segment only where core does not serialise the type itself — custom, and any type core does not know (a registered block grammar’s, a plugin’s). A text or a code segment contributes its content and nothing else; thinking and tool_call are left out of the history on purpose (_segmentsToText in AparteClient states why), and so is error.

meta

Extras the producer of the segment knows — token counts, cost, compute device — plus aparte, the one sub-object core writes.

Everything except meta.aparte is yours: fill it with updateSegment(segmentId, { meta }), which MERGES rather than replaces. Mirrors AparteMessage.metadata.

Who emits it

An app pushes one with addSegment() on the viewport, or a parser produces it while a reply streams. Core stamps its identity and timing on insert, so an emitted segment does not have to carry them.

Who draws it

Nothing in core draws this one — it is the escape hatch, and the renderer is yours. Without one registered, core falls back: it draws the segment’s fallback string when there is one, and otherwise a [Unknown segment type: custom] placeholder with a console warning naming the type.

import { registerSegmentRenderer } from '@aparte/core';
import type { AparteCustomSegment } from '@aparte/core';

registerSegmentRenderer({
    type: 'custom',
    render: (segment: AparteCustomSegment) => {
        const el = document.createElement('div');
        el.textContent = JSON.stringify(segment);
        return el;
    },
});

See Customization for the whole renderer seam, and bring your own loop for emitting segments yourself.