Layout Customization

Recipes for restructuring Velt components with wireframes: targeted single-slot overrides, full-tree rebuilds, variants, and the replace/remove/reorder tasks. Concepts and rules (the registry model, the interactivity rule, scoping) live in the Wireframes Overview.

Styling note: Passing className/style to Velt components does not change their UI. Add your classes/styles inside the Wireframe templates, or use CSS overrides with Shadow DOM disabled. See Styling.

Ways to Customize Layout

Single Component Customization (Targeted)

This lets you customize individual parts of a component without dealing with the entire structure. We recommend this approach for most use cases. Benefits:

Simpler, more maintainable code
Focus on just the parts you need to change
Greater flexibility for specific UI elements

Example: Customizing just the Comment Dialog header:

React / Next.js
Other Frameworks

<VeltWireframe>
    <VeltCommentDialogWireframe.Header>
        <div className="custom-header">
            <VeltCommentDialogWireframe.Status />
            <VeltCommentDialogWireframe.Priority />
            <VeltCommentDialogWireframe.Options />
            <VeltCommentDialogWireframe.CopyLink />
            <VeltCommentDialogWireframe.ResolveButton />
        </div>
    </VeltCommentDialogWireframe.Header>
</VeltWireframe>

<velt-wireframe style="display:none;">
    <velt-comment-dialog-header-wireframe>
        <div class="custom-header">
            <velt-comment-dialog-status-wireframe></velt-comment-dialog-status-wireframe>
            <velt-comment-dialog-priority-wireframe></velt-comment-dialog-priority-wireframe>
            <velt-comment-dialog-options-wireframe></velt-comment-dialog-options-wireframe>
            <velt-comment-dialog-copy-link-wireframe></velt-comment-dialog-copy-link-wireframe>
            <velt-comment-dialog-resolve-button-wireframe></velt-comment-dialog-resolve-button-wireframe>
        </div>
    </velt-comment-dialog-header-wireframe>
</velt-wireframe>

Full Component Tree Customization (Comprehensive)

Use this pattern when you need to modify the entire component structure or multiple related components. Benefits:

Complete control over component hierarchy
Easier to modify relationships between components
Better for large-scale structural changes

Drawbacks:

Custom CSS required for the entire component tree since adding children components to wireframes removes Velt’s default styles.

Declaring a container slot means you own its whole child tree: structural children you omit disappear instead of falling back to Velt’s defaults. Declare the full structure you want. See slot granularity.

Example: Customizing the entire Comment Dialog structure:

React / Next.js
Other Frameworks

<VeltWireframe>
    <VeltCommentDialogWireframe>
        <VeltCommentDialogWireframe.GhostBanner />
        <VeltCommentDialogWireframe.AssigneeBanner />
        <div className="dialog-content">
            <VeltCommentDialogWireframe.Header />
            <VeltCommentDialogWireframe.Body />
            <VeltCommentDialogWireframe.Composer />
            <VeltCommentDialogWireframe.AllComment />
        </div>
    </VeltCommentDialogWireframe>
</VeltWireframe>

<velt-wireframe style="display:none;">
    <velt-comment-dialog-wireframe>
        <velt-comment-dialog-ghost-banner-wireframe></velt-comment-dialog-ghost-banner-wireframe>
        <velt-comment-dialog-assignee-banner-wireframe></velt-comment-dialog-assignee-banner-wireframe>
        <div class="dialog-content">
            <velt-comment-dialog-header-wireframe></velt-comment-dialog-header-wireframe>
            <velt-comment-dialog-body-wireframe></velt-comment-dialog-body-wireframe>
            <velt-comment-dialog-composer-wireframe></velt-comment-dialog-composer-wireframe>
            <velt-comment-dialog-all-comment-wireframe></velt-comment-dialog-all-comment-wireframe>
        </div>
    </velt-comment-dialog-wireframe>
</velt-wireframe>

Variants

Variants allow you to:

Create multiple styled versions of the same component
Switch between them dynamically in different parts of your app
Maintain consistent behavior while having different looks

Create Custom Variants

Custom variants let you define your own versions of components. For example: You can have a variant of Comment Sidebar for one page and another for another page.

Define variants

On the wireframe component, add the variant prop to define your custom variants.

React / Next.js
Other Frameworks

<VeltWireframe>
    {/* Variant for preview page */}
    <VeltCommentsSidebarWireframe variant="preview-page">
        {/* Custom layout for preview */}
    </VeltCommentsSidebarWireframe>

    {/* Variant for editor page */}
    <VeltCommentsSidebarWireframe variant="editor-page">
        {/* Custom layout for editor */}
    </VeltCommentsSidebarWireframe>
</VeltWireframe>

<velt-wireframe style="display:none;">
    {/* Variant for preview page */}
    <velt-comments-sidebar-wireframe variant="preview-page">
        {/* Custom layout for preview */}
    </velt-comments-sidebar-wireframe>

    {/* Variant for editor page */}
    <velt-comments-sidebar-wireframe variant="editor-page">
        {/* Custom layout for editor */}
    </velt-comments-sidebar-wireframe>
</velt-wireframe>

Use variants

Use the variant prop on the related Velt component to apply the custom variant you defined. The value should match the variant name from step 1.
For example, use variant="preview-page" to apply the preview page variant you created above.

