[dev-v5] FluentOverflow MaxRenderedItems does not limit rendered child elements

[JamesNK]

Summary

Issue #4949 requested a MaxRenderedItems option that prevents large FluentOverflow collections from rendering every item into the browser DOM. It was closed as completed by #4961.

The v5 implementation does not currently enforce the limit during Blazor rendering. It renders @ChildContent unconditionally and passes MaxRenderedItems to the web component. TypeScript then uses the value only when building the overflow-item collection returned to Blazor.

As a result, MaxRenderedItems limits ItemsOverflow and the JS-to-.NET event payload, but all child components are still rendered by Blazor, sent to the browser, inserted into the DOM, and measured by JavaScript.

Current behavior

FluentOverflow.razor renders the complete fragment:

@ChildContent

The TypeScript implementation discovers and measures every matching child:

const allItems = Array.from(container.querySelectorAll<OverflowElement>(localQuerySelector));

MaxRenderedItems is applied later, while constructing the returned overflow records:

if (!unlimited && overflowItems.length >= maxRenderedItems) {
  break;
}

For example, rendering 500 items with MaxRenderedItems="20" still creates and measures 500 DOM elements. Only the ItemsOverflow payload is capped at 20.

This leaves the performance problem from #4949 unresolved. In Blazor Server, a sufficiently expensive layout can stop the client from processing render updates until SignalR backpressure terminates the connection.

Expected behavior

There should be an opt-in way to:

1. Limit how many overflow-managed items Blazor renders and sends to the browser.
2. Treat items beyond that limit as pre-overflowed.
3. Include pre-overflowed items in the total overflow count.
4. Make the underlying data for pre-overflowed items available to the overflow template.
5. Preserve the current unlimited ChildContent behavior by default.

API constraint

The existing ChildContent parameter is an opaque RenderFragment. FluentOverflow cannot enumerate it, associate rendered nodes with source values, or apply Take(MaxRenderedItems) to it. Limiting the fragment itself would also lose the omitted item data and produce an incorrect overflow count.

Possible improvement

Add a data-driven, strongly typed overflow API, either on a generic component or a companion component. For example:

<FluentOverflow TItem="ResourceUrl"
                Items="@urls"
                MaxRenderedItems="20">
    <ItemTemplate Context="url">
        <FluentBadge>@url.DisplayName</FluentBadge>
    </ItemTemplate>
    <OverflowTemplate Context="overflow">
        @foreach (var url in overflow.Items)
        {
            <FluentBadge>@url.DisplayName</FluentBadge>
        }
    </OverflowTemplate>
</FluentOverflow>

With this model, Blazor can render only the first 20 item templates for browser measurement and retain the remaining source items as pre-overflowed data. The existing direct ChildContent API can remain available for arbitrary markup, with its current payload-only semantics documented explicitly.

The exact API shape is open for discussion. Another option is a dedicated virtualized/data-bound overflow component so MaxRenderedItems does not have two different meanings.

Acceptance criteria

• Given 100 data-bound items and a DOM render limit of 10, no more than 10 managed item elements are initially rendered, excluding fixed framework elements such as the More button.
• OverflowCount includes both measured overflow items and the 90 items omitted from the DOM.
• The overflow template can render or otherwise access the omitted item data.
• Resizing continues to recalculate overflow among the rendered measurement set.
• Existing ChildContent usage remains backward compatible.
• Documentation clearly distinguishes the DOM render limit from the JS-to-.NET payload limit.

[dvoituron]

I think there are two ways to meet this requirement (both are useful, I believe)

1. This is to add a DeferredLoading parameter (as we have for FluentTabs or FluentWizard)
   Once this parameter is enabled, the overflow section is only rendered when it is visible on the screen.
   Example:

peek_1.mp4

2. Create another component, FluentOverflowList, which contains an Items parameter and is strongly typed as TItem, as shown in your example.

[JamesNK]

I think FluentOverflow should move to a strongly typed, data-driven rendering model. We can change the component API as needed; preserving the current opaque ChildContent behavior is not a requirement.

Default overflow UI

As with Virtualize, the typed ChildContent is the default item template. With no OverflowTemplate, the component displays everything that overflows as text in its default tooltip:

<FluentOverflow TItem="string"
                Items="@Names"
                MaxRenderedItems="20"
                Context="name">
    <FluentBadge>@name</FluentBadge>
</FluentOverflow>

MaxRenderedItems would have one unambiguous meaning: the maximum number of source items initially rendered into the overflow measurement container. Items beyond that limit are treated as pre-overflowed without being rendered or measured.

For 1,000 items, MaxRenderedItems="20", and enough room for 5 items:

• Blazor initially renders only the first 20 items.
• JavaScript measures those 20 and reports that 5 fit (ideally just a layout boundary such as FirstOverflowIndex/VisibleItemCount, rather than sending item text back to .NET).
• The component derives the overflow collection from its source data as Items.Skip(5).
• 5 measured items remain visible.
• 15 measured items are hidden as overflow.
• 980 items are never part of the initial render or measurement.
• OverflowCount and OverflowTemplate.Items contain all 995 overflow items.

If all 20 rendered items fit, the remaining 980 are still pre-overflowed. In other words, the value is a hard rendering ceiling, not a batch size.

Deferred popup

I don't think a DeferredLoading parameter is needed. OverflowTemplate should own the presentation and lifetime of the extra content. A consumer that wants lazy rendering can put a button and conditional popup inside the templates, so the popup and its item components are not created until the button is clicked:

<FluentOverflow TItem="Resource"
                Items="@Resources"
                MaxRenderedItems="20">
    <ChildContent Context="item">
        <FluentBadge>@item.Name</FluentBadge>
    </ChildContent>

    <MoreTemplate Context="overflow">
        <FluentButton @onclick="OpenOverflow">
            +@overflow.OverflowCount
        </FluentButton>
    </MoreTemplate>

    <OverflowTemplate Context="overflow">
        @if (_overflowOpened)
        {
            <FluentPopover AnchorId="@overflow.IdMoreButton"
                           @bind-Opened="_overflowOpened">
                @foreach (var item in overflow.Items)
                {
                    <FluentBadge>@item.Name</FluentBadge>
                }
            </FluentPopover>
        }
    </OverflowTemplate>
</FluentOverflow>

@code {
    private bool _overflowOpened;

    private void OpenOverflow() => _overflowOpened = true;
}

A consumer can similarly put Virtualize, pagination, or search inside OverflowTemplate if appropriate. FluentOverflow itself should not require an item size or virtualize the popup.

This keeps the component focused on bounded initial rendering, browser measurement, and exposing the complete strongly typed overflow collection. Popup behavior remains template-owned.