Cotton UI

Components

Image

Image helps you display the image in an optimal manner. By default, it waits up to 5 seconds (configurable) for an image resource to fully load before displaying it, mitigating display issues with certain formats like baseline JPEGs. If loading exceeds 5 seconds, the component will display the partially-loaded image anyway to indicate progress.

PreviewCode
  import { ImagePrimitive } from "@cychien/cotton-ui";  

  function ImageComponent() {
    return (
      <Image
        alt=""
        src="https://res.cloudinary.com/dgppby8lr/image/upload/w_1650,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg"
        width={5760}
        height={3840}
        srcSet="
          https://res.cloudinary.com/dgppby8lr/image/upload/w_280,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 280w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_560,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 560w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_840,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 840w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_1100,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 1100w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_1650,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 1650w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_2100,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 2100w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_2500,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 2500w,
          https://res.cloudinary.com/dgppby8lr/image/upload/w_3100,q_auto,f_auto/v1693572221/cotton-ui/image-component-demo_rllwr6.jpg 3100w
        "
        sizes="(min-width:640px) 330px, 80vw"
        className="max-w-[80vw] rounded-md sm:max-w-[330px]"
        placeholder="data:image/webp;base64,UklGRuYAAABXRUJQVlA4INoAAADwBwCdASpkAEMAPrlSoUyuLKqlqTTcecAXCWcGcGanLzBBplXKwkFH7cYlLzrtLC2YCI8KGsx2LUEdgjb4V6Aye0Im2lB5/oAA/t6SRTZXVo7CqrRzxpddQnP21XyNn1FuZzQE1gu1FVrFbd9MuF9YPaOkk0CZr7fi4GpUxMbmRpjo43NISZ+L/K3tZmbK9JiqANthH/t+VuEXiSDNX4mXWJAYk5VKDmB/PSD0uGJnsedHYpwFg+X10BKHtA253ZpdxRQld/KHG0JoCCsI8j5NDNTf1yNoisAAAA=="
      />
    );
  }
Props
widthnumberRequired
The instristic image width which is used to prevent layout shifts. This should not be considered the final image width.
heightnumberRequired
The instristic image height which is used to prevent layout shifts. This should not be considered the final image height.
placeholderstring
The image displayed until the actual image fully loads. It's recommended to use a base64 data URL for immediate rendering.
maxJSWaitTimenumber
The total time waiting for actual image to load. If this time is exceeded, the partially-loaded image will be displayed to inform users of the loading progress.
Plus all props from HTML <img>

Usage

  function Image() {
    return (
      <Image
        alt=""
        src="https://image-demo-1200px.jpg"
        width={1600}
        height={900}
        srcSet="
          https://image-demo-200px.jpg 200w,
          https://image-demo-600px.jpg 600w,
          https://image-demo-1200px.jpg 1200w,
        "
        sizes="(min-width:640px) 330px, 80vw"
        placeholder="data:image/webp;base64,UklGRuYAAABXRUJQVlA4INoAAADwBwCdASpkAEMA"
      />
    )
  }

Behaviors

There is no difference in behavior between the hydrated and unhydrated modes.

A timer is set when the HTML is parsed. By default, if the image fully loads within 5 seconds (configurable), it will be displayed all at once. This approach helps to prevent display issues associated with certain image formats, such as baseline JPEGs.

If the loading time exceeds 5 seconds, the partially-loaded image will be displayed regardless of how much data has been loaded. This ensures that users are not stuck viewing the placeholder, keeping them informed about the image's loading progress.

Tabs