Five ways to use images in React, from static imports to user uploads

Classify the image before choosing an import path

React renders elements and attributes; it does not define how JPEG, PNG, or SVG files enter a build. Static imports, public-directory paths, remote URLs, CSS references, and framework image components are contracts supplied by the bundler or framework. User-selected files follow a separate runtime upload lifecycle and cannot be imported as source modules.

Classify each image by owner, update frequency, privacy, and semantic role. A logo released with application code belongs in the build graph. A tenant avatar belongs in application data and durable storage. A decorative texture may belong in CSS, while an article illustration needs HTML semantics. Choosing by lifecycle prevents deployment paths and client bundles from becoming accidental asset databases.

Use static imports for source-controlled assets

A typical component imports a known file and passes the imported value to an img or framework component. Depending on the toolchain, the import may become a fingerprinted URL or an object containing URL and dimension metadata. This lets the build fail on a missing file, track dependencies, and update cache keys when contents change.

Static imports work best for a bounded set of icons, illustrations, and product screenshots. Importing an entire media catalog eagerly can enlarge the build graph and make assets discoverable from routes that never render them. Keep route-specific images near their route, and use framework-supported dynamic or glob mechanisms only when the candidate set is known at build time. Do not construct arbitrary import paths from user input.

import type { ReactNode } from 'react'

import diagramUrl from './request-flow.png'

export function RequestFlow(): ReactNode {
  return (
    <img
      src={diagramUrl}
      alt="Request flow from the browser to object storage"
      width={960}
      height={540}
    />
  )
}

Use public paths when build processing is intentionally bypassed

Files in a public directory are normally copied to deployment output and requested with a path such as /images/logo.png. The browser resolves that string at runtime, so the module resolver cannot catch a misspelled filename or attach imported dimension metadata. Stable names are useful for favicons, manifests, social assets, and files referenced by systems outside the JavaScript build.

Public paths are sensitive to deployment base paths, reverse proxies, and asset prefixes. An absolute root path may work at the main domain and fail when the application is mounted below a subdirectory. Follow the framework's path rules instead of concatenating window.location values. Give frequently changing files fingerprinted names or a deliberate revalidation policy so a deployment does not leave users with mismatched cached code and imagery.

Treat remote URLs as application data

An external src can represent a CMS image, storage object, or third-party service. Store it as validated data rather than scattering host strings through components. Define which schemes and hosts are allowed, what happens when the object is missing, whether authentication is required, and how cache invalidation works. Avoid expiring signed URLs in records intended to survive a session.

Framework image components may require a remote-host allowlist and can add sizing, format negotiation, or optimization. Those behaviors are framework features, not React behavior, and can change the request path or cost model. Confirm whether the original host or an optimizer receives user identifiers. Apply Content Security Policy, referrer policy, and privacy requirements consistently, especially when an untrusted record can influence the URL.

import type { ReactNode } from 'react'

const allowedImageHosts = new Set(['media.example.com'])

interface ProductImageProps {
  alt: string
  height: number
  src: string
  width: number
}

export function ProductImage({ alt, height, src, width }: ProductImageProps): ReactNode {
  if (!URL.canParse(src)) {
    return null
  }

  const url = new URL(src)
  if (url.protocol !== 'https:' || !allowedImageHosts.has(url.hostname)) {
    return null
  }

  return <img src={url.href} alt={alt} width={width} height={height} loading="lazy" />
}

Handle SVG according to trust and interaction needs

Rendering an SVG through img treats it as an external image and keeps its internal elements outside the application DOM. Importing SVG as a React component, when supported by the build, exposes paths and attributes for styling and animation but increases markup and couples the source to a specific compiler plugin. Referencing an SVG file and importing it as a component are therefore different contracts.

Do not turn an untrusted uploaded SVG into inline application markup. SVG can contain active or external features, and a filename extension alone does not make its contents safe. Sanitize with a policy designed for the intended SVG feature set, serve risky files as downloads when appropriate, and apply restrictive response headers. For simple product icons, prefer the application's established icon system rather than inventing another loader.

Reserve CSS imports for decorative imagery

A CSS module or stylesheet can reference a background with url(), allowing the bundler to fingerprint a local asset. This is suitable for textures, masks, and decorative layers. It is not a substitute for an img when readers need alternative text, intrinsic dimensions, image-specific loading controls, or the ability to save and inspect meaningful content.

Remember that CSS discovery can delay an important image until the stylesheet is downloaded and matched. A hidden rule may still enter the build even when no route uses it, depending on bundler behavior. Keep decorative assets colocated with their component, review generated output, and test failure and high-contrast states. Essential text and controls must remain in the React tree rather than being baked into a background.

Preview local files without confusing them with imports

A file selected through an input or drop zone is a browser File, usually backed by a local Blob. Create a temporary object URL for a preview or use a decode API, and revoke each object URL when the preview is replaced or the component is removed. The preview URL is session-local and must never be stored as if it were a public asset URL.

Validate the candidate before expensive preview work. Check allowed type, byte limit, and, after decoding, pixel dimensions. The declared MIME type and extension are hints rather than proof. Preserve a clear error state and keyboard-accessible selection controls. Large images can exhaust memory when decoded even if their compressed byte size appears acceptable, so client checks should complement server-side validation rather than replace it.

Build user uploads as an authorized processing pipeline

Images selected by users are File objects, not imports. Preview them with an object URL, then upload them through a backend endpoint or a narrowly signed direct-upload request. Keep reusable credentials off the client, authorize the destination and expected content type, enforce byte and decoded-pixel limits, and treat the browser-reported MIME type as a hint rather than proof.

After the backend validates and processes an upload, persist a durable object key or owned delivery URL together with dimensions, detected MIME type, ownership, and the application record ID. Temporary preview URLs and short-lived processing URLs belong only to the current interaction. React renders the resulting data; the database, storage policy, and delivery layer own its lifecycle.

Render every source with stable layout and semantics

Regardless of how src was obtained, meaningful images need appropriate alt behavior. Describe the image's function in context, use an empty value for genuinely decorative img elements, and avoid repeating adjacent captions. Images used as links need alternative text that communicates the destination or action. A CSS image has no equivalent semantic channel.

Provide intrinsic width and height, or use a framework component that reserves an equivalent aspect ratio, so loading does not shift surrounding content. Responsive CSS only changes display size; it does not prevent downloading an oversized original. Use responsive candidates when available, avoid lazy loading the primary above-the-fold image, and define a deliberate fallback when a remote object cannot be decoded.

Test both development and production asset behavior

Development servers often serve permissive paths and skip the hashing, optimization, and base-path behavior used in production. Run a production build and inspect emitted asset URLs, route-level downloads, remote-host errors, and source maps. Navigate directly to nested routes, refresh them, and test the application behind the same subpath or proxy configuration used in deployment.

Component tests should assert accessible names and fallback behavior, while browser tests should cover a successful load, a missing asset, slow loading, and a rejected user file. Monitor broken-image responses and optimizer errors after release. Keep uploads idempotent where retries are possible, remove abandoned temporary previews, and ensure deleting an application record triggers the intended storage lifecycle rather than only hiding the React element.

Frequently asked questions