Background Image
Utilities for controlling background images, sizing, positioning, and repeat behaviour.
On this page
backgrounds/image
A live demo of this example follows.
image.dart
View source
Open demo
WDiv(
className: 'bg-[url(images/hero.png)] bg-cover bg-center h-64 w-full rounded-lg',
child: WText('Hero Section', className: 'text-white font-bold'),
)
Basic Usage#
Setting a Background Image#
Use the bg-[url(...)] utility to set a background image. Wind supports asset paths and absolute file paths. An absolute file path (a /path value) loads a FileImage, so it works only on platforms with dart:io file support: on web and WASM it produces no background image.
// Asset image (shorthand for assets/)
WDiv(className: 'bg-[url(images/hero.png)]')
// Asset with explicit prefixes
WDiv(className: 'bg-[url(~/images/hero.png)]') // Resolves to assets/images/hero.png
WDiv(className: 'bg-[url(@/images/hero.png)]') // Resolves to assets/images/hero.png
Quick Reference#
| Class | Description | Flutter Equivalent |
|---|---|---|
bg-[url(...)] |
Sets the background image | DecorationImage(image: ...) |
bg-cover |
Scales image to cover container | fit: BoxFit.cover |
bg-contain |
Scales image to fit container | fit: BoxFit.contain |
bg-center |
Centres the image | alignment: Alignment.center |
bg-top |
Aligns image to top | alignment: Alignment.topCenter |
bg-bottom |
Aligns image to bottom | alignment: Alignment.bottomCenter |
bg-left |
Aligns image to left | alignment: Alignment.centerLeft |
bg-right |
Aligns image to right | alignment: Alignment.centerRight |
bg-no-repeat |
Prevents image repetition | repeat: ImageRepeat.noRepeat |
Variants#
Size#
Control how the background image fills its container using bg-cover or bg-contain.
WDiv(className: 'bg-[url(...)] bg-cover') // Scale to cover (may crop)
WDiv(className: 'bg-[url(...)] bg-contain') // Scale to fit (may have gaps)
Position#
Control the position of the background image using bg-{side} utilities.
WDiv(className: 'bg-[url(...)] bg-center') // Center
WDiv(className: 'bg-[url(...)] bg-top-left') // Top Left
WDiv(className: 'bg-[url(...)] bg-bottom') // Bottom Center
Supported values: top, bottom, left, right, center, top-left, top-right, bottom-left, bottom-right.
Repeat#
Control how the background image repeats.
WDiv(className: 'bg-[url(...)] bg-no-repeat') // Default
WDiv(className: 'bg-[url(...)] bg-repeat') // Tile horizontally and vertically
WDiv(className: 'bg-[url(...)] bg-repeat-x') // Tile horizontally
WDiv(className: 'bg-[url(...)] bg-repeat-y') // Tile vertically
Responsive Design#
Prefix any background utility with a breakpoint modifier to apply it at specific screen sizes.
WDiv(
// Mobile: Cover
// Desktop: Contain
className: 'bg-[url(...)] bg-cover lg:bg-contain'
)
Dark Mode#
Use the dark: prefix to change the background image in dark mode.
WDiv(
className: 'bg-[url(bg-light.png)] dark:bg-[url(bg-dark.png)]'
)
Arbitrary Values#
The bg-[...] syntax allows you to pass any string value.
// Standard URL syntax
WDiv(className: 'bg-[url(images/hero.png)]')
// Direct path syntax (also supported)
// An absolute path loads a FileImage: native platforms only, no background on web or WASM
WDiv(className: 'bg-[/path/to/local/file.png]')
Customizing Theme#
Background images are typically dynamic and not defined in the theme. However, the parser handles bg-* classes for colours as well. If you need to customise background colours, see the Background Colour documentation.
For images, Wind uses standard Flutter ImageProvider implementations based on the URL format:
- URLs starting with
/becomeFileImage - All others become
AssetImage(prefixed withassets/unless using~/or@/)
A URL containing : (http://, https://) cannot sit in a className: the prefix resolver splits on : and drops the token. For a network image, stack a WImage(src: ...) under the content.