@conectate/ct-img

An advanced image loader component with smart lazy loading capabilities, elegant loading transitions, and extensive customization options.

Table of Contents

• Installation
• Features
• Basic Usage
• Advanced Usage
• API Reference
  • Properties
  • Attributes
  • Events
  • CSS Custom Properties
• Lazy Loading
• Styling Examples
• Performance Tips
• Browser Support
• Follow Me
• Contributing
• License

Installation

Install via npm, yarn, or pnpm:

# npm
npm i @conectate/ct-img

# yarn
yarn add @conectate/ct-img

# pnpm
pnpm i @conectate/ct-img

Features

• Smart Lazy Loading: Uses native browser lazy-loading where available, with fallback to IntersectionObserver
• Placeholder Support: Display placeholder images while the main image loads
• Error Handling: Shows fallback image when the main image fails to load
• Smooth Transitions: Elegant fade-in animations when images load
• Styling Options: Support for circular images, contained backgrounds, and custom positions
• Custom Viewport: Define a custom scrollable container for precise lazy loading control
• Accessibility: Built with proper alt text support

Basic Usage

Import the component and use it in your HTML:

// Import the component
import '@conectate/ct-img';

<!-- Basic image -->
<ct-img src="image.jpg" alt="Description"></ct-img>

<!-- Lazy loading (loads only when visible) -->
<ct-img srcset="image.jpg" lazy alt="Description"></ct-img>

<!-- Circular image (great for avatars) -->
<ct-img src="profile.jpg" round alt="Profile picture"></ct-img>

<!-- Image with placeholder while loading -->
<ct-img src="large-image.jpg" placeholder-img="placeholder.jpg" alt="Description"></ct-img>

Advanced Usage

Custom Viewport for Lazy Loading

You can define a custom scrollable element as the viewport for lazy loading:

<div id="scrollContainer" style="height: 300px; overflow: auto;">
	<ct-img id="lazyImg" srcset="image.jpg" lazy alt="Lazy loaded image"></ct-img>
</div>

<script>
	document.getElementById('lazyImg').viewport = document.getElementById('scrollContainer');
</script>

Using in LitElement

import { LitElement, html } from 'lit';
import '@conectate/ct-img';

class MyElement extends LitElement {
  render() {
    return html`
      <ct-img
        src="image.jpg"
        lazy
        alt="My image">
      </ct-img>
    `;
  }
}

Background Size and Position

<!-- Contained background (doesn't crop) -->
<ct-img src="image.jpg" contain alt="Contained image"></ct-img>

<!-- Left-aligned background -->
<ct-img src="image.jpg" background-position="left" alt="Left-aligned image"></ct-img>

<!-- Right-aligned background -->
<ct-img src="image.jpg" background-position="right" alt="Right-aligned image"></ct-img>

API Reference

Properties

| Property | Type | Default | Description | | ---------------------- | ------------- | ----------------- | -------------------------------------- | | src | string | "" | URL of the image to display | | srcset | string | undefined | Source set (use for lazy loading) | | alt | string | "" | Alternative text for accessibility | | lazy | boolean | false | Enables lazy loading | | round | boolean | false | Makes the image circular | | disable_anim | boolean | false | Disables fade-in animations | | intersectionobserver | boolean | false | Forces use of IntersectionObserver | | viewport | HTMLElement | document.body | Scrollable container for lazy loading | | placeholderImg | string | "" | URL of placeholder image while loading | | onErrorSrc | string | "[default SVG]" | URL of image to show on error |

Attributes

| Attribute | Description | | --------------------- | -------------------------------------------------------------- | | contain | Uses background-size: contain instead of cover | | background-position | Position of background: "left", "right", or "center" (default) |

Events

| Event | Description | | ---------------- | -------------------------------------------- | | loaded-changed | Fired when the image has loaded successfully |

CSS Custom Properties

| Property | Description | Default | | ------------------------ | -------------------------- | ------- | | --ct-img-border-radius | Border radius of the image | 0px |

Lazy Loading

For optimal lazy loading, use the srcset attribute instead of src when the lazy attribute is enabled:

<ct-img srcset="image.jpg" lazy alt="Lazy loaded image"></ct-img>

The component will automatically:

1. Use native loading="lazy" if supported by the browser
2. Fall back to IntersectionObserver when native lazy loading is unavailable
3. Automatically load and use a polyfill for IntersectionObserver if needed

Styling Examples

Basic Responsive Image

<style>
	.responsive-img {
		width: 100%;
		height: auto;
		max-width: 800px;
	}
</style>

<ct-img class="responsive-img" src="image.jpg" alt="Responsive image"></ct-img>

Avatar Style

<style>
	.avatar {
		width: 80px;
		height: 80px;
		--ct-img-border-radius: 50%;
		border: 3px solid white;
		box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
	}
</style>

<ct-img class="avatar" src="profile.jpg" alt="User avatar"></ct-img>

Gallery Image

<style>
	.gallery-img {
		width: 300px;
		height: 200px;
		--ct-img-border-radius: 8px;
		transition: transform 0.3s ease;
	}
	.gallery-img:hover {
		transform: scale(1.05);
	}
</style>

<ct-img class="gallery-img" src="gallery-image.jpg" alt="Gallery image"></ct-img>

Performance Tips

• Always use the lazy attribute for images below the fold
• Provide appropriately sized images (don't load huge images for small containers)
• Use the placeholder-img attribute with a low-resolution or blurred version of the image
• Consider using a CDN that can serve optimized images based on device capabilities

Browser Support

• Modern browsers: Chrome, Firefox, Safari, Edge
• For older browsers, a polyfill for IntersectionObserver is automatically loaded as needed

Follow Me

https://x.com/herberthobregon

https://dev.to/herberthobregon

Contributing

1. Fork the repo
2. Create a new branch: git checkout -b feature-branch
3. Commit your changes: git commit -m 'Add new feature'
4. Push to your branch: git push origin feature-branch
5. Open a pull request!

License

See LICENSE