Display@knitui/components

BackgroundImage

BackgroundImage renders content over a cover-positioned image. The image is a real Image element layered behind children, so it renders identically on web and native. src sets the image URL, resizeMode controls how it fills the frame, and radius clips the corners. The full Box style surface is available for sizing.

WebiOSAndroid2 style slots5 own props9 examples

Stories Source Tests Open in Storybook

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

Playground

Loading playground…

srcImage URL rendered behind the content.

resizeModeHow the image fills the frame.

radiusCorner radius token — clips the image to the frame.

shadowElevation — drop shadow from the shared ladder.

Playground

<BackgroundImage
  src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80"
  resizeMode="cover"
  width={400}
  height={200}
/>

Examples

With Overlay

Default cover fit with a text overlay centered in the frame.

Loading example…

With OverlaySource Storybook

Resize Modes

All five resize modes side by side — shows how the image fills each frame.

Loading example…

Resize ModesSource Storybook

Rounded

Rounded corners via the radius token — clipped by overflow hidden.

Loading example…

RoundedSource Storybook

Radius Scale

Sweep of all radius values showing how corners are clipped.

Loading example…

Radius ScaleSource Storybook

Shadows

Sweep of all shadow levels showing the elevation ladder behind the image frame.

Loading example…

ShadowsSource Storybook

Fixed Size

Fixed dimensions — explicit width and height constrain the image frame.

Loading example…

Fixed SizeSource Storybook

Full Width Banner

Full-width banner — stretches to fill the container width.

Loading example…

Full Width BannerSource Storybook

Styles

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

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`src` required	`string`	`https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80`	Image URL rendered behind the content.
`disabled` system	`boolean \| undefined`	—
`fit`	`ImageObjectFit \| undefined`	`'cover'`	How the image fills the frame — a CSS `object-fit` value forwarded to the inner `Image`'s `fit`.
`imageProps`	`Partial<ImageProps> \| undefined`	—	Props spread onto the layered backing `<Image>`, making the previously opaque inner image reachable (e.g. `transition`, `placeholder`, `radius`). Engine-owned props (`src`/`fit`/`objectPosition`/`resizeMode`/positioning) still win. Alias for `styles.image`.
`objectPosition`	`ImageObjectPosition \| undefined`	—	How the image is aligned within the frame when it overflows — a CSS `object-position` value (keyword, `"x y"`, or `{ top, left, … }`) forwarded to the inner `Image`. Honored on web and native alike.
`radius` system	`string \| number \| undefined` unset · xs · sm · md · lg · xl	—	Corner radius token — clips the image to the frame.
`resizeMode`	`BackgroundImageResizeMode \| undefined` cover · contain · stretch · center · repeat	`cover`	How the image fills the frame.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` unset · xs · sm · md · lg · xl	—	Elevation — drop shadow from the shared ladder.
`styles` system	`SlotStyles<BackgroundImageStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching part (`root`/`image`).
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element

Style slots

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

Slot	Usage
`image`	`styles={{ image: { … } }}`
`root`	`styles={{ root: { … } }}`

Accessibility & DOM props (2)

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

Plus 498 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.