Image: raster images

Build raster images with Image. This page includes a runnable example, all props, and behavior constraints.

Complete example

Complete environment setup first. Copy this complete main.go and run go run ..

package main

import (
	"fmt"
	"github.com/dxui-org/dxui"
	"image"
	"image/color"
	"log"
)

func main() {
	pixels := image.NewRGBA(image.Rect(0, 0, 64, 64))
	for y := 0; y < 64; y++ {

		for x := 0; x < 64; x++ {
			pixels.SetRGBA(
				x,
				y,
				color.RGBA{
					R: uint8(x * 4),
					G: uint8(y * 4),
					B: 160,
					A: 255,
				},
			)
		}
	}
	source := dxui.ImageFromGo(pixels)
	status := "Loading"
	app := dxui.NewApp(dxui.AppOptions{
		Title:      "Image",
		Width:      640,
		Height:     480,
		Background: dxui.RGBA(248, 250, 252, 255),
	})
	if err := app.Run(func() dxui.View {
		return dxui.Box(
			dxui.BoxProps{
				Gap: 16,
				Style: dxui.Style{
					Padding: dxui.Padding(24),
				},
			},
			dxui.Box(
				dxui.BoxProps{
					Gap: 12,
				},
				dxui.Image(dxui.ImageProps{
					Source: source,
					Fit:    dxui.ImageContain,
					Alignment: dxui.Point{
						X: .5,
						Y: .5,
					},
					MaxPixels: 1024 * 1024,
					Style: dxui.Style{
						Width:  dxui.Px(180),
						Height: dxui.Px(120),
					},
					OnLoad: func(s dxui.Size) {
						status = fmt.Sprint(s)
					},
					OnError: func(err error) {
						status = err.Error()
					},
				}),
				dxui.Label(status),
			),
		)
	}); err != nil {

		log.Fatal(err)
	}
}

Parameters and API

func Image(props ImageProps) View

Field	Type	Purpose, defaults, and constraints
Key	string	Stable unique identity within one parent; empty by default. Use business IDs in dynamic lists, not changing indices.
Style	Style	Local layout, paint, and text styling; zero uses intrinsic sizes and theme defaults.
Token	ComponentToken	Component theme entry; empty selects its default.
States	StateStyles	Paint patches for actual interaction states; cannot fabricate state or change layout.
Pointer	PointerBehavior	Defaults to PointerAuto; PointerNone excludes the entire subtree from pointer participation, unlike Disabled.
Source	ImageSource	Stable image handle; reuse it rather than allocating during every build.
Fit	ImageFit	Defaults to ImageContain; also supports Cover, Fill, and None.
Alignment	Point	X/Y each range from 0 to 1; default (0,0) is top-left, (.5,.5) is centered.
MaxPixels	int64	Decoded pixel budget; 0 selects 16,777,216, and negative values are invalid.
OnLoad	func(Size)	Success notification with decoded size; nil still loads.
OnError	func(error)	Resource error notification; the app may render a fallback. Nil still attempts loading.

Behavior and limitations

Construct Source with ImageBytes, ImageFile, or ImageFromGo and reuse it outside builders. Contain preserves the entire image and aspect ratio; Cover fills and crops; Fill stretches; None keeps original size. Alignment is 0..1 per axis, default top-left. MaxPixels limits decoded pixels. Only PNG/JPEG/first-frame GIF; no network URLs or asynchronous decoding. Nil load callbacks do not prevent decoding. Do not modify a Go image after constructing its source.

All components share identity, style, and pointer rules. See full declarations for referenced enums, structs, and comments. Running examples explains build verification.