Images and Assets

This content was generated with the assistance of AI and should be verified against the official Webflow documentation before being relied on in production.

This sub-section’s Webflow bibliography lists the reference material consulted while preparing these pages.

This page was written against Webflow as it was on 2026-10-28. Images are the heaviest part of most pages, and in Webflow they are handled by a small asset pipeline rather than by files that a developer places in a folder: every file uploaded in the Designer or in a CMS image field is stored by Webflow, gets variants for different screen widths, and is served from Webflow’s content delivery network. The pipeline is available on every plan, including the free Starter Site plan; the limits quoted below (4 MB for an image, 10 MB for a document) apply to all of them. Where the behaviour differs between the Designer and the Data API, the text says so.

The running example is the Fernbrook Gardens site, a fictitious botanical garden. The Home page has a large hero photograph of the glasshouse, a grid of plant cards, the garden logo as an SVG and a downloadable PDF with the seasonal opening hours. The page follows those files from the moment they are uploaded to the moment a visitor’s browser downloads one of them, and ends with the code that uploads assets from a script.

What counts as an asset

An asset is any file that was uploaded to the site and is stored by Webflow. The Assets panel lists them, the Image, Video background, Link and Rich Text elements can point to them, and CMS image, multi-image and file fields store references to them.

Kind Formats Size limit

Images

PNG, JPEG (JPG), GIF, SVG, WebP, AVIF

4 MB per file

Documents

PDF, DOC and DOCX, XLS and XLSX, PPT and PPTX, TXT, CSV, ODT, ODS, ODP

10 MB per file

Lottie animations

JSON and dotLottie files

see the Lottie page

Source: Webflow developer documentation: Working with assets

Three consequences follow from this list:

  • The 4 MB limit applies to the file that is uploaded, not to the file that visitors download. A 3.8 MB photograph passes the limit and is still far too heavy for a hero; the limit is a safety net and not a performance target.

  • Videos are not uploaded as assets for playback. Background video accepts a link to a hosted file and the Video element embeds a provider. Both are covered in Lottie, Spline, Rive and Video.

  • Files uploaded to the Assets panel are public. Anyone who knows or guesses the URL can download the file, even if no page links to it. A document that must stay private does not belong in the Assets panel.

Fonts are uploaded in the site settings and not in the Assets panel; they are described in Typography and Fonts.

The Assets panel

The Assets panel is the fourth icon of the Designer’s left bar, between Pages and Components (see Designer Tour). It floats over the left edge of the canvas and can be expanded to a wide, grid-style view.

  • Upload by dragging files from the desktop onto the panel or the canvas, or with the upload button. Several files can be uploaded at once, and dropping an image straight onto the canvas creates an Image element that points to the new asset.

  • Search by file name, and filter by type.

  • Folders organise the library. A folder is created from the panel, files are moved into it by dragging, and folders can be nested. Folders exist only in the Designer; they do not change the URL of a file.

  • Usage shows which pages and elements use an asset, so an unused file can be found and deleted. A file that is still in use is warned about before it is removed.

  • Bulk actions select several assets to delete, move or convert them (see the conversion tool below).

The Fernbrook site keeps four folders, Hero, Plants, Brand and Documents. A naming habit helps more than the folders do: Webflow keeps the original file name in the URL, so glasshouse-hero.jpg is a better upload than IMG_4821.jpg for both the editors who search the panel and the search engines that read the URL.

The URL of an uploaded file has a fixed shape. Webflow puts the site identifier and a file identifier in front of the file name, and serves the file from its own asset domain:

https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero.jpg

Source: Data API: Upload asset

The host name has changed over the years (older sites show uploads-ssl.webflow.com or assets-global.website-files.com), and the old addresses keep working. Pages should never hard-code one of these URLs in custom code, because the file may be replaced or converted; reference the asset through an element or a CMS field instead.

Assets and Shared Libraries

A site that installs a Shared Library receives the library’s components, variables, fonts and assets, and the assets stay owned by the library. Shared Libraries are described in Shared Libraries.

