Create custom views

Custom views transform complex traces and dataset rows into interfaces anyone on your team can use. Describe what you want in natural language and Loop generates an interactive React component you can customize or embed anywhere.

Common use cases

Human review and annotation

Build custom annotation interfaces for large-scale human review tasks, surfacing only relevant information for annotators and subject matter experts.

Simplifying traces for non-engineers

Replace JSON with intuitive UI components like carousels, playlists, or structured summaries to make traces accessible to PMs, legal reviewers, and domain experts.

Industry-specific visualizations

Create views that mirror your product experience:

Playlist-style views for music applications
Interactive source-and-answer layouts
Custom dashboards for internal evaluations

Multi-turn conversation analysis

Aggregate and display data across conversation turns to analyze dialogue flow and long-running interactions.

Create views

To create a custom view using Loop:

Select a trace or open a dataset row.
Select Views.
Describe how you want to view your data.

After Loop generates your view, refine it by describing additional changes or edit the React component code directly. Example prompts:

Trace views
Dataset views

“Create a view that renders a list of all tools available in this trace and their outputs”
“Build an interface to review each trace one by one with easy switching between traces”
“Create a conversation-style view that highlights user messages and assistant responses”
“Render the video url from the trace’s metadata field and show simple thumbs up/down buttons”

Self-hosted deployments: If you restrict outbound access, allowlist https://www.braintrustsandbox.dev to enable custom views. This domain hosts the sandboxed iframe that securely renders custom view code.

Custom views are stored differently depending on whether they’ve been saved:

Unsaved views exist only in the browser where you created them. If you close the browser, clear browser data, or switch to a different device, the view will not be available.
Saved views are stored in Braintrust, versioned, and available to all team members in the project.

To save your view and share it with your team:

Select Save in the view editor.
Choose Save as new view version.
Select Update to make it available project-wide.

All team members can then use the shared view when reviewing traces or dataset rows. Custom views integrate with Braintrust workflows. Use them during human review, write annotations that flow into datasets, and combine with Loop for analysis.

Edit view React code

Custom views are React components that run inside Braintrust. You can edit the component code directly to customize behavior beyond what Loop generates. To edit the React code:

Go to the custom view.
Select in the lower left of the view.
Select Edit.

Your React component receives props based on the view type:

Trace views
Dataset views

Prop	Type	Description
`trace`	object	Contains all spans and methods for the trace. Attachment URLs in span data are automatically signed for rendering.
`span`	object	The currently selected span with full data
`update`	function	Update span metadata: `update('field', value)`
`selectSpan`	function	Navigate to a different span: `selectSpan(spanId)`

The trace object includes:

rootSpanId, selectedSpanId - Current span context
spanOrder - All span IDs in execution order
spans - Map of span_id → span (IDs/relationships only)
fetchSpanFields - Fetch full data for multiple spans (see Access data from multiple spans)

Prop	Type	Description
`input`	object	The row’s input field.
`expected`	object	The row’s expected field.
`metadata`	object	The row’s metadata field.
`tags`	string[]	Tags applied to the row.
`id`	string	The row’s unique identifier.

The component can be copied and embedded in your own applications, enabling you to:

Reuse custom views outside of Braintrust
Integrate review interfaces into internal tools
Build standalone annotation applications
Create consistent review experiences across different contexts

Add interactive controls

Custom views support interactive elements that write data back to traces. Add buttons, inputs, or custom controls to collect:

Human review scores
Thumbs up/down feedback
Custom metadata fields
Annotation notes

Use the update function to write metadata back to the trace. This enables annotation workflows where review and data collection happen in the same interface.

Example: Add thumbs up/down buttons

function FeedbackView({ trace, span, update }) {
  const handleFeedback = (isPositive) => {
    update('metadata', {
      ...span.metadata,
      user_feedback: isPositive ? 'positive' : 'negative',
      reviewed_at: new Date().toISOString(),
    });
  };

  return (
    <div className="p-4">
      <h3 className="text-lg font-semibold mb-4">Review this output</h3>
      <pre className="bg-slate-100 p-2 rounded mb-4">
        {JSON.stringify(span.output, null, 2)}
      </pre>
      <div className="flex gap-2">
        <button onClick={() => handleFeedback(true)}>👍 Good</button>
        <button onClick={() => handleFeedback(false)}>👎 Bad</button>
      </div>
    </div>
  );
}

module.exports = FeedbackView;

Access data from multiple spans

By default, only the selected span has full data (input, output, expected, metadata). To access data from other spans, use fetchSpanFields:

// Fetch all fields for one span
const data = await trace.fetchSpanFields(spanId);

// Fetch specific fields for multiple spans
const data = await trace.fetchSpanFields(trace.spanOrder, ['input', 'output']);

Example: Display all span inputs

