Componente Img

Un componente de imagen potente y flexible para Next.js con optimización automática y marcadores de posición difuminados

Ver en GitHub⭐ Danos una estrella en GitHub

Introducción

El componente Img es una solución versátil de imágenes que soporta imágenes locales, remotas y de fondo con marcadores de posición difuminados automáticos, carga perezosa y diseño responsivo.

Características

🎨
Marcadores de posición difuminados automáticos
⚡
Soporte para carga perezosa
📱
Diseño responsivo
🖼️
Múltiples tipos de imagen
🛡️
Manejo de errores
📝
Soporte para TypeScript
🚀
Optimizado para rendimiento
♿
Cumple con accesibilidad

Instalación

Asegúrate de configurar tu archivo next.config.ts :

1. Install the packages

Terminal
npm install imaginex @plaiceholder/next

2. Configure Next.js

next.config.ts
// @ts-check
import withPlaiceholder from "@plaiceholder/next";

/**
 * @type {import('next').NextConfig}
 */
const config = {
  reactStrictMode: true,
  images: {
    domains: [
      "images.unsplash.com",
    ],
  },
};

export default withPlaiceholder(config);

Ejemplos de Uso

Imágenes Remotas

Muestra imágenes desde URLs externas con generación automática de marcadores de posición difuminados.

Sin Marcador Difuminado

Remote image example
View Code
<Img 
  type="remote" 
  src="https://example.com/image.jpg" 
  alt="Remote image" 
  width={400} 
  height={225}
  blurDataURL="data:image/..." // Optional
/>

Con Marcador Difuminado

Remote image with blur
View Code
<Img 
  type="remote" 
  src="https://example.com/image.jpg" 
  alt="Remote image" 
  width={400} 
  height={225}
  blurDataURL="data:image/..." // Optional
/>

Imágenes Locales

Muestra imágenes locales con extracción automática de marcadores de posición difuminados.

Visualización Estándar

Local image example
View Code
import imgLocal from "./path/to/image.jpg";

<Img 
  src={imgLocal} 
  alt="Local image" 
  width={400} 
  height={225}
/>

Modo de Fondo

View Code
<Img 
  type="bg" 
  src={backgroundImage} 
  alt="Hero background" 
  width={800} 
  height={300}
>
  <div className="hero-content">
    <h1>Your Content Here</h1>
  </div>
</Img>

Imágenes de Fondo

Usa imágenes como fondos con soporte para contenido superpuesto.

Sección Hero

Perfecto para secciones hero y banners

View Code
<Img 
  type="bg" 
  src={backgroundImage} 
  alt="Hero background" 
  width={800} 
  height={300}
>
  <div className="hero-content">
    <h1>Your Content Here</h1>
  </div>
</Img>

Ejemplos Avanzados

Imágenes Responsivas

Imágenes que se adaptan a diferentes tamaños de pantalla

Responsive image
View Code
<Img
  type="remote"
  src="https://example.com/image.jpg"
  alt="Responsive image"
  width={800}
  height={450}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  className="w-full h-auto"
/>

Carga Perezosa

Cargar imágenes solo cuando entran en el viewport

Lazy loaded image
View Code
<Img
  type="local"
  src={localImage}
  alt="Lazy loaded image"
  width={600}
  height={400}
  loading="lazy"
  priority={false}
/>

Manejo de Errores

Manejo elegante de fallas en la carga de imágenes

Image with error handling
View Code
<Img
  type="remote"
  src="https://example.com/might-fail.jpg"
  alt="Image with error handling"
  width={400}
  height={300}
  onError={(error) => {
    console.error('Image failed to load:', error);
    // Handle error (show fallback, notify user, etc.)
  }}
  onLoadStart={() => console.log('Loading started')}
  onLoadComplete={() => console.log('Loading completed')}
/>

Referencia de API

Props Base (Todos los Componentes)

Estas props están disponibles para todos los tipos de componentes de imagen.

PropTipoPor DefectoRequeridoDescripción
srcstring | StaticImageData-SíURL de origen de la imagen o imagen importada
altstring-SíTexto alternativo para accesibilidad
type'remote' | 'local' | 'bg''local'SíTipo de componente de imagen a renderizar
widthnumber | string960NoAncho de la imagen en píxeles
heightnumber | string540NoAlto de la imagen en píxeles

Uso con TypeScript

Importa los tipos apropiados para mejor soporte de TypeScript.

TypeScript Example
import Img from '@/components/Img';
import type { ImgRemoteProps, ImgBGProps } from '@/components/utils/ImgProps';

// For remote images with callbacks
const RemoteImageComponent: React.FC = () => {
  const handleLoadStart = () => console.log('Loading started');
  const handleLoadComplete = () => console.log('Loading completed');
  const handleError = (error: Error) => console.error('Load error:', error);

  return (
    <Img
      type="remote"
      src="https://example.com/image.jpg"
      alt="Remote image"
      onLoadStart={handleLoadStart}
      onLoadComplete={handleLoadComplete}
      onError={handleError}
      transitionDuration={800}
      fetchTimeout={3000}
    />
  );
};

// For background images with overlay
const BackgroundImageComponent: React.FC = () => (
  <Img
    type="bg"
    src={backgroundImage}
    alt="Hero background"
    backgroundSize="cover"
    backgroundPosition="center top"
    backgroundAttachment="scroll"
  >
    <div className="hero-content">
      <h1>Overlay Content</h1>
    </div>
  </Img>
);

Consideraciones de Rendimiento

Consejos para rendimiento óptimo

Usa tamaños de imagen apropiados

Implementa carga perezosa para imágenes below-the-fold

Usa marcadores difuminados para mejorar el rendimiento percibido

Configura headers de caché apropiados

Mejores Prácticas

Siempre proporciona texto alt

Esencial para accesibilidad y SEO

Usa dimensiones apropiadas

Establece ancho y alto para prevenir cambios de diseño

Configura dominios para imágenes remotas

Agrega dominios externos a tu configuración de Next.js

Usa prioridad para imágenes above-the-fold

Mejora las puntuaciones de Core Web Vitals

Optimiza la calidad de imagen

Equilibra entre tamaño de archivo y calidad visual

Usa formatos de imagen apropiados

WebP para navegadores modernos, respaldo para antiguos