Alt text

Alt text is the textual alternative of an image. Screen readers announce it, search engines read it, and the browser shows it when the file cannot be loaded. Webflow stores alt text in two places that behave differently.

  • On the asset. The Assets panel has an alt text field for each file. The text is a default: every Image element that points to the asset starts with it, and changing it on the asset updates the elements that have not been given their own text.

  • On the element. The Image element’s settings have an alt text control with three choices: use the asset’s text, write a different description for this placement, or mark the image as decorative.

The two levels exist because the same photograph can have a different purpose on different pages. The Fernbrook glasshouse photograph is described as "The Victorian glasshouse at Fernbrook Gardens in spring, with the palm collection visible through the glass" on the About page, where it illustrates the building, and the same file is decorative on a promotional banner that already says "Visit the glasshouse" in text.

Descriptive and decorative images

A descriptive image carries information that the text around it does not. Its alt text states what a sighted visitor learns from it and not what the file is (no "image of" or "photo of", and no file names). A decorative image adds nothing to the content: dividers, background flourishes and photographs repeated beside a caption. Marking an image as decorative makes Webflow write an empty alt attribute, which tells assistive technology to skip it.

<!-- Descriptive: the image tells the visitor something -->
<img src="https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero.jpg"
     alt="The Victorian glasshouse at Fernbrook Gardens in spring, with the palm collection visible through the glass"
     loading="eager" width="1920" height="1080" class="image-hero">

<!-- Decorative: empty alt, the attribute is still present -->
<img src="https://cdn.prod.website-files.com/<site-id>/<file-id>_leaf-divider.svg"
     alt="" loading="lazy" class="divider">

Source: Webflow Help Center: Responsive images

The distinction matters because an Image element with no alt setting at all is the worst of the three states: some tools then announce the file name. The Audit panel lists images that have no alt text and no decorative flag, so it is a good last check before publishing (see Accessibility).

Alt text in the CMS

An image placed in a Collection template page is bound to a CMS image field, and its alt text comes from the asset unless the element is given another text. A Collection that holds photographs usually needs one more thing: a plain-text field for the alt text of each item, because the same asset can be reused by several items, and the asset’s default text cannot describe all of them. The Fernbrook Plants Collection has an Image field and a plain text Image description field, and the template page binds the Image element’s alt text to the latter. Binding is described in Collection Template Pages.

Alt text per locale

On a localized site (see Localization) the alt text can be translated like any other text. A secondary locale can show its own alt text for an image while the file stays the same; the alt text is picked up by the translation workflow together with page text and, with the localized CMS fields, with the items. If a locale has no translation yet, the primary locale’s text is shown, so an untranslated site is never left with empty alt attributes by accident.

A file that contains text, for example a poster with the opening hours drawn in the image, is a different problem. Alt text can repeat the words for a screen reader, but the poster cannot be translated without a second file. For such images, upload a localized file for each locale and swap the asset in the locale, or better, move the text out of the image.

Responsive images

A visitor on a phone should not download a 1920-pixel-wide hero. Webflow solves that when a file is uploaded. For each raster image it creates a set of smaller variants and writes the srcset and sizes attributes that let the browser choose among them.

<img src="https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero.jpg"
     srcset="https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero-p-500.jpg 500w,
             https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero-p-800.jpg 800w,
             https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero-p-1080.jpg 1080w,
             https://cdn.prod.website-files.com/<site-id>/<file-id>_glasshouse-hero.jpg 1920w"
     sizes="(max-width: 1920px) 100vw, 1920px"
     alt="The Victorian glasshouse at Fernbrook Gardens in spring">

Source: Webflow Help Center: Responsive images