function AllInputsView({ trace, span }) {
  const [spanData, setSpanData] = React.useState(null);
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState(null);

  React.useEffect(() => {
    if (!trace?.fetchSpanFields) return;

    trace.fetchSpanFields(trace.spanOrder, ['input'])
      .then(setSpanData)
      .catch((err) => {
        console.error('Failed to fetch span data:', err.message);
        setError(err.message);
      })
      .finally(() => setLoading(false));
  }, [trace]);

  if (loading) return <div className="p-4">Loading...</div>;
  if (error) return <div className="p-4 text-red-600">Error: {error}</div>;

  return (
    <div className="p-4 space-y-2">
      {trace.spanOrder.map((id) => (
        <pre key={id} className="text-xs bg-slate-100 p-2 rounded text-wrap">
          {JSON.stringify(spanData?.[id]?.input, null, 2)}
        </pre>
      ))}
    </div>
  );
}

module.exports = AllInputsView;

Render attachments

Attachments (images, videos, audio, and other binary data) logged in your traces can be displayed directly in custom views. When span data is fetched, Braintrust automatically converts attachment references to inline_attachment objects with pre-signed URLs ready for rendering. Attachments in span data are automatically transformed into objects with this structure:

{
  type: "inline_attachment",
  src: "https://signed-url...",      // Pre-signed URL ready to use
  content_type: "image/jpeg",        // MIME type
  filename: "example.jpg",           // Optional filename
  data?: string                      // Pre-fetched text content (JSON, text, CSV, XML, Markdown attachments)
}

The type field identifies the object as an attachment, src contains a pre-signed URL that works directly in image, video, or audio tags, and content_type indicates the media type. For text-based attachment references (JSON, plain text, CSV, XML, and Markdown) that Braintrust signs on the viewer’s behalf, Braintrust pre-fetches the content and populates the data field with the text string. Structured inline_attachment objects you log directly with an http or data: URL in src are passed through unchanged and will not have data populated. When data is present, render it directly instead of loading from src.

Size limits apply to pre-fetching: 1MB per individual attachment and 5MB in aggregate across the entire payload being processed. The initial custom view load signs the full {trace, span} object (which includes all spans in the trace), and each fetchSpanFields call signs all spans in that response together. Once the 5MB aggregate is reached within a single payload, remaining text attachments will have data omitted even if each individual attachment is under 1MB. The content is still accessible via src in all cases.

For example, the following code creates an input/output verification view that automatically detects and renders attachments alongside regular data:

Example: Input/output verification

