Skip to content

Images and media

Images, videos, and embedded content make pages engaging and informative.

Silex provides blocks for images, videos, and embedded content (maps, widgets, iframes). Once added, media behaves like any other element — it has a box with dimensions, padding, margins, and borders. What makes media special is how its content fits inside that box.

Key mental model: A media element is a box, and the media fills that box according to rules you set. The box size comes from width/height properties. How the media fits inside comes from Object-Fit and Object-Position.

Adding images

To add an image:

  1. Drag the Image block from the Blocks panel onto the canvas
  2. Silex places an img element with a placeholder
  3. Select the image
  4. In the Element settings (gear icon) on the right, find the src field (labeled "Image URL")
  5. Either:
  6. Enter a URL directly (e.g., https://example.com/photo.jpg)
  7. Click the Asset Manager icon to upload and browse files

Asset Manager: uploading images

The Asset Manager is a media library for your project. When you upload an image, Silex stores it according to your hosting configuration. You can reuse images across pages — upload once, use many times.

To upload:

  1. Double-click an image element, or click the Asset Manager icon in the src field
  2. Click Upload or drag files into the manager
  3. Select the image you want to use
  4. It appears on your canvas and the src field fills automatically

Supported formats: - JPEG — best for photographs, high compression - PNG — good for graphics, transparent backgrounds - WebP — modern format, excellent compression for all types - SVG — vector graphics, scales perfectly to any size - GIF — simple animations

Use JPEG or WebP for photos, PNG for icons/graphics with transparency, SVG for logos/illustrations that need to scale.

Alt text: crucial for accessibility

Every image needs alt text. Alt text is read by screen readers for blind or low-vision visitors, shown when the image fails to load, and indexed by search engines.

To set alt text:

  1. Select the image
  2. In the Element settings (gear icon), find the alt attribute field
  3. Write a short, descriptive phrase describing what the image shows

Good alt text: "Two people collaborating at a desk with laptops" Bad alt text: "image", "photo", or empty

For decorative images (background textures, borders, dividers) that don't add information, set alt text to empty. This tells screen readers to skip them.

Alt text best practices: - Describe the image's content, not "picture of" or "image of" - Keep it under 125 characters — short but specific - Don't include "image of" or "a photo of" - Include relevant text visible in the image (signs, captions, text overlays)

Adding videos

To add a self-hosted video:

  1. Drag the Video block from the Blocks panel
  2. Silex creates a <video> element
  3. Select the video
  4. In the Element settings (gear icon), set the source URL (or use Asset Manager to upload)
  5. Configure options:
  6. autoplay — start playing automatically
  7. controls — show play/pause buttons
  8. loop — restart when finished
  9. muted — required for autoplay in many browsers

For YouTube, Vimeo, or other hosted video services:

Don't use the Video block. Instead:

  1. Drag the Map block (despite its name, it creates an iframe for any embedded content)
  2. Paste the embed code from the video service
  3. Or use the Custom code block for full HTML control

Embedded content (maps, widgets, social posts)

The Map block creates an <iframe> element. Despite its name, you can embed any third-party content:

  • Google Maps
  • Calendars
  • Social media posts
  • Surveys
  • Chat widgets
  • YouTube/Vimeo videos

To add embedded content:

  1. Drag the Map block from the Blocks panel
  2. Select it and look for the src field in the Element settings (gear icon)
  3. Paste the embed URL or iframe code

For full control, use the Custom code block instead. It lets you paste any HTML snippet, including JavaScript.

Audio players

Drag the Audio block (listed as a media element) to embed an audio player. Set the source URL in the Element settings (gear icon). Common uses: podcasts, music, sound effects.

Canvas and other replaced elements

The Canvas block creates a <canvas> element for drawings created with JavaScript. Most designers won't use this — it's for advanced scripting. The Object-Fit and Object-Position properties below also apply to canvas elements.

Controlling how media fits its box

When a media element's box and its content have different aspect ratios, CSS controls what happens: stretch the content, crop it, or letterbox it. This is where Object-Fit comes in.

Object-Fit

Object-Fit determines how media fills its box.

To set object-fit:

  1. Select an image, video, audio, iframe, embed, or canvas element
  2. Open the Object section in the Style panel (appears only for these elements)
  3. Choose an object-fit value

Available values:

Value Effect
fill Stretch/squeeze the media to fill the box completely. May distort aspect ratio.
contain Scale the media to fit inside the box without cropping. Letterbox if aspect ratios don't match.
cover Scale the media to cover the entire box. May crop parts. Usually best for backgrounds.
none Display the media at its natural size. May overflow or leave empty space.
scale-down Use the smaller of none or contain.

Examples:

  • cover on a hero image: fills the space, crops top/bottom if needed
  • contain on a product photo: shows the whole product without distortion
  • fill on a video background: stretches to fill, may distort
  • none on an icon: displays at exact size, no scaling

Object-Position

Object-Position controls where the media is positioned inside its box when it doesn't fill it exactly (when using contain, scale-down, or none).

Available positions (preset options):

Position Effect
left top Align to top-left corner
left center Align to left edge, vertically centered
left bottom Align to bottom-left corner
center top Horizontally centered, top edge
center center Centered both ways (default)
center bottom Horizontally centered, bottom edge
right top Align to top-right corner
right center Align to right edge, vertically centered
right bottom Align to bottom-right corner

Example: an image with object-fit: cover and object-position: center top crops the bottom and sides while preserving the top (good for photos where the important content is at the top).

You want three images side by side, each 200px wide, that scale down on mobile.

  1. Create the gallery container:
  2. Add a Div, set tag to section
  3. Set Display to Flex, Flex-wrap to wrap

  4. Set Column-gap to 16px

  5. Create the image items:

  6. Add three Divs inside the section, set tag to article
  7. Set Flex-basis to 200px, Flex-grow to 0

  8. Set Width to 100%, Height to 200px (square images)

  9. Add images inside each article:

  10. Drag an Image block into each article
  11. Set Width to 100%, Height to 100%
  12. Set Object-fit to cover
  13. Set Object-position to center center

  14. Add alt text to each image

  15. Result: three square images side by side, photos cropped to fill without distortion. On narrow screens, they wrap naturally into rows.

Practical example: responsive hero image with text overlay

You want a full-width image with text on top.

  1. Create the hero container:
  2. Add a Div, set height to 400px (or your choice)
  3. Set Width to 100%

  4. Set Position to relative (so text can position absolutely over it)

  5. Add the background image:

  6. Drag an Image block into the hero Div
  7. Set Width to 100%, Height to 100%
  8. Set Object-fit to cover, Object-position to center center

  9. This fills the hero box without distortion

  10. Add text on top:

  11. Add a Div inside the hero
  12. Set Position to absolute, Top to 50%, Left to 50%
  13. Add text inside with a high Flex-basis to center it
  14. Style with color and shadows to stand out against the image

The image fills the hero area, text floats on top, and everything scales responsively.

Common mistakes

  • Forgetting alt text. Every image needs alt text. Screen reader users and search engines depend on it.
  • Using fill object-fit when you meant cover. fill distorts the image to stretch; cover crops while maintaining aspect ratio.
  • Not setting width/height on images. If an image has no set size, it displays at its natural resolution, which may be too large or small.
  • Setting object-fit without understanding aspect ratio mismatch. Object-fit only matters when the box and image have different proportions.
  • Using images as layout tools. For layout spacing and structure, use semantic elements (Sections, Divs, Flexbox). Images are for content.

Learn more

Advanced: replaced elements and how Silex handles them

Media elements (img, video, iframe, embed, audio, canvas) are called "replaced elements" in CSS. Unlike normal HTML elements, their appearance is determined by external content (the image file, video stream, etc.) rather than CSS boxes.

In Silex, images cannot be converted to links via the Tag Name selector. The image component removes the href and tag-name traits. If you want a clickable image, wrap it in a Link element instead.

The Object section (with object-fit and object-position properties) appears only when a replaced element is selected. This is done by registering the Object sector to show only for img, video, iframe, embed, audio, and canvas elements.

When you upload images via the Asset Manager, Silex converts URLs to a stored format internally and back to displayable URLs on the canvas — this is transparent to you.

Reference: Object-Fit and Object-Position values

Object-Fit values

Value Effect
fill Stretches/squeezes the content to fill the box. Aspect ratio may not be preserved.
contain Scales the content to fit inside the box. Preserves aspect ratio. May letterbox.
cover Scales the content to cover the entire box. Preserves aspect ratio. May crop.
none Content keeps its natural size. May overflow or leave space.
scale-down Uses whichever is smaller: none or contain.
initial Resets to CSS default (fill).
inherit Uses the parent element's value.

Object-Position values

Position Anchors to
left top Top-left corner (0% 0%)
left center Left edge, vertically centered (0% 50%)
left bottom Bottom-left corner (0% 100%)
center top Top edge, horizontally centered (50% 0%)
center center Dead center (50% 50%, default)
center bottom Bottom edge, horizontally centered (50% 100%)
right top Top-right corner (100% 0%)
right center Right edge, vertically centered (100% 50%)
right bottom Bottom-right corner (100% 100%)
initial Resets to CSS default (50% 50%)
inherit Uses parent element's value
unset Removes any set value

Use these together: cover with center top crops the bottom, keeping the top visible.

Quiz

Q1: A company logo is in a tall sidebar and looks squished. What do you set?

  • A) Object-fit to fill
  • B) Object-fit to contain
  • C) Width to 100%