The -p-<width> suffix is how Webflow names its generated variants. Four points explain how the feature behaves:

  • Variants are created at upload. A new Image element needs no setup. The browser reads the widths from srcset, compares them with the sizes description of how wide the image is drawn, and the device pixel ratio, and downloads the smallest variant that is still sharp.

  • Only files uploaded to Webflow get variants. An image that is embedded with a raw <img> in a Code Embed, hosted on another service, or placed in a Rich Text field as an external URL keeps whatever markup it has. If the same photo is needed everywhere, upload it as an asset.

  • The sizes attribute describes the layout. Webflow starts from a width of the element’s container and the Image element’s settings allow the sizes hint to be adjusted for images that never fill their container, for example a card image that occupies one third of the row on desktop. A wrong hint makes the browser pick a variant that is larger than needed; it does not break the image.

  • Exported code keeps them. A code export contains the variants in an images folder and the same srcset attributes (see Code Export and Portability).

The background image of a Section or a Div Block is a CSS property, not an <img> element, and it does not get a srcset. A photograph that matters for the page speed belongs in an Image element, or in an element whose background is a small, already compressed file. See Backgrounds, Borders and Effects for the background controls.

The HTML side of the same mechanism, including <picture> and the art-direction case that Webflow does not generate, is explained in Native HTML Images and Lazy Loading.

Width and height

Webflow writes width and height attributes on the <img> when it knows the intrinsic size of the file. They let the browser reserve the space before the file arrives, which prevents the layout from jumping while the page loads (the Cumulative Layout Shift metric). The CSS that Webflow writes for an Image element, max-width: 100% and display: inline-block, still lets the picture scale with its container. A custom height or an object-fit value in the Style panel overrides the proportions, and then the reserved space and the drawn space no longer match; set a fixed aspect ratio on the element when images with several shapes share a grid.

Lazy and eager loading

The loading attribute tells the browser when to fetch an image. lazy waits until the image is near the viewport, and eager fetches it at once. Since the update "New images set to lazy load by default", images added to a site are lazy-loaded unless a different setting is chosen. The update does not touch images that already existed on the site. The Image element’s settings offer the choices Lazy, Eager and Auto (the browser’s own default).

Image Setting Reason

Hero photograph at the top of the Home page

Eager

It is the largest visible element on load, so delaying it delays the whole page

Logo in the navbar

Eager

It is visible immediately and small

Plant cards below the fold

Lazy

The visitor may never scroll to them

Gallery items in a Lightbox

Lazy

Only the first rows are visible

Image in a collapsed accordion or hidden tab

Lazy

It is not needed until the visitor opens it

Source: Webflow updates: New images set to lazy load by default

The classic mistake is the opposite of what the default prevents: leaving the hero image lazy. The browser then waits for the layout, decides that the image is in the viewport and only then starts downloading, which delays the Largest Contentful Paint. Set the first large image of every page to Eager, and let the rest stay lazy. Lazy loading applies to <img> elements only. It does not apply to CSS background images, which the browser downloads as soon as the style rule matches an element.

A Collection List repeats a single Image element for every item, so its setting is shared. Fernbrook sets the plant-card image to Lazy, and limits the featured-plants list on the Home page to a few items instead of relying on lazy loading to hide a long list. The performance consequences, and how to measure them, are in Performance Optimization.

flowchart TD A["Image to place on a page"] --> B{"Is it content or decoration?"} B -->|"Decoration"| C["Mark as decorative: alt is empty"] B -->|"Content"| D["Write alt text for this placement"] C --> E{"Visible without scrolling?"} D --> E E -->|"Yes"| F["Loading: Eager"] E -->|"No"| G["Loading: Lazy"] F --> H["Check size and convert to AVIF or WebP"] G --> H H --> I["Publish and test"]

The diagram is a checklist and does not reproduce any screenshot of the Designer.

The AVIF and WebP conversion tool

JPEG and PNG are old formats. WebP, and more recently AVIF, give the same visual quality at a fraction of the size, and every current browser can display both. Webflow has had a conversion tool for them since 2024-07-31, and it works on the files that are already in the Assets panel.

