ImageLcpPriority [pattern] v1.0.0

Hint the browser that the LCP image is the most important resource on the page. Combines <link rel='preload' as='image'> with fetchpriority='high', modern format negotiation, and explicit dimensions to drive sub-2.5s LCP on mobile.

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Body

    # Pattern: Prioritize the LCP image

    The Largest Contentful Paint (LCP) is almost always an image (~75% of the time per HTTPArchive). The browser does not know which image is the LCP candidate until it has parsed CSS and laid out — by then, lower-priority images may already have started fetching.

    ## Implementation (HTML)

    ```html
    <!-- 1. Preload the LCP image with explicit type for format negotiation -->
    <link rel="preload"
          as="image"
          href="/hero.avif"
          type="image/avif"
          imagesrcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
          imagesizes="(max-width: 640px) 100vw, 1280px"
          fetchpriority="high">

    <!-- 2. Render the image with matching srcset + fetchpriority -->
    <img src="/hero-1280.avif"
         srcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
         sizes="(max-width: 640px) 100vw, 1280px"
         alt="Descriptive text for the hero subject"
         width="1280"
         height="720"
         fetchpriority="high"
         decoding="sync">
    ```

    ## Key Mechanisms

    1. `<link rel="preload" fetchpriority="high">` — fires the request during HTML parse, before CSS is fetched.
    2. `<img fetchpriority="high">` — explicit signal; otherwise browser defaults the FIRST in-viewport image to high.
    3. `decoding="sync"` — for the LCP image only; tells browser to block render briefly to decode synchronously, preventing a brief blank flash.
    4. `width` / `height` attributes — reserve space, prevent CLS (see @community/rule-cls-budget).
    5. AVIF / WebP via `<picture>` for ~40-60% byte savings vs JPEG at equivalent quality.
    6. Below-the-fold images: `loading="lazy"` + `fetchpriority="low"` — opposite signal.

    ## When to Use `<picture>` Format Negotiation

    ```html
    <picture>
      <source type="image/avif" srcset="/hero.avif">
      <source type="image/webp" srcset="/hero.webp">
      <img src="/hero.jpg" width="1280" height="720" alt="..."
           fetchpriority="high" decoding="sync">
    </picture>
    ```

    Use when AVIF support is required AND your CDN does not negotiate by Accept header. Modern image CDNs (Vercel Image, Cloudflare Images, Fastly Image Optimizer) handle negotiation automatically — a single <img> with srcset is sufficient.

    ## Anti-Patterns to Avoid

    - DO NOT lazy-load the LCP image (loading="lazy") — defers it to after layout, blowing LCP.
    - DO NOT inline LCP image as base64 — bloats HTML, blocks parser.
    - DO NOT use a CSS background-image for LCP — the browser cannot prioritize it via fetchpriority.
    - DO NOT render the LCP image inside JavaScript-only components — it requires hydration before the request fires; SSR + native <img> is faster.
  

Use When

• The LCP element is an image (most product / marketing pages)
• Page has multiple above-the-fold images and you need to differentiate the hero
• Site is image-heavy (e-commerce, news, photography portfolios)

Avoid When

• LCP element is text or a video — different patterns apply
• Hero is a CSS gradient (no image to preload)
• Image is below the fold — loading='lazy' is correct, NOT high priority

Counter Examples

• as the LCP — browser defers fetch until layout; LCP becomes 3.5s+ on 4G.
• background-image: url(hero.jpg) on hero
  — no fetchpriority signal; browser deprioritizes it behind synchronous CSS sprites.

ImageLcpPriority [pattern] v1.0.0

Hint the browser that the LCP image is the most important resource on the page. Combines <link rel='preload' as='image'> with fetchpriority='high', modern format negotiation, and explicit dimensions to drive sub-2.5s LCP on mobile.

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Body

    # Pattern: Prioritize the LCP image

    The Largest Contentful Paint (LCP) is almost always an image (~75% of the time per HTTPArchive). The browser does not know which image is the LCP candidate until it has parsed CSS and laid out — by then, lower-priority images may already have started fetching.

    ## Implementation (HTML)

    ```html
    <!-- 1. Preload the LCP image with explicit type for format negotiation -->
    <link rel="preload"
          as="image"
          href="/hero.avif"
          type="image/avif"
          imagesrcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
          imagesizes="(max-width: 640px) 100vw, 1280px"
          fetchpriority="high">

    <!-- 2. Render the image with matching srcset + fetchpriority -->
    <img src="/hero-1280.avif"
         srcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
         sizes="(max-width: 640px) 100vw, 1280px"
         alt="Descriptive text for the hero subject"
         width="1280"
         height="720"
         fetchpriority="high"
         decoding="sync">
    ```

    ## Key Mechanisms

    1. `<link rel="preload" fetchpriority="high">` — fires the request during HTML parse, before CSS is fetched.
    2. `<img fetchpriority="high">` — explicit signal; otherwise browser defaults the FIRST in-viewport image to high.
    3. `decoding="sync"` — for the LCP image only; tells browser to block render briefly to decode synchronously, preventing a brief blank flash.
    4. `width` / `height` attributes — reserve space, prevent CLS (see @community/rule-cls-budget).
    5. AVIF / WebP via `<picture>` for ~40-60% byte savings vs JPEG at equivalent quality.
    6. Below-the-fold images: `loading="lazy"` + `fetchpriority="low"` — opposite signal.

    ## When to Use `<picture>` Format Negotiation

    ```html
    <picture>
      <source type="image/avif" srcset="/hero.avif">
      <source type="image/webp" srcset="/hero.webp">
      <img src="/hero.jpg" width="1280" height="720" alt="..."
           fetchpriority="high" decoding="sync">
    </picture>
    ```

    Use when AVIF support is required AND your CDN does not negotiate by Accept header. Modern image CDNs (Vercel Image, Cloudflare Images, Fastly Image Optimizer) handle negotiation automatically — a single <img> with srcset is sufficient.

    ## Anti-Patterns to Avoid

    - DO NOT lazy-load the LCP image (loading="lazy") — defers it to after layout, blowing LCP.
    - DO NOT inline LCP image as base64 — bloats HTML, blocks parser.
    - DO NOT use a CSS background-image for LCP — the browser cannot prioritize it via fetchpriority.
    - DO NOT render the LCP image inside JavaScript-only components — it requires hydration before the request fires; SSR + native <img> is faster.
  

