Network Image

Image component that adapts quality and loading strategy in real-time based on connection speed using the Network Information API.

Component

Network-responsive demo image
4G

Installation

pnpm dlx shadcn@latest add "https://pulkitxm.com/components/network-image.json"

Usage

Import the component

Add the NetworkImage import to your file.

import { NetworkImage } from "@/components/network-image";

Use with default props

Use with required src and alt. The component adapts automatically.

<NetworkImage
  src="https://example.com/image.jpg"
  alt="Description"
/>;

Customize with props

Provide quality tiers and show the connection badge for debugging.

<NetworkImage
  src="/full.jpg"
  mediumSrc="/medium.jpg"
  lowSrc="/thumb.jpg"
  alt="Adaptive"
  showBadge
/>;

Guidelines

  • Provide lowSrc and mediumSrc for best results on slow connections; otherwise the full src is used for all tiers.
  • Use showBadge during development to verify the component detects your connection correctly.
  • The Network Information API has limited browser support (Chromium); the component falls back to 4g behavior when unavailable.
  • Respect saveData: when the user has enabled reduced data usage, the component uses the low tier.

Props

PropTypeDefaultDescription
srcstringPrimary image URL. Used for 4g connections.
altstringAccessible alt text for the image.
lowSrcstringundefinedLow-resolution URL for 2g/slow-2g. Falls back to mediumSrc or src if not provided.
mediumSrcstringundefinedMedium-resolution URL for 3g. Falls back to src if not provided.
widthnumberundefinedImage width in pixels.
heightnumberundefinedImage height in pixels.
classNamestringundefinedAdditional CSS classes for the wrapper.
showBadgebooleanfalseShow a badge overlay with the detected connection type (4G, 3G, 2G, Offline).
loadingStrategy"auto" | "eager" | "lazy""auto"Loading strategy. 'auto' adapts by network; 'eager' or 'lazy' override.
networkOverridePartial<NetworkStatus>undefinedOverride network status for testing/demo. Not for production use.

Examples

Basic

Default usage. Uses full resolution on fast connections, adapts on slower ones.

Network-responsive demo image
4G
import { NetworkImage } from "@/components/network-image";

export function NetworkImageBasic() {
  return (
    <NetworkImage
      src="https://picsum.photos/800/400"
      alt="Adaptive image"
    />
  );
}

Quality tiers

Provide different image URLs for each connection tier.

Network-responsive demo image
4G
import { NetworkImage } from "@/components/network-image";

export function NetworkImageWithTiers() {
  return (
    <NetworkImage
      src="https://example.com/image-full.jpg"
      mediumSrc="https://example.com/image-medium.jpg"
      lowSrc="https://example.com/image-thumb.jpg"
      alt="Adaptive image with quality tiers"
    />
  );
}

With badge

Show a live badge indicating the detected connection type.

Network-responsive demo image
4G
import { NetworkImage } from "@/components/network-image";

export function NetworkImageWithBadge() {
  return (
    <NetworkImage
      src="https://picsum.photos/800/400"
      alt="Image with network badge"
      showBadge
    />
  );
}

Made with ❤️ by Pulkit

© 2026 Pulkit. All rights reserved

DMCA Verified

Last updated: