Masked Image

Image components with gradient masks for radial fades, linear fades, and glassmorphic overlays

Masked Image

Flexible image components with gradient masking effects. Perfect for creating radial fades, linear fades, and glassmorphic image overlays used throughout the Bento UI Kit.

Usage

import { MaskedImage, MaskedImageContent, GridBackground } from "@/components/ui/masked-image";

export default function Example() {
  return (
    <MaskedImage mask="radial">
      <MaskedImageContent src="/image.png" alt="Description" />
    </MaskedImage>
  );
}

Components

MaskedImage

The container component that applies gradient masking to its children.

MaskedImageContent

Image element with object-fit and positioning controls.

GridBackground

Convenience component for grid background patterns (Bento1 pattern).

GlassmorphicImage

Specialized image component with glassmorphic overlay (Bento14 pattern).

Props

MaskedImage Props

Prop	Type	Default	Description
mask	"radial" | "radial-90" | "radial-97" | "bottom-75" | "bottom-90" | "bottom-100" | "horizontal" | "none"	"radial"	Gradient mask type
size	"sm" | "default" | "lg" | "full"	"default"	Container size
aspectRatio	"square" | "video" | "portrait" | "auto"	"auto"	Aspect ratio constraint

MaskedImageContent Props

Prop	Type	Default	Description
fit	"cover" | "contain" | "fill" | "none"	"cover"	Object-fit behavior
position	"center" | "top" | "bottom" | "left" | "right"	"center"	Object-position

GridBackground Props

Prop	Type	Default	Description
gridSrc	string	"/images/grid.svg"	Path to grid image
mask	MaskedImage["mask"]	"radial"	Mask type

GlassmorphicImage Props

Prop	Type	Default	Description
size	"sm" | "default" | "lg"	"default"	Image size

Variants

Mask Types

// Radial fade from center
<MaskedImage mask="radial">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// Radial fade to 90% transparent
<MaskedImage mask="radial-90">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// Radial fade to 97% transparent
<MaskedImage mask="radial-97">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// Bottom linear fade (75% transparent)
<MaskedImage mask="bottom-75">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// Bottom linear fade (90% transparent)
<MaskedImage mask="bottom-90">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// Horizontal fade (left and right)
<MaskedImage mask="horizontal">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

// No mask
<MaskedImage mask="none">
  <MaskedImageContent src="/image.png" />
</MaskedImage>

Size Variants

// Small - 280px
<MaskedImage size="sm">...</MaskedImage>

// Default - 336px
<MaskedImage size="default">...</MaskedImage>

// Large - 400px
<MaskedImage size="lg">...</MaskedImage>

// Full - 100% width/height
<MaskedImage size="full">...</MaskedImage>

Aspect Ratios

// Square (1:1)
<MaskedImage aspectRatio="square">...</MaskedImage>

// Video (16:9)
<MaskedImage aspectRatio="video">...</MaskedImage>

// Portrait (3:4)
<MaskedImage aspectRatio="portrait">...</MaskedImage>

// Auto (no constraint)
<MaskedImage aspectRatio="auto">...</MaskedImage>

Examples

Grid Background (Bento1 Pattern)

<GridBackground gridSrc="/images/grid.svg" />

This recreates the exact Bento1 grid background with radial mask.

Glassmorphic Image Overlay (Bento14 Pattern)

<GlassmorphicImage>
  <img src="/avatar.png" alt="User" className="w-full h-full object-cover" />
</GlassmorphicImage>

Custom Mask with Next.js Image

import Image from "next/image";

<MaskedImage mask="radial-90" size="full">
  <Image
    src="/hero.png"
    alt="Hero image"
    fill
    className="object-cover"
  />
</MaskedImage>

Horizontal Fade for Carousels

<MaskedImage mask="horizontal" size="full" className="h-64">
  <div className="flex gap-4 px-8">
    <img src="/item1.png" alt="Item 1" />
    <img src="/item2.png" alt="Item 2" />
    <img src="/item3.png" alt="Item 3" />
  </div>
</MaskedImage>

Bottom Fade for Text Overlay

<MaskedImage mask="bottom-90" size="full" className="h-96">
  <MaskedImageContent src="/background.png" alt="" />
  <div className="absolute bottom-0 left-0 right-0 p-8 z-10">
    <h2 className="text-4xl font-bold">Title</h2>
    <p className="text-lg">Description</p>
  </div>
</MaskedImage>

Object-Fit Variants

// Cover - fills container, crops if needed
<MaskedImageContent src="/image.png" fit="cover" />

// Contain - fits within container, no crop
<MaskedImageContent src="/image.png" fit="contain" />

// Fill - stretches to fill container
<MaskedImageContent src="/image.png" fit="fill" />

// None - original size
<MaskedImageContent src="/image.png" fit="none" />

Object-Position Variants

// Center (default)
<MaskedImageContent src="/image.png" position="center" />

// Top
<MaskedImageContent src="/image.png" position="top" />

// Bottom
<MaskedImageContent src="/image.png" position="bottom" />

Design Tokens

Mask Gradients

Mask Type	Token	Description
radial	var(--gradient-radial-center)	Fade from center to transparent
radial-90	var(--gradient-radial-center-90)	90% transparent at edge
radial-97	var(--gradient-radial-center-97)	97% transparent at edge
bottom-75	var(--gradient-mask-bottom)	Linear fade to 75% transparent
bottom-90	var(--gradient-mask-bottom-90)	Linear fade to 90% transparent
bottom-100	var(--gradient-mask-bottom-100)	Linear fade to 100% transparent
horizontal	var(--gradient-mask-horizontal)	Fade left and right edges

Dimensions

Size	Dimensions
sm	280px × 280px
default	336px × 336px
lg	400px × 400px
full	100% × 100%

GlassmorphicImage Dimensions

Size	Dimensions
sm	96px × 128px
default	108px × 128px
lg	128px × 160px

Mask Visualization

Radial Masks

radial:      ████████     (fade to 0% at edge)
             ██████████
             ████████

radial-90:   ████████░    (fade to 10% at edge)
             ██████████░
             ████████░

radial-97:   ████████▓    (fade to 3% at edge)
             ██████████▓
             ████████▓

Linear Masks

bottom-75:   ████████     (solid top, fade bottom)
             ████████
             ██████░░

bottom-90:   ████████     (solid top, stronger fade)
             ████████
             ████░░░░

horizontal:  ░░████░░     (fade left and right)
             ░░████░░

Found In

• Bento1 - Grid background with radial mask
• Bento10 - Avatar images with masks
• Bento11 - Social icon backgrounds
• Bento12 - Masked list items
• Bento13 - Image galleries
• Bento15 - Hero images with fade

Accessibility

Image Content

• Always provide meaningful alt text for content images
• Use alt="" for decorative images
• Ensure text overlays have sufficient contrast
• Masks should not obscure critical content

Best Practices

// Content image - descriptive alt
<MaskedImage mask="radial">
  <MaskedImageContent 
    src="/product.png" 
    alt="Product showcase featuring the new design"
  />
</MaskedImage>

// Decorative background - empty alt
<MaskedImage mask="radial-90">
  <MaskedImageContent src="/pattern.png" alt="" />
</MaskedImage>

// With text overlay - ensure contrast
<MaskedImage mask="bottom-90">
  <MaskedImageContent src="/hero.png" alt="" />
  <div className="absolute bottom-0 p-8 z-10">
    <h2 className="text-white drop-shadow-lg">Title</h2>
  </div>
</MaskedImage>

Performance

• Pure CSS masking (hardware accelerated)
• No JavaScript required
• Minimal DOM nodes
• Efficient image loading with Next.js Image support
• Lazy loading compatible

Responsive Behavior

All size variants can be overridden with responsive classes:

<MaskedImage 
  size="default"
  className="w-full md:w-[336px] h-64 md:h-[336px]"
>
  <MaskedImageContent src="/image.png" />
</MaskedImage>