The steps are the following:

  1. Open the Assets panel and expand it.

  2. Select the images to convert with the check icon of each file.

  3. Choose AVIF or WebP as the target format.

  4. Select Compress and keep working; the conversion runs in the background.

  5. Publish the site again so that the published pages use the new files.

The tool has several properties that are easy to miss:

  • It replaces the original. The file type of the asset is changed in the Assets panel and in every place where the asset is used on the canvas, and the original JPEG or PNG is not kept. The operation is irreversible in Webflow; a converted image cannot be turned back into its original format by the tool. Download the originals before converting, or keep them in the team’s own storage.

  • It works on JPEG, JPG and PNG. SVG, GIF and files that are already WebP or AVIF are not converted.

  • It is limited by rate. A request converts up to 100 assets and the tool accepts 10 requests per minute. Webflow recommends converting very large images one at a time.

  • It is manual and it is not applied to new uploads. An image that is uploaded next month is a JPEG until somebody converts it. A team that cares about this adds the step to its publishing checklist (see Testing, CI and DevOps).

  • Open Graph images are the exception. AVIF and WebP files are not supported for the Open Graph image that social networks display, so the image used for sharing in the page’s SEO settings should stay a JPEG or PNG. Social previews are covered in SEO and AEO.

  • It is not an optimizer for what already is a WebP. Converting does not shrink an oversized photograph. Resize a 6000-pixel original to the largest size the layout can show before uploading it; the tool then improves the encoding of a sensible file.

A comparison of the formats shows why the conversion is worth the care:

Format Strengths Limits

JPEG

Universal; good for photographs

No transparency; larger than WebP and AVIF for the same quality

PNG

Lossless; transparency

Very large for photographs

WebP

Much smaller than JPEG and PNG; transparency; animation

Not accepted as Open Graph image

AVIF

The smallest of the four for photographs; transparency; high dynamic range

Slower to encode; not accepted as Open Graph image

SVG

Vector; scales without loss; styleable

Only for drawings, not photographs

Source: Webflow Help Center: Image conversion tool

For the choice of formats outside Webflow, and for a pipeline that converts images at build time, see Media Optimization.

SVG graphics

SVG is the right format for logos, icons and illustrations. A vector file stays sharp at every size and is usually a few kilobytes. Webflow accepts SVG in the Assets panel, so the Fernbrook logo is uploaded once and used by an Image element, and it can be used wherever an image is allowed.

An SVG used by an Image element is an external file. The browser draws it, but the page’s CSS cannot reach inside it, so an icon that must change colour on hover cannot be restyled that way. There are two ways around it:

  • Inline the SVG in an Embed element. Paste the <svg> markup into a Code Embed. The shapes are now part of the page, so fill and stroke can follow currentColor, and the colour can come from a class or a variable.

  • Use a mask or a pair of files. Use one file for each state and switch them in the hover state of the class.

<!-- Code Embed: the icon inherits the text colour of its parent -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"
     fill="none" stroke="currentColor" stroke-width="2" role="img" aria-label="Glasshouse">
  <path d="M3 21V10l9-7 9 7v11z"/>
  <path d="M9 21v-7h6v7"/>
</svg>

Source: Webflow Help Center: Responsive images

Two cautions apply. SVG files that come from a design tool often carry editor metadata, comments and inline styles; run them through a cleaner before uploading, since a 40 KB logo can shrink to 2 KB. And an SVG that is uploaded must come from a trusted source, because an SVG is a document and can contain scripts. Styling and animating SVG in the browser is explained in SVG Styling and Animation. Animated vector content that Webflow plays itself (Lottie) is a separate element.

SVG files do not get responsive variants, since they have no pixels to reduce, and they are not converted to AVIF or WebP.

Documents

PDFs and other documents are uploaded the same way as images and are subject to the 10 MB limit. The Fernbrook opening-hours PDF is uploaded to the Documents folder and linked from a Link Block whose target is the asset. Three habits keep documents usable:

  • Link text says what the file is and its size and format ("Opening hours 2026-27, PDF, 180 KB"), because a link that says "Download" says nothing out of context.

  • The link opens in a new tab or downloads the file only when the visitor needs it, and the rel="noopener" attribute is added with target="_blank".

  • A document that changes every season is replaced in the Assets panel instead of being uploaded under a new name, so that links already printed or shared remain valid.

