Progressive-Acrylic

API Reference

Complete reference for Progressive Acrylic functions, parameters, and configuration options.

Table of Contents

Main Function

progressiveAcrylic(target, options)

Creates a layered acrylic effect on the specified element.

Parameters

Parameter Type Required Description
target HTMLElement ✅ The DOM element to apply the acrylic effect to
options Object ❌ Configuration object for customizing the effect

Returns

Returns an object with control methods:

{
  update: (newOptions: Object) => void,
  destroy: () => void
}

Example

const element = document.getElementById('myElement');
const acrylic = progressiveAcrylic(element, {
  blur: {
    enabled: true,
    maxBlur: 200,
    height: '50%'
  }
});

Configuration Object

The configuration object follows this structure:

interface AcrylicOptions {
  blur?: BlurLayerOptions;
  luminosity?: LuminosityLayerOptions;
  tint?: TintLayerOptions;
  noise?: NoiseLayerOptions;
}

Default Configuration

const defaultOptions = {
  blur: {
    enabled: true,
    direction: 'bottom',
    height: '60%',
    layers: 8,
    maxBlur: 40,
    startOpacity: 0,
    endOpacity: 1,
    position: 'bottom',
    curve: [0.25, 0.46, 0.45, 0.94]
  },
  luminosity: {
    enabled: false,
    brightness: 1.1,
    contrast: 1.05,
    saturate: 1.2,
    opacity: 0.8,
    blendMode: 'normal'
  },
  tint: {
    enabled: false,
    color: '#ffffff',
    gradient: null,
    opacity: 0.1,
    blendMode: 'overlay'
  },
  noise: {
    enabled: false,
    opacity: 0.3,
    blendMode: 'multiply'
  }
};

Layer Options

Blur Layer Options

Property Type Default Range/Values Description
enabled boolean true true | false Enable/disable the blur layer
direction string 'bottom' 'top' | 'bottom' | 'left' | 'right' Direction of blur fade
height string '60%' '10%' - '100%' Height of blur area
layers number 8 3 - 20 Number of blur layers
maxBlur number 40 0 - 1000 Maximum blur amount in pixels
startOpacity number 0 0 - 1 Starting opacity of gradient
endOpacity number 1 0 - 1 Ending opacity of gradient
position string 'bottom' 'top' | 'bottom' Vertical position of blur area
curve number[] [0.25, 0.46, 0.45, 0.94] Cubic-bezier values Distribution curve for layers

Blur Layer Example

blur: {
  enabled: true,
  direction: 'top',
  height: '40%',
  layers: 6,
  maxBlur: 150,
  startOpacity: 0,
  endOpacity: 0.9,
  position: 'top',
  curve: [0.62, 0.123, 0.92, 0.002]
}

Direction Values

Position Values

Curve Values

Accepts either an array of cubic-bezier values [x1, y1, x2, y2] or predefined strings:

Luminosity Layer Options

Property Type Default Range/Values Description
enabled boolean false true | false Enable/disable the luminosity layer
brightness number 1.1 0 - 2 Brightness adjustment
contrast number 1.05 0 - 2 Contrast adjustment
saturate number 1.2 0 - 3 Saturation adjustment
opacity number 0.8 0 - 1 Layer opacity
blendMode string 'normal' CSS blend modes Mix blend mode

Luminosity Layer Example

luminosity: {
  enabled: true,
  brightness: 1.2,
  contrast: 1.1,
  saturate: 1.3,
  opacity: 0.9,
  blendMode: 'overlay'
}

Blend Mode Values

Common blend modes for luminosity layer:

Tint Layer Options

Property Type Default Range/Values Description
enabled boolean false true | false Enable/disable the tint layer
color string '#ffffff' Hex color Solid color overlay
gradient object | null null Gradient object Linear gradient configuration
opacity number 0.1 0 - 1 Layer opacity
blendMode string 'overlay' CSS blend modes Mix blend mode

Tint Layer Example (Solid Color)

tint: {
  enabled: true,
  color: '#3498db',
  opacity: 0.2,
  blendMode: 'overlay'
}

Tint Layer Example (Gradient)

tint: {
  enabled: true,
  gradient: {
    direction: 'to bottom',
    colors: [
      { color: '#ffffff', stop: 0, opacity: 0.3 },
      { color: '#000000', stop: 50, opacity: 0.1 },
      { color: '#3498db', stop: 100, opacity: 0.5 }
    ]
  },
  opacity: 1,
  blendMode: 'overlay'
}

