@carrot/design-components-images

Image component CSS classes and TypeScript types for the Carrot Design System. Provides layout and fit styles for image, background image, picture, and SVG components plus framework-agnostic type contracts.

Installation

npm install @carrot/design-components-images

@import "@carrot/design-components-images";

import { ImageFits, ImagePositions, ImageStatuses } from "@carrot/design-components-images/types";
import type { ImageStyleProps, BgImageStyleProps, PictureSource } from "@carrot/design-components-images/types";

Contents

CSS Classes

Component classes defined in @layer kapish.components (file: images.css).

CarrotImage

Class / Selector	Description
.carrot-image	Relative container with overflow hidden
.carrot-image-el	Block-level image element, full width
.carrot-image-el[data-fit="cover"]	object-fit: cover
.carrot-image-el[data-fit="contain"]	object-fit: contain
.carrot-image-el[data-fit="fill"]	object-fit: fill
.carrot-image-el[data-fit="none"]	object-fit: none
.carrot-image-el[data-fit="scale-down"]	object-fit: scale-down
.carrot-image-el[data-lqip]	LQIP blur state (blur 20px + scale 1.1)
.carrot-image-placeholder	Absolute-fill placeholder overlay
.carrot-image-error	Absolute-fill error overlay

CarrotBgImage

Class	Description
.carrot-bg-image	Relative container with overflow hidden, no-repeat bg

CarrotPicture

Class	Description
.carrot-picture	Relative container with overflow hidden
.carrot-picture-el	Block-level image element inside <picture>, full size

CarrotSvg

Class	Description
.carrot-svg	Inline-block wrapper with line-height: 0

TypeScript Types

Image Fit & Position

ImageFits; // ["cover", "contain", "fill", "none", "scale-down"]
ImagePositions; // ["center", "top", "bottom", "left", "right",
//  "top-left", "top-right", "bottom-left", "bottom-right"]

Background Fit & Position

BgFits; // ["cover", "contain", "auto"]
BgPositions; // ["center", "top", "bottom", "left", "right"]

Loading & Performance

ImageLoadingStrategies; // ["lazy", "eager"]
FetchPriorities;        // ["high", "low", "auto"]
ImageDecodings;         // ["async", "sync", "auto"]

Status

ImageStatuses; // ["idle", "loading", "loaded", "error"]

Interfaces

interface ImageDimensions {
  naturalWidth: number;
  naturalHeight: number;
}

interface PictureSource {
  media?: string;
  srcset: string;
  type?: string;
  sizes?: string;
}

interface ImageStyleProps {
  fit?: ImageFit;
  position?: ImagePosition;
  aspect?: string;
  radius?: string;
}

interface BgImageStyleProps {
  fit?: BgFit;
  position?: BgPosition;
  fixed?: boolean;
  aspect?: string;
  radius?: string;
}

interface ImageQueueOptions {
  maxConcurrent?: number;
}

Dist Structure

File	Description
index.css	Barrel -- imports images.css
images.css	Component class definitions
index.js / index.d.ts	TypeScript types + runtime constants

Dependencies

None -- this package is self-contained.

Build

npm run build

---

Usage Guide

Import

@import "@carrot/design-components-images";

import { ImageFits, ImagePositions, ImageStatuses } from "@carrot/design-components-images/types";
import type { ImageStyleProps, BgImageStyleProps, PictureSource } from "@carrot/design-components-images/types";

CSS Classes

This package provides component CSS classes in @layer kapish.components for image layout, fit, LQIP blur, placeholders, and error states.

CarrotImage classes

• .carrot-image -- relative container with overflow hidden
• .carrot-image-el -- block-level image element (full width)
• .carrot-image-el[data-fit="cover|contain|fill|none|scale-down"] -- object-fit variants
• .carrot-image-el[data-lqip] -- LQIP blur state (blur 20px + slight scale)
• .carrot-image-placeholder -- absolute-fill placeholder overlay
• .carrot-image-error -- absolute-fill error overlay

CarrotBgImage classes

• .carrot-bg-image -- relative container with overflow hidden, no-repeat background

CarrotPicture classes

• .carrot-picture -- relative container with overflow hidden
• .carrot-picture-el -- block-level image inside <picture>

CarrotSvg classes

• .carrot-svg -- inline-block SVG wrapper with line-height: 0

TypeScript Types

• ImageFit: cover · contain · fill · none · scale-down
• ImagePosition: center · top · bottom · left · right · top-left · top-right · bottom-left · bottom-right
• BgFit: cover · contain · auto
• ImageLoadingStrategy: lazy · eager
• FetchPriority: high · low · auto
• ImageStatus: idle · loading · loaded · error

Examples

CarrotImage with fit and LQIP

<!-- Image container with cover fit -->
<div class="carrot-image">
  <img class="carrot-image-el" data-fit="cover" src="/hero.jpg" alt="Hero" />
</div>

<!-- Image with LQIP blur placeholder (blur removed when high-res loads) -->
<div class="carrot-image">
  <img class="carrot-image-el" data-fit="cover" data-lqip src="/hero-lqip.jpg" alt="" />
  <img class="carrot-image-el" data-fit="cover" src="/hero.jpg" alt="Hero" />
</div>

<!-- Image with placeholder and error states -->
<div class="carrot-image">
  <div class="carrot-image-placeholder">Loading...</div>
  <div class="carrot-image-error">Failed to load</div>
  <img class="carrot-image-el" data-fit="contain" src="/photo.jpg" alt="Photo" />
</div>

CarrotBgImage

<div class="carrot-bg-image" style="background-image: url('/bg.jpg'); background-size: cover; aspect-ratio: 16/9;" role="img" aria-label="Background"></div>

CarrotPicture

<div class="carrot-picture">
  <picture>
    <source srcset="/hero.avif" type="image/avif" />
    <source srcset="/hero.webp" type="image/webp" />
    <img class="carrot-picture-el" src="/hero.jpg" alt="Hero" />
  </picture>
</div>

CarrotSvg

<span class="carrot-svg" style="width: 24px; height: 24px;">
  <svg viewBox="0 0 24 24"><!-- icon --></svg>
</span>

TypeScript usage — building a component

import type { ImageStyleProps, PictureSource } from "@carrot/design-components-images/types";

// Use ImageStyleProps to type your component's props
function buildImageStyle(props: ImageStyleProps): Record<string, string> {
  return {
    objectFit: props.fit ?? "cover",
    objectPosition: props.position ?? "center",
    ...(props.aspect ? { aspectRatio: props.aspect } : {}),
    ...(props.radius ? { borderRadius: props.radius } : {}),
  };
}

Loading state tracking

import { ImageStatuses } from "@carrot/design-components-images/types";
import type { ImageStatus } from "@carrot/design-components-images/types";

let status: ImageStatus = "idle";

const img = document.querySelector("img")!;
img.addEventListener("load", () => { status = "loaded"; });
img.addEventListener("error", () => { status = "error"; });

With Vue

Use @carrot/design-vue-images for <SbImage>, <SbBgImage>, and <SbPicture> components that accept ImageStyleProps / BgImageStyleProps as props and handle responsive loading, error fallbacks, and status tracking automatically.