Use When

• The LCP element is an image (most product / marketing pages)
• Page has multiple above-the-fold images and you need to differentiate the hero
• Site is image-heavy (e-commerce, news, photography portfolios)

Avoid When

• LCP element is text or a video — different patterns apply
• Hero is a CSS gradient (no image to preload)
• Image is below the fold — loading='lazy' is correct, NOT high priority

Counter Examples

• as the LCP — browser defers fetch until layout; LCP becomes 3.5s+ on 4G.
• background-image: url(hero.jpg) on hero
  — no fetchpriority signal; browser deprioritizes it behind synchronous CSS sprites.

Examples

• Vercel: their /next.js LCP image preloaded via <link rel=preload> + AVIF; LCP = 1.1s on 4G mobile.
• Pinterest: hero image gets fetchpriority=high; subsequent grid images get fetchpriority=auto + loading=lazy. LCP improved 30%.
• Smashing Magazine: AVIF hero + preload link + size-adjust webfont — Cumulative real-user LCP-p75 dropped from 2.8s to 1.4s.

Relations

related: [@community/metric-lcp-largest-contentful-paint, @community/rule-cls-budget, @community/principle-perceived-vs-actual, @community/anti-pattern-blocking-third-party, @community/fact-rail-targets] derived-from: @community/metric-lcp-largest-contentful-paint

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Body

    # Pattern: Prioritize the LCP image

    The Largest Contentful Paint (LCP) is almost always an image (~75% of the time per HTTPArchive). The browser does not know which image is the LCP candidate until it has parsed CSS and laid out — by then, lower-priority images may already have started fetching.

    ## Implementation (HTML)

    ```html
    <!-- 1. Preload the LCP image with explicit type for format negotiation -->
    <link rel="preload"
          as="image"
          href="/hero.avif"
          type="image/avif"
          imagesrcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
          imagesizes="(max-width: 640px) 100vw, 1280px"
          fetchpriority="high">

    <!-- 2. Render the image with matching srcset + fetchpriority -->
    <img src="/hero-1280.avif"
         srcset="/hero-640.avif 640w, /hero-1280.avif 1280w, /hero-2560.avif 2560w"
         sizes="(max-width: 640px) 100vw, 1280px"
         alt="Descriptive text for the hero subject"
         width="1280"
         height="720"
         fetchpriority="high"
         decoding="sync">
    ```

    ## Key Mechanisms

    1. `<link rel="preload" fetchpriority="high">` — fires the request during HTML parse, before CSS is fetched.
    2. `<img fetchpriority="high">` — explicit signal; otherwise browser defaults the FIRST in-viewport image to high.
    3. `decoding="sync"` — for the LCP image only; tells browser to block render briefly to decode synchronously, preventing a brief blank flash.
    4. `width` / `height` attributes — reserve space, prevent CLS (see @community/rule-cls-budget).
    5. AVIF / WebP via `<picture>` for ~40-60% byte savings vs JPEG at equivalent quality.
    6. Below-the-fold images: `loading="lazy"` + `fetchpriority="low"` — opposite signal.

    ## When to Use `<picture>` Format Negotiation

    ```html
    <picture>
      <source type="image/avif" srcset="/hero.avif">
      <source type="image/webp" srcset="/hero.webp">
      <img src="/hero.jpg" width="1280" height="720" alt="..."
           fetchpriority="high" decoding="sync">
    </picture>
    ```

    Use when AVIF support is required AND your CDN does not negotiate by Accept header. Modern image CDNs (Vercel Image, Cloudflare Images, Fastly Image Optimizer) handle negotiation automatically — a single <img> with srcset is sufficient.

    ## Anti-Patterns to Avoid

    - DO NOT lazy-load the LCP image (loading="lazy") — defers it to after layout, blowing LCP.
    - DO NOT inline LCP image as base64 — bloats HTML, blocks parser.
    - DO NOT use a CSS background-image for LCP — the browser cannot prioritize it via fetchpriority.
    - DO NOT render the LCP image inside JavaScript-only components — it requires hydration before the request fires; SSR + native <img> is faster.
  

Use When

• The LCP element is an image (most product / marketing pages)
• Page has multiple above-the-fold images and you need to differentiate the hero
• Site is image-heavy (e-commerce, news, photography portfolios)

Avoid When

• LCP element is text or a video — different patterns apply
• Hero is a CSS gradient (no image to preload)
• Image is below the fold — loading='lazy' is correct, NOT high priority

Counter Examples

• as the LCP — browser defers fetch until layout; LCP becomes 3.5s+ on 4G.
• background-image: url(hero.jpg) on hero
  — no fetchpriority signal; browser deprioritizes it behind synchronous CSS sprites.

Derived From

@community/metric-lcp-largest-contentful-paint