React / Next.js
Other Frameworks

<VeltCommentsSidebar variant="preview-page" />

<velt-comments-sidebar variant="preview-page"></velt-comments-sidebar>

Use Pre-defined Variants

Many components come with built-in variants optimized for specific use cases. For example, the Comment Dialog has two pre-defined variants for different contexts:

React / Next.js
Other Frameworks

<VeltWireframe>
    {/* For Pin, Area, and Text comments */}
    <VeltCommentDialogWireframe variant="dialog">
        {/* Custom layout */}
    </VeltCommentDialogWireframe>

    {/* For Sidebar comments */}
    <VeltCommentDialogWireframe variant="sidebar">
        {/* Custom layout */}
    </VeltCommentDialogWireframe>
</VeltWireframe>

<velt-wireframe style="display:none;">
    {/* For Pin, Area, and Text comments */}
    <velt-comment-dialog-wireframe variant="dialog">
        {/* Custom layout */}
    </velt-comment-dialog-wireframe>

    {/* For Sidebar comments */}
    <velt-comment-dialog-wireframe variant="sidebar">
        {/* Custom layout */}
    </velt-comment-dialog-wireframe>
</velt-wireframe>

Each component’s documentation lists its supported pre-defined variants
Pre-defined variants are optimized for specific use cases but can still be customized
You can combine pre-defined variants with your own custom styling

Common Customization Tasks

Replace Default Layout

Simply provide your own HTML or components as children of the wireframe component:

React / Next.js
Other Frameworks

<VeltWireframe>
    <VeltCommentDialogWireframe.Composer.ActionButton type="attachments">
        <button className="custom-attachment-btn">
            <CustomIcon />
            Add Files
        </button>
    </VeltCommentDialogWireframe.Composer.ActionButton>
</VeltWireframe>

<velt-wireframe style="display:none;">
    <velt-comment-dialog-composer-action-button-wireframe type="attachments">
        <button class="custom-attachment-btn">
            <custom-icon></custom-icon>
            Add Files
        </button>
    </velt-comment-dialog-composer-action-button-wireframe>
</velt-wireframe>

Remove Components

To remove a component, you either:

simply omit it from the wireframe template as shown below, or
use Conditional Templates

React / Next.js
Other Frameworks

<VeltWireframe>
    <VeltCommentDialogWireframe.Header>
        {/* Priority and CopyLink buttons removed */}
        <VeltCommentDialogWireframe.Status />
        <VeltCommentDialogWireframe.Options />
        <VeltCommentDialogWireframe.ResolveButton />
    </VeltCommentDialogWireframe.Header>
</VeltWireframe>

<velt-wireframe style="display:none;">
    <velt-comment-dialog-header-wireframe>
        {/* Priority and CopyLink buttons removed */}
        <velt-comment-dialog-status-wireframe></velt-comment-dialog-status-wireframe>
        <velt-comment-dialog-options-wireframe></velt-comment-dialog-options-wireframe>
        <velt-comment-dialog-resolve-button-wireframe></velt-comment-dialog-resolve-button-wireframe>
    </velt-comment-dialog-header-wireframe>
</velt-wireframe>

Reorder Components

To reorder components, simply rearrange them within the wireframe template.

React / Next.js
Other Frameworks

<VeltWireframe>
    <VeltCommentDialogWireframe.Header>
        <VeltCommentDialogWireframe.Priority />
        <VeltCommentDialogWireframe.Status />
        <VeltCommentDialogWireframe.CopyLink />
        <VeltCommentDialogWireframe.ResolveButton />
        <VeltCommentDialogWireframe.Options />
    </VeltCommentDialogWireframe.Header>
</VeltWireframe>

<velt-wireframe style="display:none;">
    <velt-comment-dialog-header-wireframe>
        <velt-comment-dialog-priority-wireframe></velt-comment-dialog-priority-wireframe>
        <velt-comment-dialog-status-wireframe></velt-comment-dialog-status-wireframe>
        <velt-comment-dialog-copy-link-wireframe></velt-comment-dialog-copy-link-wireframe>
        <velt-comment-dialog-resolve-button-wireframe></velt-comment-dialog-resolve-button-wireframe>
        <velt-comment-dialog-options-wireframe></velt-comment-dialog-options-wireframe>
    </velt-comment-dialog-header-wireframe>
</velt-wireframe>

Concepts

AI Agent Workflow

Approaches

Feature Guides

Components: Async Collaboration

Components: Realtime Collaboration

Guidance

Reference

Layout Customization

Ways to Customize Layout

Single Component Customization (Targeted)

Full Component Tree Customization (Comprehensive)

Variants

Create Custom Variants

Use Pre-defined Variants

Common Customization Tasks

Replace Default Layout

Remove Components

Reorder Components

​Ways to Customize Layout

​Single Component Customization (Targeted)

​Full Component Tree Customization (Comprehensive)

​Variants

​Create Custom Variants

​Use Pre-defined Variants

​Common Customization Tasks

​Replace Default Layout

​Remove Components

​Reorder Components

Ways to Customize Layout

Single Component Customization (Targeted)

Full Component Tree Customization (Comprehensive)

Variants

Create Custom Variants

Use Pre-defined Variants

Common Customization Tasks

Replace Default Layout

Remove Components

Reorder Components