> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://documentation.celestory.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🟦 Background image

# 🟦 Background image

${frame}[Video: anatomy of the Background image block](https://celestory-docs-videos.netlify.app/en/anatomie-bloc/createbackgroundimage.html)

![Background image](https://celestory-docs-illustrations.netlify.app/en/Backgroundimage_EN.svg)

The Background Image block lets you prepare an image to be used as a background: how it should fit the screen, whether it repeats as a pattern, and where it sits.

This block does not display anything on screen by itself: it produces a ready-to-use configuration, which you then plug into the Switch Background block, which handles the transition animation (fade, zoom, duration...) and the actual display.

## 📥 Inputs

- image (Image): The image to use as a background.
- size (Choice): How the image fits the screen (options: Contain, Auto, Cover - default Cover).
- color (Color): Color visible around the image when it does not cover the whole screen.
- repeat (Choice): Whether and how the image repeats as a pattern (options: repeat-x, repeat-y, space, no-repeat, round - default no-repeat, meaning no repetition).
- positionX (Number + CSS unit): Horizontal position of the image within its frame.
- positionY (Number + CSS unit): Vertical position of the image within its frame.

## 📤 Outputs

- backgroundImage (Background image Object): The background configuration, ready to be plugged into the background input of a Switch Background block.

## 💡 Example of use

Scenario: Preparing a starry sky for a night scene

1. The designer wants a starry sky as the background of a night scene.
1. A Background Image block is added to the canvas and configured with:

- image: a photo of a starry sky
- size: Cover (to fill the whole screen)
- repeat: no-repeat (the image does not repeat)

1. Its backgroundImage output is plugged into the background input of a Switch Background block.
1. The Switch Background block then displays this backdrop on screen with an animated transition (fade, duration, etc.).

## ⚙️ Technical Details

- Value block, not a flow block: this block has no stream input or output (in/out). It doesn't sit directly in the course of the story; it plugs into the input of another block (Switch Background) which handles the actual display and animation.
- Compatibility: Works with all standard image formats (JPG, PNG, SVG) and adapts to different screen resolutions.

---

*Documented version: v1*