Gradient Object Structure

interface GradientOptions {
  direction: string;  // CSS gradient direction
  colors: Array<{
    color: string;    // Hex color value
    stop: number;     // Position (0-100)
    opacity: number;  // Individual opacity (0-1)
  }>;
}

Gradient Direction Values

Noise Layer Options

Property Type Default Range/Values Description
enabled boolean false true | false Enable/disable the noise layer
opacity number 0.3 0 - 1 Layer opacity
blendMode string 'multiply' CSS blend modes Mix blend mode

Noise Layer Example

noise: {
  enabled: true,
  opacity: 0.4,
  blendMode: 'overlay'
}

Noise Blend Mode Values

Recommended blend modes for noise texture:

Return Object

The progressiveAcrylic() function returns an object with control methods:

update(newOptions)

Updates the acrylic effect with new configuration options.

Parameters

Parameter Type Required Description
newOptions Object ✅ Partial configuration object with new options

Example

const acrylic = progressiveAcrylic(element, initialOptions);

// Update only blur settings
acrylic.update({
  blur: { maxBlur: 300, height: '70%' }
});

// Update multiple layers
acrylic.update({
  blur: { maxBlur: 200 },
  tint: { color: '#ff3498', opacity: 0.3 },
  noise: { enabled: true }
});

destroy()

Completely removes the acrylic effect and cleans up all layers.

Example

const acrylic = progressiveAcrylic(element, options);

// Later, when component unmounts or effect is no longer needed
acrylic.destroy();

Utility Functions

Built-in Presets

You can use predefined configurations for common styles:

// iOS-style acrylic
progressiveAcrylic(element, acrylicPresets['ios-default']);

// Windows acrylic
progressiveAcrylic(element, acrylicPresets['windows-acrylic']);

// Glass morphism
progressiveAcrylic(element, acrylicPresets['glass-morphism']);

Feature Detection

// Check if backdrop-filter is supported
const supportsBackdropFilter = CSS.supports('backdrop-filter', 'blur(1px)');

if (supportsBackdropFilter) {
  progressiveAcrylic(element, options);
} else {
  // Apply fallback styles
}

Type Definitions

Here are TypeScript type definitions for better IDE support:

interface AcrylicOptions {
  blur?: {
    enabled?: boolean;
    direction?: 'top' | 'bottom' | 'left' | 'right';
    height?: string;
    layers?: number;
    maxBlur?: number;
    startOpacity?: number;
    endOpacity?: number;
    position?: 'top' | 'bottom';
    curve?: [number, number, number, number];
  };
  luminosity?: {
    enabled?: boolean;
    brightness?: number;
    contrast?: number;
    saturate?: number;
    opacity?: number;
    blendMode?: string;
  };
  tint?: {
    enabled?: boolean;
    color?: string;
    gradient?: {
      direction: string;
      colors: Array<{
        color: string;
        stop: number;
        opacity: number;
      }>;
    } | null;
    opacity?: number;
    blendMode?: string;
  };
  noise?: {
    enabled?: boolean;
    opacity?: number;
    blendMode?: string;
  };
}

interface AcrylicInstance {
  update: (newOptions: Partial<AcrylicOptions>) => void;
  destroy: () => void;
}

declare function progressiveAcrylic(
  target: HTMLElement,
  options?: AcrylicOptions
): AcrylicInstance;

Error Handling

Progressive Acrylic includes built-in error handling:

try {
  const acrylic = progressiveAcrylic(element, options);
} catch (error) {
  console.error('Progressive Acrylic Error:', error.message);
  
  // Common error types:
  // - Invalid target element
  // - Unsupported browser
  // - Invalid configuration values
}

Performance Considerations

Optimization Guidelines

  1. Layer Count: Use 6-8 layers for optimal performance
  2. Blur Amount: Keep maxBlur under 300px for better performance
  3. Multiple Effects: Limit simultaneous acrylic areas
  4. Update Frequency: Avoid rapid successive updates

Performance Monitoring

const startTime = performance.now();
const acrylic = progressiveAcrylic(element, options);
const endTime = performance.now();

console.log(`Acrylic creation took ${endTime - startTime} milliseconds`);

For more examples and tutorials, see the Examples Guide and Custom Effects.

This site is open source. Improve this page.