BnImage

Namespace: BlazorNative.Components

An image loaded from a URL. Renders as a native ImageView on Android and a UIImageView on iOS. The platform fetches, decodes and measures the bytes — your code only names the source. The rest of its surface is BnView's flex item surface (BnImage.Grow, BnImage.Shrink, BnImage.Basis, BnImage.AlignSelf, the box, BnImage.Margin, BnImage.Position).

public sealed class BnImage : Microsoft.AspNetCore.Components.ComponentBase, Microsoft.AspNetCore.Components.IComponent, Microsoft.AspNetCore.Components.IHandleEvent, Microsoft.AspNetCore.Components.IHandleAfterRender

Inheritance Object → ComponentBase → BnImage
Implements IComponent, IHandleEvent, IHandleAfterRender
Attributes NullableContextAttribute, NullableAttribute

Remarks:

Sizing is the decision this component's shape makes. Set BnImage.WidthandBnImage.Height and the frame is exactly those numbers, always — the bytes never move it, so nothing below it ever reflows. Set NEITHER and the image is intrinsic: it measures 0 × 0 until its bytes arrive and its natural pixel size (in dp or pt) afterwards, at which point the layout re-solves and its siblings below move down. Exactly one reflow, never two.

On failure the node stays 0 × 0: it reserves no space, and it does not retry. Changing BnImage.Src, or removing the image, cancels the in-flight request, so a late arrival can never paint into something you have replaced. Setting to null clears the image and re-solves: an intrinsic image collapses back to 0 × 0 and its siblings move back up. That is the same reflow in the other direction, and it is part of the contract rather than an accident.

Not a flex container, and not a container at all. There is no Direction, Justify, Align, Wrap, Gap, Padding — and no ChildContent. An image is a leaf: it has no Yoga children for any of them to arrange. To overlay content on an image, compose (a BnView parent with an absolutely positioned child).

Nothing else here changes the sizing rules above.BnImage.PlaceholderColor never measures, BnImage.OnError never changes measurement, and BnImage.ContentMode is paint-only. Whatever you set among those three, the frame is the one the two paragraphs above describe.

Properties

Src

The image URL. The platform fetches it — you cannot hand this component bytes.

Null = no source: nothing is fetched, and the node keeps measuring 0 × 0 unless BnImage.Width and BnImage.Height say otherwise. Changing it cancels any request still in flight for this image.

Setting it back to null is a real change, not a no-op: the image is cleared, and an intrinsic node collapses to 0 × 0 so its siblings move back up.

public string? Src { get; set; }

Property Value

String

PlaceholderColor

A colour to paint while the image is loading — a hex string, not content and not a second image. It stays as the visible state if the load fails, and is cleared once the real bytes paint. Null = no placeholder.

It never measures and never reflows: it paints inside whatever box the layout already gave the node. That means an intrinsic image's placeholder is invisible — a 0 × 0 box paints nothing — so give the image a size if you want a placeholder to show. Letterbox bars show BnImage.BackgroundColor, never this.

public string? PlaceholderColor { get; set; }

Property Value

String

ContentMode

How the pixels are painted inside the box the layout gave this image. Paint-only: the mode never changes measurement, so every frame is identical under all four modes and the paint never escapes the box — both platforms clip it.

Null leaves the platform default, which is Contain (aspect-fit). Clearing the parameter restores that default. See ImageContentMode for the four modes.

public ImageContentMode? ContentMode { get; set; }

Property Value

ImageContentMode?

OnError

Raised when the image fails to load. The arguments carry the failed URL and nothing else. Optional: nothing is attached to the native control unless you supply a handler.

Failure never changes measurement: a declared box keeps its size, an intrinsic node stays 0 × 0. The platform will not substitute anything of its own — a fallback is whatever you render from this handler (swap the BnImage.Src, unmount the image, show a message).

It fires at most once per request, and only for the request that is still current: cancelling — changing BnImage.Src, setting it to null, or removing the image — is not a failure and raises nothing. There is no matching success event.

public EventCallback<BnImageErrorEventArgs> OnError { get; set; }

Property Value

EventCallback<BnImageErrorEventArgs>

BackgroundColor

Background color as a hex string, e.g. "#FFEEAA". Null leaves the view transparent.

public string? BackgroundColor { get; set; }

Property Value

String

Margin

Outside spacing, e.g. "8" — space between this view's box and its siblings. Null = none.

public string? Margin { get; set; }

Property Value

String

AlignSelf

Cross-axis override for this item (alignSelf). Null = auto (inherit the parent's BnView.Align).

public FlexAlign? AlignSelf { get; set; }

Property Value

FlexAlign?

Grow

Share of the free main-axis space this item absorbs (flexGrow) — a UNITLESS number, not a length. Null = 0.

public float? Grow { get; set; }

Property Value

Single?

Shrink

Share of the main-axis overflow this item gives back (flexShrink) — a UNITLESS number. Null = Yoga's default.

public float? Shrink { get; set; }

Property Value

Single?

Basis

Main-axis base size (flexBasis): "auto" | "50%" | "120". Null = auto.

public string? Basis { get; set; }

Property Value

String

Width

Declared width, e.g. "200". Null = auto. Set it together withBnImage.Height and the image is sized IMMEDIATELY — its frame never moves when the bytes land; set NEITHER and the image is intrinsic: 0 × 0 until the bytes, its natural size after (see the class remarks).

public string? Width { get; set; }

Property Value

String

Height

Declared height, e.g. "120". Null = auto. The sizing rule is BnImage.Width's and is stated there: BOTH set → definite, never measured; NEITHER set → intrinsic.

public string? Height { get; set; }

Property Value

String

MinWidth

Minimum width. Null = unset.

public string? MinWidth { get; set; }

Property Value

String

MaxWidth

Maximum width. Null = unset.

public string? MaxWidth { get; set; }

Property Value

String

MinHeight

Minimum height. Null = unset.

public string? MinHeight { get; set; }

Property Value

String

MaxHeight

Maximum height. Null = unset.

public string? MaxHeight { get; set; }

Property Value

String

Position

Positioning mode (position). Null = relative (in flow).

public FlexPosition? Position { get; set; }

Property Value

FlexPosition?

Top

Top inset. Null = unset.

public string? Top { get; set; }

Property Value

String

Right

Right inset. Null = unset.

public string? Right { get; set; }

Property Value

String

Bottom

Bottom inset. Null = unset.

public string? Bottom { get; set; }

Property Value

String

Left

Left inset. Null = unset.

public string? Left { get; set; }

Property Value

String

Constructors

BnImage()

public BnImage()