API Proposal: Media components (Image, Video, FileDownload)

[javiercn]

Background and Motivation

Blazor has no built-in way to display images, videos, or trigger file downloads from non-HTTP sources (byte arrays, streams, database BLOBs). Developers currently must base64-encode data (causing large string allocations) or create separate HTTP endpoints (which can interfere with authorization). Issue #25274 (20+ upvotes) has requested an Image component since 2020. This feature introduces a suite of media components using streaming JS interop and browser Cache Storage API for efficient data transfer.

PRs #63360 (Image) and #63540 (Media Suite — Video, FileDownload, MediaComponentBase, MediaSource, MediaContext). Related to issue #25274.

Proposed API

namespace Microsoft.AspNetCore.Components.Web.Media;

+ public class MediaSource
+ {
+     public MediaSource(byte[] data, string mimeType, string cacheKey);
+     public MediaSource(Stream stream, string mimeType, string cacheKey);
+     public string CacheKey { get; }
+     public long? Length { get; }
+     public string MimeType { get; }
+     public Stream Stream { get; }
+ }

+ public class MediaContext
+ {
+     public ElementReference Element { get; set; }
+     public bool HasError { get; }
+     public bool IsLoading { get; }
+     public string? ObjectUrl { get; }
+ }

+ public abstract class MediaComponentBase : ComponentBase, IAsyncDisposable
+ {
+     public Dictionary<string, object>? AdditionalAttributes { get; set; }
+     public MediaSource Source { get; set; }
+     public ValueTask DisposeAsync();
+ }

+ public class Image : MediaComponentBase
+ {
+     public RenderFragment<MediaContext>? ChildContent { get; set; }
+ }

+ public class Video : MediaComponentBase
+ {
+     public RenderFragment<MediaContext>? ChildContent { get; set; }
+ }

+ public class FileDownload : ComponentBase
+ {
+     public RenderFragment<FileDownloadContext>? ChildContent { get; set; }
+     public string FileName { get; set; }
+     public string? Text { get; set; }
+ }

+ public class FileDownloadContext
+ {
+     public string FileName { get; }
+     public Task InvokeAsync();
+ }

Usage Examples

Image from byte array:

@using Microsoft.AspNetCore.Components.Web.Media

<Image Source="new MediaSource(photoBytes, "image/jpeg", "photo-42")"
       alt="Product photo" />

Video from stream:

<Video Source="new MediaSource(videoStream, "video/mp4", "product-demo")"
       controls />

File download:

<FileDownload Source="new MediaSource(pdfData, "application/pdf", "report")"
              FileName="annual-report-2025.pdf"
              Text="Download Report" />

Alternative Designs

Base64 encoding (allocates large strings), creating separate HTTP endpoints (interferes with authorization, requires more work). The streaming approach avoids large .NET-side memory allocations and uses browser Cache Storage for repeat loads.

Risks

MediaSource is single-use (one instance per media load). The browser Cache Storage API is used for caching, which has storage limits depending on the browser.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[github-actions]

Triage Summary

Area: area-blazor ✅ (already labeled — proposal introduces new Blazor components: Image, Video, FileDownload, MediaComponentBase, MediaSource, MediaContext in Microsoft.AspNetCore.Components.Web.Media)
Type: api-proposal — formal API addition proposal with a diff-formatted API surface, usage examples, and alternative design discussion; references existing PRs #63360 and #63540

Potential Duplicates

• Blazor Image component to display images that are not accessible through HTTP endpoints #25274 — referenced directly in the issue as the original feature request (Image component, 20+ upvotes since 2020); this issue is the formal API proposal superseding/advancing that request (related, not a duplicate)
• No other duplicates found

Notes

• The issue is filed by a MEMBER and already carries api-ready-for-review, indicating it has been prepared for the API review process.
• Adding api-proposal type label to complete classification.

Generated by Issue Triage Agent for dotnet/aspnetcore for issue #66391 · ● 208.9K · ◷