function InputOutputVerification({ trace, span }) {
  // Helper to check if a value is an attachment
  const isAttachment = (value) => {
    return value && typeof value === 'object' && value.type === 'inline_attachment' && value.src;
  };

  // Helper to render a value, handling attachments and regular data
  const renderValue = (value, label) => {
    if (!value && value !== 0 && value !== false) {
      return (
        <div className="text-slate-400 italic">No {label.toLowerCase()}</div>
      );
    }

    // Check if it's an attachment
    if (isAttachment(value)) {
      const { src, filename, content_type, data } = value;
      if (content_type?.startsWith('image/')) {
        return (
          <div className="space-y-2">
            <img src={src} alt={filename || 'attachment'} className="max-w-full rounded-lg border border-slate-200 shadow-sm" />
            {filename && <p className="text-xs text-slate-500">{filename}</p>}
          </div>
        );
      }
      if (content_type?.startsWith('video/')) {
        return <video src={src} controls className="max-w-full rounded-lg" />;
      }
      if (content_type?.startsWith('audio/')) {
        return <audio src={src} controls className="w-full" />;
      }
      // For text-based attachments, use pre-fetched data when available
      if (data !== undefined) {
        const isJson = content_type === 'application/json' || filename?.endsWith('.json');
        let displayText = data;
        if (isJson) {
          try { displayText = JSON.stringify(JSON.parse(data), null, 2); } catch (_) {}
        }
        return (
          <div className="space-y-1">
            {filename && <p className="text-xs text-slate-500">{filename}</p>}
            <pre className="text-sm bg-slate-50 p-3 rounded border border-slate-200 overflow-auto whitespace-pre-wrap">{displayText}</pre>
          </div>
        );
      }
      return <a href={src} download={filename} className="text-blue-600 underline">{filename || 'Download attachment'}</a>;
    }

    // Handle objects that might contain attachments
    if (typeof value === 'object') {
      const entries = Object.entries(value);
      return (
        <div className="space-y-3">
          {entries.map(([key, val]) => (
            <div key={key}>
              <div className="text-xs font-semibold text-slate-600 uppercase mb-1">{key}</div>
              <div className="pl-2 border-l-2 border-slate-200">
                {renderValue(val, key)}
              </div>
            </div>
          ))}
        </div>
      );
    }

    // Handle strings and primitives
    if (typeof value === 'string') {
      return <div className="whitespace-pre-wrap text-slate-800">{value}</div>;
    }

    return <pre className="text-sm bg-slate-50 p-3 rounded border border-slate-200 overflow-auto">{JSON.stringify(value, null, 2)}</pre>;
  };

  const input = span?.data?.input;
  const output = span?.data?.output;
  const expected = span?.data?.expected;

  return (
    <div className="w-[100vw] min-h-screen bg-slate-50 p-6">
      <div className="max-w-7xl mx-auto">
        <h1 className="text-2xl font-bold text-slate-900 mb-6">Input & Output Verification</h1>

        <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
          {/* Input Section */}
          <div className="bg-white rounded-lg shadow-sm border border-slate-200 p-6">
            <div className="flex items-center gap-2 mb-4">
              <div className="w-2 h-2 bg-blue-500 rounded-full"></div>
              <h2 className="text-lg font-semibold text-slate-900">Input</h2>
            </div>
            <div className="space-y-4">
              {renderValue(input, 'Input')}
            </div>
          </div>

          {/* Output Section */}
          <div className="bg-white rounded-lg shadow-sm border border-slate-200 p-6">
            <div className="flex items-center gap-2 mb-4">
              <div className="w-2 h-2 bg-green-500 rounded-full"></div>
              <h2 className="text-lg font-semibold text-slate-900">Output</h2>
            </div>
            <div className="space-y-4">
              {renderValue(output, 'Output')}
            </div>
          </div>
        </div>

        {/* Expected Section (if exists) */}
        {expected && (
          <div className="mt-6 bg-white rounded-lg shadow-sm border border-slate-200 p-6">
            <div className="flex items-center gap-2 mb-4">
              <div className="w-2 h-2 bg-amber-500 rounded-full"></div>
              <h2 className="text-lg font-semibold text-slate-900">Expected</h2>
            </div>
            <div className="space-y-4">
              {renderValue(expected, 'Expected')}
            </div>
          </div>
        )}

        {/* Metadata Section */}
        {span?.data?.metadata && Object.keys(span.data.metadata).length > 0 && (
          <div className="mt-6 bg-white rounded-lg shadow-sm border border-slate-200 p-6">
            <div className="flex items-center gap-2 mb-4">
              <div className="w-2 h-2 bg-purple-500 rounded-full"></div>
              <h2 className="text-lg font-semibold text-slate-900">Metadata</h2>
            </div>
            <div className="space-y-4">
              {renderValue(span.data.metadata, 'Metadata')}
            </div>
          </div>
        )}

        {/* Scores Section */}
        {span?.data?.scores && Object.keys(span.data.scores).length > 0 && (
          <div className="mt-6 bg-white rounded-lg shadow-sm border border-slate-200 p-6">
            <div className="flex items-center gap-2 mb-4">
              <div className="w-2 h-2 bg-rose-500 rounded-full"></div>
              <h2 className="text-lg font-semibold text-slate-900">Scores</h2>
            </div>
            <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
              {Object.entries(span.data.scores).map(([name, score]) => (
                <div key={name} className="bg-slate-50 rounded p-3 border border-slate-200">
                  <div className="text-xs text-slate-600 mb-1">{name}</div>
                  <div className="text-2xl font-bold text-slate-900">
                    {typeof score === 'number' ? score.toFixed(2) : score}
                  </div>
                </div>
              ))}
            </div>
          </div>
        )}
      </div>
    </div>
  );
}

module.exports = InputOutputVerification;

Custom view PDF limitation: PDF files referenced as ExternalAttachment objects cannot be rendered in custom views due to browser-level security restrictions in the sandboxed iframe environment. While images and videos work correctly, browsers block PDF rendering in this context.To display PDFs in custom views, upload them as standard Attachment objects or host them externally and link to them instead of attempting inline rendering.

Duplicate views

Duplicate custom views to reuse them across different projects or organizations. This lets you create a view once and apply the same interface across multiple projects without rebuilding from scratch. To duplicate a custom view:

Open the custom view you want to duplicate.
Select in the lower left of the view.
Select Duplicate.
Give the new view a name.
Choose the target organization and project.
Select Duplicate to create a copy in the selected project.

The duplicated view includes all React component code and configuration, creating an independent copy you can modify without affecting the original.

Rename views

To rename a custom view:

Go to the custom view.
Select in the lower left of the view.
Select Rename.
Enter a new name for the view.
Select Save to save the changes.

Access version history

Every time you save changes to a custom view, Braintrust creates a new version with a timestamp. To view or switch between previous versions:

Go to the custom view.
Select in the lower left of the view.
Select Version to see all past versions.
Choose any previous version to switch to it.

The current version is marked with a Latest label.

Next steps

Add human feedback
Build datasets from annotated traces
Learn about Loop for AI-assisted development

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Common use cases

Create views

Edit view React code

Add interactive controls

Access data from multiple spans

Render attachments

Duplicate views

Rename views

Access version history

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Documentation Index

​Common use cases

​Create views

​Share views

​Edit view React code

​Add interactive controls

​Access data from multiple spans

​Render attachments

​Duplicate views

​Rename views

​Access version history

​Next steps

Common use cases

Create views

Share views

Edit view React code

Add interactive controls

Access data from multiple spans

Render attachments

Duplicate views

Rename views

Access version history

Next steps