Image and Picture Components

Picture Examples

Basic Picture with Loading Spinner

<Picture

    src="https://picsum.photos/640/480"

    alt="Random landscape"

    width={ 640 }

    height={ 480 }

    className="rounded-box overflow-hidden"

    onLoad={ () => console.log("Loaded!") }

/>

Masonry Gallery Layout

Responsive masonry layout that distributes images across columns automatically.

#01

#03

#05

#07

#09

#11

#02

#04

#06

#08

#10

#12

<Masonry

    columns={ { xs: 2, sm: 2, md: 3, lg: 4 } }

    gap={ 4 }

    <Picture

        src="https://picsum.photos/400/600"

        width={ 400 }

        height={ 600 }

        loadingAnimation="ring"

/>

    // More pictures with varying heights...

</Masonry>

💡 Tip: Masonry layout automatically distributes images across columns. Images with different heights create a natural, flowing layout without gaps.

Auto Dimensions & Fill Mode

💡 Fill mode makes images responsive - they fill their parent container while maintaining aspect ratio. Natural dimensions are displayed in development mode.

fill + aspect-video (16:9)

fill + aspect-4/3

fill + aspect-square

fill + aspect-[21/9]

Object Fit Variations

objectFit="cover"

objectFit="contain"

objectFit="fill"

objectFit="none"

<div className="relative aspect-video">

    <Picture

        src="/banner.jpg"

        alt="Responsive banner"

        fill // Responsive mode

        objectFit="cover" // or contain, fill, none

        onLoad={ (img) => {

            console.log(img.naturalWidth, img.naturalHeight);

} }

/>

</div>

Practical Use Cases

1. Responsive Gallery Grid

Grid with uniform aspect ratios - perfect for photo galleries

<div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">

    { photos.map(photo => (

        <div className="relative aspect-square rounded-box overflow-hidden">

            <Picture

                src={ photo.url }

                alt={ photo.title }

                fill

                objectFit="cover"

/>

        </div>

    )) }

</div>

2. Adaptive Hero Banner

Full-width banner with ultrawide aspect ratio - great for headers

Welcome to Oihana Next UI

Next JS OpenSource UI Library

<div className="relative aspect-21/9 w-full">

    <Picture

        src="/hero.jpg"

        alt="Hero"

        fill

        priority // Above the fold

        objectFit="cover"

/>

    <div className="absolute inset-0 ...">

        { /* Overlay content */ }

    </div>

</div>

3. Auto Dimension Detection

Retrieve natural image dimensions for processing or display

Open your browser console to see:

naturalWidth & naturalHeight (original image size)
width & height (displayed size)
Useful for image processing, validation, or analytics

📸 Image loaded!

Natural dimensions: 1920 x 1080

Displayed dimensions: 480 x 270

<Picture

    src={ userUpload }

    width={ 800 }

    height={ 600 }

    onLoad={ (img) => {

        // Get natural dimensions

        const width = img.naturalWidth;

        const height = img.naturalHeight;

        // Save to database, validate, etc.

        saveDimensions(width, height);

} }

/>

💡 Use Cases Summary:

Gallery: Uniform grid with aspect-square + fill
Hero Banner: Wide format with aspect-[21/9] + priority
Dimensions: Use onLoad to get natural size

Corner Content & Overlays

Add any content to the four corners of your images: badges, buttons, icons, text, etc.

E-commerce Product

-30%

$349

$499

In Stock

Photo Gallery

📸 Canon EOS R5

⭐ 4.8 (124 likes)

Real Estate

Featured

NEW

Starting at

$1.2M

🛏️ 3 beds · 🚿 2 baths

Video Thumbnail

LIVE

⏱️ 12:45

<Picture

    src="/product.jpg"

    width={ 600 }

    height={ 800 }

    // Corner content

    topLeft={ <Badge color="error">-30%</Badge> }

    topRight={ <Button icon={FavoriteIcon} /> }

    bottomLeft={ <div>$349</div> }

    bottomRight={ <Badge>In Stock</Badge> }

    // Optional dimensions

    showDimensions

    dimensionsPosition="bottom-right"

/>

💡 Corner Positions Available:

topLeft - Top-left corner (e.g., badges, labels)
topRight - Top-right corner (e.g., action buttons)
bottomLeft - Bottom-left corner (e.g., price, metadata)
bottomRight - Bottom-right corner (e.g., status, CTA)
showDimensions - Display natural image dimensions
dimensionsPosition - Where to place dimensions badge

Center Content Examples

Place content in the center of images - perfect for play buttons, overlay text, or call-to-actions.

Video Thumbnail

LIVE

⏱️ 45:32

Hero Overlay

Premium Wood Furniture

Handcrafted Excellence Since 1995

Premium Content

🔒

Premium Content

Subscribe to unlock exclusive photos and videos

Image Preview

HD Quality

Click to zoom

Coming Soon

COMING SOON

March 2026

CTA Overlay

Eco-Friendly

🌲

Sustainable Wood

100% eco-friendly materials sourced from certified forests

<Picture

    src="/video-thumbnail.jpg"

    width={ 800 }

    height={ 450 }

    // Center content

    center={

        <Button size="lg" shape="circle">

            <PlayIcon />

        </Button>

    // Can combine with corners

    topRight={ <Badge>LIVE</Badge> }

    bottomLeft={ <div>Duration</div> }

/>

💡 Center Content Use Cases:

Play Buttons: Video/audio thumbnails with play controls
Hero Text: Centered headlines and CTAs over images
Premium Overlays: Locked content with unlock prompts
Interactive Icons: Zoom, preview, or action buttons
Status Messages: "Coming Soon", "Sold Out", etc.
Call to Actions: Centered buttons and promotional content

Dark Mode Support

Automatically switch between light and dark images based on the theme.

💡 Toggle your theme to see the images change automatically!

Logo with Dark Mode

Light theme shows first image, dark theme shows second image

Hero Banner with Dark Mode

Theme-Aware Hero

Product with Dark Variant

-30%

Illustration (Fill Mode)

Premium

<Picture

    src="/logo-light.png" // Light mode image

    dark="/logo-dark.png" // Dark mode image

    alt="Logo"

    width={ 400 }

    height={ 100 }

    // Works with all Picture features

    topLeft={ <Badge>New</Badge> }

    center={ <Button>Click</Button> }

    showDimensions

/>

✅ Dark Mode Benefits:

Automatic switching: Images change with theme (no JS required)
Full compatibility: Works with all Picture features (corners, center, fill, etc.)
Backward compatible: Optional - works like before if dark prop is omitted
Performance: Only one image loaded at a time (CSS handles visibility)
Use cases: Logos, illustrations, diagrams, hero banners, products

Loading Animations

spinner

ring

dots

bars

ball

infinity

<Picture

    loadingAnimation="spinner" // or ring, dots, bars, ball, infinity

/>

Loading Sizes

xs

sm

md

lg

xl

<Picture

    loadingSize="xs" // or sm, md, lg, xl

/>

Loading Colors

primary

secondary

accent

error

<Picture

    loadingColor="primary" // Any TextColor

/>

Round Pictures (Avatars)

<Picture

    src="https://i.pravatar.cc/150?img=1"

    alt="Avatar"

    width={ 150 }

    height={ 150 }

    className="rounded-full overflow-hidden"

    imageClassName="object-cover"

/>

Without Loading Spinner

<Picture

    showLoading={ false } // Disable loading spinner

/>

Priority Loading (Above-the-fold)

Use priority for images that are visible immediately when the page loads (hero banners, above-the-fold content).

<Picture

    priority // Preload this image (disables lazy loading)

    src="/hero-banner.jpg"

/>