Skip to content

Image (Visual Content) Components

Phantom Image (Visual Content) Components provide a powerful, flexible and unique way to display images in your documentation with features like lazy-loading, lightbox support and responsive layouts.

Component Features

  • Lazy Loading: Images load only when entering viewport
  • Lightbox Support: Full-screen image viewing
  • Responsive Design: Adapts to different screen sizes
  • Flexible Positioning: Float left, right, or center
  • Grid Layouts: Display multiple images efficiently

Image Path Resolution

Images are automatically resolved from the /assets/static/images/ directory. Simply use the filename:

  • data-src="example.png" → /assets/static/images/example.png
  • For absolute paths, start with /: data-src="/custom/path/image.png"
  • For external images, use full URLs: data-src="https://example.com/image.png"

Basic Usage

Simple Image

The most basic usage - just provide the image source:

Image with Caption

Add context to your images with captions:

Size Variants

Control the display size of your images:

Small Image

Medium Image (Default)

Large Image

Full Width Image

Positioning with Text

Images can be positioned to flow with your text content:

Left-Aligned Image

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

Right-Aligned Image

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Click on images with lightbox enabled to view them in full screen:

Image Grid

Display multiple images in a responsive grid layout:

Image Comparison

Compare two images side by side:

Advanced Usage

Tutorial with Images

Step 1: Open Settings

First, navigate to the settings page by clicking the gear icon in the top right corner. The settings page contains all configuration options for your application.

You'll find various sections including general settings, appearance, and advanced options.

Step 2: Configure Options

In the configuration panel, you can adjust various settings according to your needs. Each option has a tooltip that explains its function.

Make sure to save your changes before leaving the page.

Feature Showcase

Advanced Image Processing

Our image component provides state-of-the-art features for displaying images in documentation:

  • Automatic lazy loading for performance
  • Responsive sizing and positioning
  • Built-in lightbox functionality

Configuration Options

Data Attributes

Attribute Type Default Description
data-src string required Image source URL
data-alt string "" Alternative text for accessibility
data-caption string null Caption text below image
data-size string "medium" Size variant: small, medium, large, full
data-position string "center" Position: left, right, center
data-loading string "lazy" Loading strategy: lazy, eager
data-lightbox boolean false Enable lightbox on click

Error States

Failed Image Load

When an image fails to load, the component displays a clear error message:

Loading State

While images are loading, a spinner is displayed. Here's an example with a larger image that demonstrates the loading state:

Best Practices

  1. Always provide alt text: Essential for accessibility and SEO
  2. Use appropriate sizes: Choose the right size variant for your content
  3. Enable lightbox for detailed images: Let users see full resolution when needed
  4. Add captions for context: Help users understand what they're looking at
  5. Optimize your images: Use appropriate formats and compression
  6. Consider mobile users: Test how images appear on smaller screens

Troubleshooting

Image Not Loading

  • Check that data-src points to a valid image URL
  • Ensure the image file exists and is accessible
  • Check browser console for error messages
  • For local images, verify they're in /docs/assets/static/images/
  • Verify data-lightbox="true" is set
  • Check that JavaScript is enabled
  • Ensure phantom-image.js is loaded
  • Confirm the image loaded successfully (lightbox is disabled for failed images)

Layout Issues

  • Check that parent containers have appropriate width
  • Test responsive behavior on different screen sizes
  • Test responsive behavior at different screen sizes