Skip to content
Proto UI

Search

Loading search…
Toggle theme

Image

Host-owned image presentation with explicit accessibility and loading status

base-image-root is a draft Base prototype available in the 0.3.0-alpha.0 package line. It declares one host-owned image target and exposes its source, fit, and loading status. Web Components, React, Vue 3, and Vue 2 currently project it to one physical <img> per instance. These previews prove a bounded Web profile, not non-Web host support.

选择适配器 Web Components React Vue Vue 2

The three upper frames use the same image and size to compare contain, cover, and fill across four Web adapters. The small illustration is decorative. The lower image starts without a source: load, replace, break, or clear its source to inspect real loadingStatusChange events. A cached or local image may finish loading too quickly to see the intermediate state; the transition log retains it. The controls, frame sizes, and log belong to this demo, not to Base Image.

Use Image

Section titled “Use Image”

Import the real prototype and adapt it in the host application:

import * as React from 'react';
import { createReactAdapter } from '@proto.ui/adapter-react';
import { imageRoot } from '@proto.ui/prototypes-base/image';


const Image = createReactAdapter(React)(imageRoot);


export function Cover() {
  return (
    <Image
      source="/images/cover.jpg"
      a11yMode="informative"
      alternativeText="A mountain ridge reflected in a lake"
      fit="cover"
      surfaceStyle={{ width: '100%', height: '240px' }}
    />
  );
}

Vue 3 uses createVueAdapter(Vue)(imageRoot) and Vue 2 uses createVue2Adapter({ extend: Vue.extend.bind(Vue), nextTick: Vue.nextTick.bind(Vue), set: Vue.set.bind(Vue) })(imageRoot). Web Components use AdaptToWebComponent(imageRoot, { registerAs: 'app-image' }); set the declared props with setElementProps() before mounting. Use matching exact package versions throughout the application.

The workspace CLI registers base-image for react, vue, vue2, and wc, generating BaseImageRoot or BaseImageRootElement. A build containing the entry supports proto-ui add react base-image and the corresponding vue / vue2 / wc commands.

Historical release boundary: the published 0.3.0-alpha.0 prerelease contains the direct Image exports shown above, but its CLI predates the base-image registry entry. Image is outside the stable 0.2.0 surface.

Props and Exposes

Section titled “Props and Exposes”
PropMeaning
sourceOpaque URI string. Omitted or empty means idle. Synchronizing the same URI does not restart a settled request.
a11yModeChoose informative or decorative explicitly. The default is informative, which still requires non-empty alternative text.
alternativeTextRequired non-empty text for an informative image. Decorative input must omit it or use an empty string.
fitcontain (default), cover, or fill, centered in the consumer-sized frame.

An informative image receives its alternative text on the physical target. A decorative image has empty alt and contributes no image name to the accessibility tree. Contradictory or incomplete accessibility input is rejected; Base Image does not invent a label from the URI.

The exposed states are source, fit, and loadingStatus. The only outward transition event is loadingStatusChange:

{ status, previousStatus, source }

Status is idle | loading | loaded | error. A changed non-empty source enters loading before host work; its current request can settle as loaded or error. Replacing a source clears the previous visual and retires its pending completion. Clearing the source returns to idle. Native events and host error objects are not part of the payload.

The current Web profile uses a displayable synchronous cache hit or that source request’s HTMLImageElement.decode() settlement. This is a Web readiness mapping, not a promise that every host uses the same decoder API. A failed source has no built-in retry button or fallback content; the application chooses what to display around it.

Compose and Style

Section titled “Compose and Style”

Root has no authored children. The application supplies dimensions, framing, and any adjacent caption or status display; fit describes how the image fills that physical frame. Web Components retain a custom-element boundary with one inner image; surfaceClassName and surfaceStyle target the image. React, Vue 3, and Vue 2 use the physical image as their root.

A prototype reusing the authored hook must also reuse its frozen static requirements so the Adapter can select the image target before setup:

import { definePrototype } from '@proto.ui/core';
import { asImageRoot } from '@proto.ui/prototypes-base/image';


const framedImage = definePrototype({
  name: 'framed-image',
  modules: asImageRoot.modules,
  setup() {
    asImageRoot();
  },
});

Base Image does not own Avatar fallback, upload, cropping, zoom, gallery navigation, responsive srcset, caching policy, or live announcements. An image used inside a Button or Link does not become an independent control; the surrounding control owns activation and its functional name.

References

Section titled “References”