Display@knitui/components

Image

Cross-platform Image backed by expo-image on web, iOS, and Android. It accepts src (preferred), the deprecated source prop, and optional fallbackSrc for graceful error handling. The fit prop maps to expo-image's contentFit (CSS object-fit values); objectPosition maps to contentPosition; radius applies a border-radius token or CSS value. The full expo-image surface is also exposed: transition, placeholder, blurRadius, tintColor, priority, cachePolicy, recyclingKey, and more.

WebiOSAndroid5 style slots9 own props19 examples

Stories Source Tests Open in Storybook

import { Image } from "@knitui/components";

Playground

Loading playground…

srcImage URL or require() result.

altAccessible alternative text.

fitCSS object-fit value. Defaults to "cover".

radiusBorder-radius — a theme token key or any valid CSS value.

fallbackSrcURL shown when the primary source fails to load.

width

height

transitionexpo-image cross-fade duration in ms (or an ImageTransition object).

blurRadiusexpo-image blur effect radius in points.

tintColorexpo-image template tint color.

priorityexpo-image load priority.

cachePolicyexpo-image cache strategy.

Playground

<Image
  src="https://picsum.photos/seed/knitui/400/300"
  alt="Sample image"
  width={400}
  height={300}
  fit="cover"
/>

Examples

Fit Modes

All object-fit values side by side; each image is constrained to the same box.

Loading example…

Fit ModesSource Storybook

Radius

Border-radius applied via a raw CSS value — from sharp to fully rounded.

Loading example…

RadiusSource Storybook

Fallback

When the primary src is broken, the image automatically shows fallbackSrc.

Loading example…

FallbackSource Storybook

No Source

No src and no fallbackSrc — demonstrates empty / missing image handling.

Loading example…

No SourceSource Storybook

Wide aspect ratio constrained to a fixed height — useful for banners.

Loading example…

BannerSource Storybook

Avatar

Square thumbnail with a circular radius — common for avatars.

Loading example…

AvatarSource Storybook

Deprecated Source

Demonstrates the deprecated source prop still resolves correctly.

Loading example…

Deprecated SourceSource Storybook

Transition

expo-image cross-fades the image in once it loads. transition accepts a duration in ms (shown) or a full ImageTransition object ({ duration, effect, timing }).

Loading example…

TransitionSource Storybook

Placeholder

A blurhash placeholder is shown while the full image loads, avoiding layout shift and blank space. placeholder also accepts a thumbhash or a low-res source.

Loading example…

PlaceholderSource Storybook

Blurred

blurRadius applies a native blur to the rendered image.

Loading example…

BlurredSource Storybook

Object Position

objectPosition (expo-image's contentPosition) controls how the image is aligned within its frame when it overflows.

Loading example…

Object PositionSource Storybook

Radius Tokens

radius accepts the theme radius tokens (xxs–xxl) in addition to raw CSS values. The image is clipped to the rounded frame on web and native alike.

Loading example…

Radius TokensSource Storybook

Tinted

tintColor recolors the image — useful for monochrome icons/templates. It maps to expo-image's tintColor on native and an SVG color filter on web.

Loading example…

TintedSource Storybook

Content Position Object

objectPosition (→ contentPosition) also accepts the object form with point/percent offsets from any edge.

Loading example…

Content Position ObjectSource Storybook

Priorities

priority hints how urgently the image should load (low | normal | high). On web it sets fetchpriority on the underlying <img>.

Loading example…

PrioritiesSource Storybook

Shadows

The inherited shadow elevation prop, from xs to xl.

Loading example…

ShadowsSource Storybook

Styles

Per-slot styles targets individual parts — here the root frame and image.

Loading example…

StylesSource Storybook

Showcase

A feature showcase: rounded, animated cross-fade in, with a blurhash placeholder, memory-disk caching, and a recycling key.

Loading example…

ShowcaseSource Storybook

Props

Prop	Type	Default	Description
`disabled` system	`boolean \| undefined`	—
`fallbackProps`	`Partial<ImageProps> \| undefined`	—	Props spread onto the backing image (alias for `styles.image`).
`fallbackSrc`	`string \| undefined`	—	URL shown when the primary source fails to load.
`fit`	`ImageObjectFit \| undefined` cover · contain · fill · none · scale-down	`"cover"`	CSS object-fit value. Defaults to "cover".
`objectPosition`	`ImageObjectPosition \| undefined`	—	Alias for `contentPosition`.
`onError`	`((event: ImageErrorEvent) => void) \| undefined`	—
`onLoad`	`((event: ImageLoadEvent) => void) \| undefined`	—
`radius` system	`string \| number \| undefined`	—	Border-radius — a theme token key or any valid CSS value.
`resizeMode`	`ImageHostResizeMode \| undefined`	—	Deprecated — use fit instead.
`source`	`ImageSrc \| undefined`	—	Deprecated — use src instead.
`src`	`ImageSrc \| undefined`	`https://picsum.photos/seed/knitui/400/300`	Image URL or require() result.
`styles` system	`SlotStyles<ImageStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching part.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element

Style slots

Every part of Image can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`fallback`	`styles={{ fallback: { … } }}`
`image`	`styles={{ image: { … } }}`
`overlay`	`styles={{ overlay: { … } }}`
`placeholder`	`styles={{ placeholder: { … } }}`
`root`	`styles={{ root: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<unknown> \| undefined`

Plus 519 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.