Vibe

Appearance

@vibe-labs/design-components-images ​

Image component TypeScript types for the Vibe Design System. Provides framework-agnostic type contracts for image and background image components.

Installation ​

bash
npm install @vibe-labs/design-components-images
ts
import { ImageFits, ImagePositions, ImageStatuses } from "@vibe-labs/design-components-images/types";
import type { ImageStyleProps, BgImageStyleProps, PictureSource } from "@vibe-labs/design-components-images/types";

Contents ​

TypeScript Types ​

All types are defined in types/ and exported from index.js / index.d.ts. There are no CSS tokens or generated styles — index.css is reserved for future use.

Image Fit & Position ​

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

Background Fit & Position ​

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

Loading & Performance ​

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

Status ​

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

Interfaces ​

ts
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 ​

FileDescription
index.cssEmpty (reserved for future component styles)
index.js / index.d.tsTypeScript types + runtime constants

Dependencies ​

None — this package is self-contained.

Build ​

bash
npm run build

Usage Guide ​

Import ​

This package is type-only. There are no CSS classes to import.

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

Variants ​

This package provides TypeScript type contracts — no data-attribute variant system. The types are consumed by Vue/framework components that translate props to native HTML attributes (object-fit, object-position, loading, fetchpriority, decoding).

Key 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 ​

Plain HTML image (manual attributes) ​

html
<!-- Lazy-loaded cover image — set styles directly on the img element -->
<img
  src="/hero.jpg"
  alt="Hero image"
  loading="lazy"
  decoding="async"
  style="width: 100%; height: 300px; object-fit: cover; object-position: center"
/>

Responsive picture element ​

html
<!-- <picture> with multiple sources — PictureSource type documents srcset/type/sizes/media -->
<picture>
  <source
    srcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
    type="image/avif"
    sizes="(max-width: 768px) 100vw, 50vw"
  />
  <source
    srcset="/hero-800.webp 800w, /hero-1600.webp 1600w"
    type="image/webp"
    sizes="(max-width: 768px) 100vw, 50vw"
  />
  <img src="/hero-800.jpg" alt="Hero" loading="lazy" />
</picture>

Background image ​

html
<!-- Background image div — BgImageStyleProps documents fit, position, fixed, aspect, radius -->
<div
  style="
    background-image: url('/bg.jpg');
    background-size: cover;
    background-position: center;
    aspect-ratio: 16 / 9;
    border-radius: var(--radius-lg);
  "
  role="img"
  aria-label="Background image"
></div>

TypeScript usage — building a component ​

ts
import type { ImageStyleProps, PictureSource } from "@vibe-labs/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 ​

ts
import { ImageStatuses } from "@vibe-labs/design-components-images/types";
import type { ImageStatus } from "@vibe-labs/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 @vibe-labs/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.

Vibe