A CMS file field stores a document the same way, one per item, which is how the Fernbrook Events Collection offers a programme PDF for each event. Field types are listed in Collections and Field Types.

Uploading assets from code

A script can create assets and folders through the Data API. The upload is a two-step flow because the file itself goes to object storage and not to Webflow’s API server:

  1. POST /v2/sites/{site_id}/assets with the file name and the MD5 hash of the file. The response contains the identifier of the new asset, a hostedUrl, an uploadUrl and an uploadDetails object.

  2. Send the file bytes to uploadUrl as a multipart form whose fields are the entries of uploadDetails, followed by the file itself.

The site token needs the assets:write scope (and assets:read to list). The fileName has to be shorter than 100 characters, and the optional parentFolder is the identifier of an asset folder, so a script can file the upload into a folder directly.

import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
import { WebflowClient } from "webflow-api";

const client = new WebflowClient({ accessToken: process.env.WEBFLOW_TOKEN });
const siteId = "<site-id>";

const bytes = await readFile("./glasshouse-hero.webp");
const fileHash = createHash("md5").update(bytes).digest("hex");

// Step 1: register the asset and receive the upload instructions.
const asset = await client.assets.create(siteId, {
  fileName: "glasshouse-hero.webp",
  fileHash,
  parentFolder: "<hero-folder-id>",
});

// Step 2: send the bytes to the storage location, with the fields Webflow returned.
const form = new FormData();
for (const [name, value] of Object.entries(asset.uploadDetails)) {
  form.append(name, String(value));
}
form.append("file", new Blob([bytes], { type: "image/webp" }), "glasshouse-hero.webp");

const response = await fetch(asset.uploadUrl, { method: "POST", body: form });
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);

console.log("Hosted at", asset.hostedUrl);

Source: Data API: Upload asset

The fileHash also protects against duplicates: Webflow uses it to avoid storing the same file twice. The 4 MB and 10 MB limits apply to API uploads too. Because the asset is public as soon as it exists, a script that uploads drafts should clean up after itself. The Data API also manages folders and lets a script update an asset’s metadata; the endpoints, the SDK and the rate limits are described in Data API: Assets, Forms and Custom Code. Inside the Designer, an app can read and create assets through the Designer API (see Designer Extensions and the Designer API).

The Webflow CLI has an assets command group for the same purpose, which fits a shell script better than a Node program (see Webflow CLI).

A checklist for the Fernbrook site

  1. Resize each photograph to the largest size the layout shows, and export it as JPEG or PNG under 4 MB.

  2. Upload it to the right folder with a descriptive file name.

  3. Decide whether the image is descriptive or decorative, and write the alt text for the placement; add translations if the site is localized.

  4. Set the Loading option: Eager for the first large image of the page, Lazy for the rest.

  5. Convert the bulk to WebP or AVIF with the conversion tool after saving the originals elsewhere, but leave the Open Graph image as JPEG or PNG.

  6. Publish and test the page on a throttled connection. The developer tools of the browser show which variant of the srcset was downloaded.

  7. Run the Audit panel to catch images without alt text.

Where older material is out of date

Books and tutorials from before 2024 describe a Webflow without an image conversion tool, so they tell readers to compress and convert images outside Webflow before uploading, which is still a valid habit for the first resize. They also describe the Designer before the 2023 redesign describe the Editor for changing images (fully deprecated on 2026-10-05; images are now changed on the canvas in Edit mode), and say nothing about lazy loading being the default for new images. Plans named in those sources (Lite, Pro, Team and CMS) were replaced by the current Workspace and Site plans, but the 4 MB and 10 MB limits are the same. See Where Older Books and Tutorials Are Outdated.

Where to go next

References