# Media Agents: start with [Workspace for Agents](https://workspace.socra.com/solutions/agents.md), the verified steps for getting an identity on a team, with commands, cost and limits. Socra: Fill the roles your team needs with proactive AI teammates, each with its own computer, identity and role. Canonical: https://socra.design/components/media ## Governing rules [Building with Socra components](https://socra.design/agents.md) explains setup, consumption rules and verification. Semantic owner: Flash Module `ui-component-family-media` in Socra Cortex when available. It supplies current intent and prerequisite rules; the public API below supplies exact code names and values. Use published property names, not inspector labels. Composition and preview settings are not component props. Public styling escape hatches do not permit product-local presentation overrides. Images with stable geometry, explicit crop and truthful loading or failure states. Keep media recognizable and surrounding content stable while the source loads, changes or fails. Status: partial. Source implementation and canonical specimen are prepared. Public package adoption and rendered catalog verification are required before release. Library: @socra/web-ui ## Anatomy - Image requires positive intrinsic width and height and either alt or decorative=true. The frame creates no action or tab stop. - Image preserves intrinsic aspect ratio at every width. Cover media uses the shared showcase radius and continuous container corners on desktop and mobile. - Artwork reserves 20:13 at up to 400px, centered within available width. It contains the full scene by default. Decorative artwork is omitted in forced colors. - darkSrc follows the app dark class and the nearest explicit theme scope, not the operating system preference. One accessible image description covers both sources. - placeholderSrc renders a blurred preview of the same source below the full image and is not announced by screen readers. Reduced transparency removes the blur. ## States - **Rest:** The decoded source replaces its preview without changing geometry. - **Hover:** Passive media adds no hover treatment or pointer cursor. - **Focus:** The frame adds no tab stop. Controls placed over media keep their own focus contract. - **Pressed:** Media is not an action and adds no pressed treatment. - **Selected:** Media carries no selection state; a host that makes it selectable owns that state. - **Disabled:** Media has no disabled state. An unavailable source is an Error, not a dimmed image. - **Loading:** Intrinsic dimensions reserve the complete frame; an optional small preview remains beneath native image loading. - **Error:** Missing sources, transfer failures and decoding failures remain distinct, preserve the frame and accessible description, and recover when the host supplies a new source. ## Motion Media changes without decorative animation. Loading, errors, theme changes and reduced motion retain the reserved frame. ## Usage - Choose complete-image containment or an intentional crop. Contain preserves every edge; cover fills the frame while retaining image proportions. - Describe meaningful media; mark redundant artwork decorative. One accessible name serves both theme variants, and forced colors can omit decorative scenes. ## Avoid - Do not recreate the frame in product styles. Shared media owns geometry, corners, placeholder, crop and theme switching. ## Properties [Complete public API, including inherited properties and event signatures](https://socra.design/components/media/api.md) ### Image Import: `import { Image } from '@socra/web-ui/media';` | Property | Type or permitted values | Default / omission | Required | Meaning and behavior | Inspector | | --- | --- | --- | --- | --- | --- | | `alt` | `string \| undefined` | Omitted; no declared default | no | Accessible description. Use decorative for artwork already described by adjacent content. Nondecorative images require a nonblank description; decorative=true supplies empty alternative text. | Direct API | | `darkSrc` | `string \| undefined` | Omitted; no declared default | no | Alternate artwork follows the nearest app theme scope or .dark class, independently of OS preference. Selected by the inherited color mode; source identity changes reset image loading state. | Direct API | | `decoding` | `"auto"`, `"async"`, `"sync"` | `"async"` | no | | Direct API | | `decorative` | `false`, `true` | `false` | no | | Decorative | | `fit` | `"contain"`, `"cover"` | cover for cover presentation, otherwise contain. | no | | Fit | | `height` | `number` | Required input | yes | When supplied, must be positive and finite. | Direct API | | `loading` | `"eager"`, `"lazy"` | `"lazy"` | no | | Direct API | | `placeholderSrc` | `string \| undefined` | Omitted; no declared default | no | Small rendering of the same image, hidden from assistive technology. | Direct API | | `presentation` | `"image"`, `"cover"`, `"artwork"` | `"image"` | no | Image keeps intrinsic geometry. Cover fills a responsive card. Artwork contains a 20:13 scene. | Presentation | | `sizes` | `string \| undefined` | Omitted; no declared default | no | | Direct API | | `src` | `string \| undefined` | Omitted; no declared default | no | | Direct API | | `srcSet` | `string \| undefined` | Omitted; no declared default | no | | Direct API | | `width` | `number` | Required input | yes | Intrinsic dimensions, always positive; reserve geometry before loading. When supplied, must be positive and finite. | Direct API | ### Inspector mappings | Setting | Initial preview value | Consumed code | | --- | --- | --- | | Presentation | `image` | Image.presentation | | Fit | `contain` | Image.fit | | Source | `available` | composition: Supplies an available fixture src, omits src, or uses a failing URL to exercise resource states. | | Placeholder | `true` | composition: Includes or omits placeholderSrc. | | Dark artwork | `false` | composition: Includes darkSrc alongside src so the component resolves the current color mode. | | Decorative | `false` | Image.decorative | ## Example ```tsx import { Image } from '@socra/web-ui/media'; // The host supplies its image URL and intrinsic dimensions. export function MediaExample({src}: {src: string}) { return Project overview; } ```