ScreenshotNeo
Sign in Get a free key

BlogGuides

Puppeteer Locator Fill Options Explained

Learn how Puppeteer Locator.fill() accepts strings, booleans, and version-sensitive options, with runnable examples and fixes for common issues.

By the ScreenshotNeo team4 October 20266 min read

Locator.fill(value, options?) fills the element found by a Puppeteer locator and returns Promise<void>. Use a string for text-like controls and a boolean for checkbox, radio-button, and switch targets. The one detailed option covered here, typingThreshold, appears in Puppeteer’s /next/ documentation; check the docs for your installed version before relying on it.

1. The method signature and supported values

The Puppeteer 25.12.0 method reference gives this signature:

fill<ElementType extends Element>(
  this: Locator<ElementType>,
  value: string | boolean,
  options?: Readonly<LocatorFillOptions>,
): Promise<void>

Puppeteer determines the target type at runtime and chooses a fill method for the documented element types:

Target Value Example
input, textarea, select, or contenteditable String 'reader@example.com'
Checkbox, radio button, or switch Boolean true or false

This documented support list does not mean that every custom form widget can be filled directly. For a custom control, use the interaction its implementation supports and verify the resulting state.

2. Complete runnable example

This Node.js example opens a local page, fills a text input and a contenteditable element, sets a checkbox, and reads their resulting values. Install Puppeteer with npm install puppeteer, save as fill.mjs, then run node fill.mjs.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
try {
  const page = await browser.newPage();
  await page.setContent(`
    <label>Email <input name="email"></label>
    <div contenteditable="true" data-testid="note"></div>
    <label><input type="checkbox" name="updates"> Updates</label>
  `);

  await page.locator('input[name="email"]').fill('reader@example.com');
  await page.locator('[data-testid="note"]').fill('Please send the report.');
  await page.locator('input[name="updates"]').fill(true);

  const result = await page.evaluate(() => ({
    email: document.querySelector('[name="email"]').value,
    note: document.querySelector('[data-testid="note"]').textContent,
    updates: document.querySelector('[name="updates"]').checked,
  }));
  console.log(result);
} finally {
  await browser.close();
}

Expected output includes the entered email, note text, and updates: true. The call resolves when the fill operation completes; it does not return the field value.

3. The optional fill setting: typingThreshold

The official next-version LocatorFillOptions reference lists typingThreshold?: number, with a documented default of 100. It describes the number of characters to type before switching to a faster fill-out method.

await page.locator('input[name="email"]').fill('reader@example.com', {
  typingThreshold: 100,
});

Passing 100 explicitly is generally unnecessary when using a release whose behavior matches that reference. The detailed property was found on the next-version page, so do not assume it exists in every released Puppeteer version. Check the API reference matching your installed package. This documentation does not establish a performance guarantee or a particular event sequence for the faster method.

The reviewed released-version options reference did not provide a detailed list of other LocatorFillOptions properties. In particular, do not assume that timeout belongs in the fill options object.

4. How locator readiness and timeouts work

Locators are strategies for finding objects and performing actions. Puppeteer checks preconditions, and retries an operation when the target is not ready. A fill that waits is therefore often a readiness or timeout issue, rather than a problem with the string or boolean.

Use locator controls when you need to adjust the wait behavior. For example, set a total timeout on the locator:

const email = page.locator('input[name="email"]').setTimeout(10_000);
await email.fill('reader@example.com');

setTimeout(timeout) returns a cloned locator configured with the timeout for locator actions. Zero disables that locator timeout; the documented default comes from Page.getDefaultTimeout(). See the Locator class reference and Locator.setTimeout() reference for the available readiness controls and version-specific details. The timeout is not a LocatorFillOptions field.

5. cURL, Python, and ScreenshotNeo

Locator.fill() is a Puppeteer browser API, so cURL and Python do not call that JavaScript method directly. Use the Node.js examples above when you need to automate a browser form. For a screenshot of the resulting page, you can capture it through ScreenshotNeo’s HTTP API.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request parameters and response details. ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Its screenshot capture does not execute your Puppeteer form interaction; navigate to or prepare the page as needed before requesting a screenshot.

6. Troubleshooting

Symptom Likely cause What to do
The fill call times out The locator did not resolve to a ready target before the configured timeout. Check the selector and whether the element appears, is enabled, and is in the expected frame. Review page and locator timeout settings.
typingThreshold is rejected or has no effect The installed release may not expose the option documented on /next/. Check the reference for your installed Puppeteer version. Omit the option if that release does not support it.
A custom dropdown or widget does not change The element is not one of the documented native fill targets, or it uses custom interaction behavior. Inspect the widget and use its supported click, keyboard, or other interaction path; verify the resulting state.
A checkbox ends in the wrong state The target selector may match a different control, or the page may update the control after interaction. Use a specific locator, pass the intended boolean, then inspect the checked state and any application-level result.
The field value is right but the application does not update The application may depend on behavior beyond the documented fill result. Check the application’s own control behavior and confirm its state after filling. Do not infer a specific event sequence from typingThreshold.
The code cannot find page.locator The installed Puppeteer version or API surface differs from the referenced docs. Confirm the installed package version and consult its matching Locator documentation.

7. Reliability, performance, and cost

  • Reliability: Use selectors that identify the intended control, allow locator preconditions to handle normal readiness, and set a timeout appropriate to the page. Confirm application state when a successful fill alone is not enough.
  • Performance: The next-version documentation describes typingThreshold as switching to a faster fill-out method after a character count. It does not promise a speedup for a particular page or define additional event guarantees. Avoid tuning it without checking version compatibility and the behavior your application needs.
  • Cost: Puppeteer is the browser automation step in this example; ScreenshotNeo is an optional screenshot service with a separate API and plans. ScreenshotNeo offers 1,000 shots per month free with no card; paid plans start at $5 for 3,000 shots. Only clean shots are billed, and its responses report page verdict and billing headers. See the docs for API usage.

8. Or skip the browser setup

If your goal is a clean screenshot of a page, ScreenshotNeo takes a URL in one API request. It is a separate capture path; use Puppeteer when you need to fill and submit a form as part of browser automation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots each month with no card, and paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

9. FAQ

Does fill() return the entered value?

No. Its documented return type is Promise<void>. Read the control separately if you need to assert its value.

Can I pass a number to fill()?

The documented value type is string | boolean. Convert numeric text to a string for a text field.

Where is typingThreshold documented?

It appears in the next-version LocatorFillOptions reference. Verify support against the documentation for your installed release.

Can ScreenshotNeo fill a form with Locator.fill()?

No. ScreenshotNeo captures website screenshots and PDFs through its API or MCP server; Puppeteer performs the browser form interaction.

Official references

Keep reading

7 min read

LinkedIn Open to Work Image

Learn what LinkedIn’s Open to Work photo frame means, who can see it, how to add or remove it, and how to choose the right privacy setting.