frame.addStyleTag() adds CSS to the frame represented by that Puppeteer Frame object. Pass content for CSS text, path for a local CSS file, or url for a stylesheet URL. Use the frame method when the CSS belongs in a particular frame; page.addStyleTag() is the shortcut for the page’s main frame.
Choose the stylesheet input
The documented options are content, path, and url. Each is optional in the interface, but for predictable results, provide just the one source form you intend to use. The API references do not specify precedence or validation behavior when multiple fields are supplied together.
| Option | Use it for | What Puppeteer receives |
|---|---|---|
content |
CSS authored in your script | A string containing raw CSS |
path |
A stylesheet stored locally | A CSS file path; a relative path resolves from Node.js process.cwd() |
url |
A stylesheet available at a URL | The URL of a CSS file, represented by a link element |
Inline CSS: content
Use content when the CSS is short, generated dynamically, or already available as a string.
await frame.addStyleTag({
content: 'body { background: #f5f5f5; }'
});Local CSS: path
Use path to load a stylesheet from the machine running the Node.js process. Relative paths are based on the process working directory, not the page URL and not necessarily the directory containing the script. An absolute path avoids uncertainty about the working directory.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
await frame.addStyleTag({
path: '/absolute/path/to/test.css'
});Remote CSS: url
Use url to link a stylesheet by URL. The URL overload produces a link element rather than an inline style element.
await frame.addStyleTag({
url: 'https://example.com/test.css'
});Target the frame that should receive the CSS
Call addStyleTag() on the Frame you want to modify. A page can contain a main frame and child frames; adding a stylesheet to one frame does not mean it has been added to every other frame.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
If the target is the main frame, page.addStyleTag(options) is a convenience shortcut equivalent to page.mainFrame().addStyleTag(options). For a particular child frame, use that frame’s method instead.
What the method returns
The method returns a promise for a handle to the loaded element. In the documented overloads, options without url return an ElementHandle<HTMLStyleElement>; the URL overload returns an ElementHandle<HTMLLinkElement>. This distinction reflects how the stylesheet is represented: style element for the non-URL form and link element for the URL form.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
Common problems and fixes
- The CSS file cannot be found: Check the Node process’s current working directory and the path spelling. Use an absolute path if the code may run from different directories.
- The stylesheet affects the wrong content: Confirm that you called the method on the intended frame.
page.addStyleTag()targets the main frame, not an arbitrary child frame. - The returned element is not the type expected: A URL-backed stylesheet uses a link element; the other documented overload uses a style element.
- Several option fields are being passed together: The references do not define which field takes precedence or how combinations are validated. Pass only the intended source and check the API reference for the Puppeteer version installed in your project.
Version considerations
Puppeteer’s API references can render different documentation versions: the options interface page showed version 25.3.0, the Frame method page 25.9.0, and the Page method page 25.11.0 at the time those pages were reviewed. Documentation may change over time, so compare the method and option types with the version of Puppeteer your project actually uses.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is to produce a webpage screenshot rather than modify a particular Puppeteer frame, ScreenshotNeo provides a screenshot API. Its custom-CSS option can apply CSS to a capture, but that is not a replacement for choosing a specific Puppeteer frame with Frame.addStyleTag().
Quick Recap
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Example cURL request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000. Sign up for the free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
