Scroll Height Control

The Screenshots API allows you to control the vertical scroll position of a webpage before capturing the screenshot. This is particularly useful for:

• Capturing specific sections of a long page
• Ensuring important content is in view
• Testing responsive layouts at different scroll positions
• Validating infinite scroll implementations

How Scroll Height Works

1. You specify the desired scroll height using the scroll parameter
2. The API scrolls the page to that position before taking the screenshot
3. The screenshot is captured after any animations or content loading completes

Basic Usage

Here's how to use the scroll height feature:

async function takeScrolledScreenshot() {
  const params = new URLSearchParams({
    url: 'https://example.com',
    fmt: 'png',
    scroll: '800', // Scroll to 800 pixels from top
    wait: 1000,    // Wait 1 second after scrolling
    qual: 80,
    full: false,
    ads: true,
    cookie: true,
    track: true,
    clear: true,
    device: 'desktop',
    dark: false,
    width: 1920,
    height: 1080
  });
 
  const response = await fetch(`https://api.screenshotsapi.dev/take?${params}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const result = await response.json();
  console.log('Screenshot captured:', result.message);
  console.log('URL:', result.url);
  console.log('Duration:', result.duration, 'ms');
  console.log('Timestamp:', result.timestamp);
  
  return result;
}

Scroll Height Options

The scroll parameter supports several formats:

1. Pixel Value:

   • scroll=800 - Scrolls to 800 pixels from the top
   • scroll=0 - Stays at the top of the page
   • scroll=2000 - Scrolls to 2000 pixels from the top

2. Special Values:

   • scroll=auto - Uses the default scroll position (usually top)
   • scroll=bottom - Scrolls to the bottom of the page

3. Percentage:

   • scroll=50% - Scrolls to 50% of the page height
   • scroll=75% - Scrolls to 75% of the page height

Best Practices

1. Wait Time:

   • Always use the wait parameter with scroll to allow time for:
     • Content to load after scrolling
     • Animations to complete
     • Lazy-loaded images to appear
   • Recommended minimum wait: 500ms

2. Viewport Height:

   • Consider the viewport height (height parameter) when using scroll
   • Ensure important content will be visible in the viewport
   • Test with different viewport sizes

3. Full Page Screenshots:

   • When full=true, scroll position affects initial render
   • Useful for ensuring specific content is loaded before capture
   • Can be combined with wait for better results

4. Error Handling:

   • Validate scroll values before sending
   • Handle cases where page is shorter than scroll value
   • Consider fallback options for different page lengths

Common Use Cases

1. Content Verification:

   • Capture specific sections of long pages
   • Verify content at different scroll positions
   • Test dynamic content loading

2. Performance Testing:

   • Check lazy loading behavior
   • Verify scroll-based animations
   • Test infinite scroll implementations

3. Layout Testing:

   • Verify fixed/sticky elements
   • Test floating navigation
   • Check responsive behavior at different scroll positions

4. User Experience:

   • Document user journey steps
   • Capture specific user interactions
   • Test scroll-triggered features

Example: Capturing Multiple Sections

Here's an example of capturing the same page at different scroll positions:

async function capturePageSections() {
  const scrollPositions = ['0', '800', '1600', 'bottom'];
  const screenshots = [];
  
  for (const scroll of scrollPositions) {
    const params = new URLSearchParams({
      url: 'https://example.com',
      scroll,
      wait: 1000,
      // ... other parameters
    });
    
    const result = await takeScreenshot(params);
    screenshots.push({
      scroll,
      ...result
    });
  }
  
  return screenshots;
}

Next Steps

• Learn about advanced features
• Explore bulk screenshot capabilities
• Check out the API reference for detailed documentation