Imgproxy Loader

This integration allows you to use Imgproxyfor image optimization. For more details, refer to the official documentation.

Module import

import * as Imgproxy from '@lonik/oh-image/imgproxy'

URL Schema

The loader generates URLs following this pattern:

URL Schema

<path>/<params>/plain/<src>

useImgproxyLoader

The primary hook for generating the loader function. It accepts configuration options (including transforms and placeholder settings) and returns a function that generates the final image URL. Pass this result to the loader prop of the Image component.

Using useImgproxyLoader

import { useImgproxyLoader } from '@lonik/oh-image/imgproxy';
import { Image } from '@lonik/oh-image/react'

function MyComponent() {
  const loader = useImgproxyLoader(
  {
    transforms: {
      format: "webp",
    },
    placeholder: {
      quality: 10,
      format: "webp",
    },
    signature:undefined
  },
  );

  return (
    <Image
      src="image.jpg"
      width={500}
      loader={loader}
      placeholder={true}
    />
  );
}

ImgproxyLoaderProvider

A Context Provider that configures global options for all child components using this loader. This is the recommended way to set the base path/URL and default transforms.

Configuring ImgproxyLoaderProvider

import { ImgproxyLoaderProvider } from '@lonik/oh-image/imgproxy';

function App() {
  return (
    <ImgproxyLoaderProvider
      path="https://example.com/images"
      transforms={OPTIONS}
      placeholder={PLACEHOLDER_OPTIONS}
    >
      <MyApp />
    </ImgproxyLoaderProvider>
  );
}

useImgproxyContext

Returns the global configuration of the loader.

Global Defaults

By default the loader is configured with the following properties:

Imgproxy Loader Default Config

  {
    transforms: {
      format: "webp",
    },
    placeholder: {
      quality: 10,
      format: "webp",
    },
    signature:undefined
  },
  

Global Options

Everything in transformation options in addition to:

Imgproxy Loader Global Options

export interface ImgproxyGlobalOptions {
  /**
   * If `undefined`, won't set anything (this is for backward compatibility and will be removed in future versions, where by default it will be "insecure").
   * - `"insecure"` sets it to insecure
   * - `string` sets the custom signature
   */
  signature?: "insecure" | (string & {});
}

Transforms Option

Below is the transformation options for this loader.

Imgproxy Loader Interface

type ResizeType = "fit" | "fill" | "fill-down" | "force" | "auto";
type ResizeAlgorithm = "nearest" | "linear" | "cubic" | "lanczos2" | "lanczos3";
type GravityType =
  | "no"
  | "so"
  | "ea"
  | "we"
  | "noea"
  | "nowe"
  | "soea"
  | "sowe"
  | "ce";

interface ResizeOptions {
  resizing_type?: ResizeType;
  width?: number;
  height?: number;
  enlarge?: boolean;
  extend?: boolean;
}

interface SizeOptions {
  width?: number;
  height?: number;
  enlarge?: boolean;
  extend?: boolean;
}

interface ExtendOptions {
  extend?: boolean;
  gravity?: GravityType;
}

interface GravityOptions {
  type: GravityType;
  x_offset?: number;
  y_offset?: number;
}

interface CropOptions {
  width: number;
  height: number;
  gravity?: GravityType;
}

interface TrimOptions {
  threshold: number;
  color?: string;
  equal_hor?: boolean;
  equal_ver?: boolean;
}

interface PaddingOptions {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}

interface BackgroundOptions {
  r: number;
  g: number;
  b: number;
}

interface AdjustOptions {
  brightness?: number;
  contrast?: number;
  saturation?: number;
}

interface BlurDetectionsOptions {
  sigma: number;
  class_names: string[];
}

interface DrawDetectionsOptions {
  draw: boolean;
  class_names: string[];
}

interface WatermarkOptions {
  opacity: number;
  position?: GravityType | "re";
  x_offset?: number;
  y_offset?: number;
  scale?: number;
}

interface WatermarkSizeOptions {
  width: number;
  height: number;
}

interface UnsharpeningOptions {
  mode?: string;
  weight?: number;
  dividor?: number;
}

interface AutoqualityOptions {
  method?: string;
  target?: number;
  min_quality?: number;
  max_quality?: number;
  allowed_error?: number;
}

interface JpegOptions {
  progressive?: boolean;
  no_subsample?: boolean;
  trellis_quant?: boolean;
  overshoot_deringing?: boolean;
  optimize_scans?: boolean;
  quant_table?: number;
}

interface PngOptions {
  interlaced?: boolean;
  quantize?: boolean;
  quantization_colors?: number;
}

export interface ImgproxyTransforms {
  resize?: ResizeOptions;
  size?: SizeOptions;
  resizing_type?: ResizeType;
  resizing_algorithm?: ResizeAlgorithm;
  width?: number;
  height?: number;
  "min-width"?: number;
  "min-height"?: number;
  zoom?: number | { x: number; y: number };
  dpr?: number;
  enlarge?: boolean;
  extend?: boolean | ExtendOptions;
  gravity?: GravityOptions;
  crop?: CropOptions;
  trim?: TrimOptions;
  padding?: PaddingOptions;
  auto_rotate?: boolean;
  rotate?: number;
  background?: string | BackgroundOptions;
  background_alpha?: number;
  adjust?: AdjustOptions;
  brightness?: number;
  contrast?: number;
  saturation?: number;
  blur?: number;
  sharpen?: number;
  pixelate?: number;
  unsharpening?: UnsharpeningOptions;
  blur_detections?: BlurDetectionsOptions;
  draw_detections?: DrawDetectionsOptions;
  watermark?: WatermarkOptions;
  watermark_url?: string;
  watermark_text?: string;
  watermark_size?: WatermarkSizeOptions;
  style?: string;
  strip_metadata?: boolean;
  keep_copyright?: boolean;
  strip_color_profile?: boolean;
  enforce_thumbnail?: boolean;
  return_attachment?: boolean;
  quality?: number;
  format_quality?: Record<string, number>;
  autoquality?: AutoqualityOptions;
  max_bytes?: number;
  jpeg_options?: JpegOptions;
  png_options?: PngOptions;
  format?: string;
  page?: number;
  video_thumbnail_second?: number;
  fallback_image_url?: string;
  skip_processing?: string[];
  cachebuster?: string;
  expires?: number;
  filename?: string;
  preset?: string[];
}