Answer

B) Object-fit to contain — this scales the logo to fit without distortion. You may see empty space, but the aspect ratio is preserved.

Q2: A hero image has Object-fit: cover, but the subject (at the bottom) gets cropped. How do you fix it?

  • A) Set Object-fit to contain
  • B) Set Object-position to center bottom
  • C) Increase the container height
Answer

B) Set Object-position to center bottom — the crop anchors to the bottom, keeping the subject visible.

Q3: A screen reader user visits your page. An image has no alt text. What happens?

  • A) The screen reader reads the file name (IMG_4392.jpg)
  • B) The screen reader skips it silently
  • C) Either A or B depending on the screen reader
Answer

C) Either A or B depending on the screen reader — some read the file name, some skip it. Either way, add descriptive alt text so all visitors understand the image.

Q4: You want to embed a YouTube video. Which block should you use?

  • A) Video block
  • B) Map block or Custom code block
  • C) Image block
Answer

B) Map block or Custom code block — the Video block is for self-hosted video files. Map block creates an iframe for embedded content.

Q5: Your 600px-wide image takes a long time to load. The original file is 5000px. What should you do?

  • A) Use CSS to scale it down
  • B) Set Object-fit to scale-down
  • C) Resize the image to 1200px before uploading
Answer

C) Resize the image to 1200px before uploading — this cuts the file size dramatically. CSS scaling doesn't reduce the file size, it just displays it smaller.

Edit this page on GitLab