examples

module

v0.19.2 Latest Latest Go to latest Published: Oct 4, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/chromedp/examples

Links

Open Source Insights

README ¶

About chromedp examples

This repository holds 43 example programs for chromedp, a Go package that drives Chrome through the Chrome DevTools Protocol. The package documentation has small examples that are self-contained. These programs are larger. Some of them need the internet or an external component.

The programs use the typed API of chromedp v0.19.0 and cdproto v0.157.5. The file docs/API.md in the chromedp repository shows the old code and the new code side by side. The file docs/MIGRATION.md in the same folder lists every name that changed. See the decision for the port.

Build and run

The module needs Go 1.27. It requires chromedp v0.19.0, cdproto v0.157.5 and chromedp/remote v0.1.0, and Go downloads them when you build a program. The programs use remote for the flag -visible, which keeps the browser open, and for the remote program.

The tags of this repository follow the tags of chromedp. The tag v0.19.0 holds programs that use chromedp v0.19, and a tag such as v0.19.1 is a later change in this repository.

chromedp starts the browser. It finds Chrome or Chromium on the PATH. If Chrome has another name, link it to the name google-chrome in a folder on the PATH. Run a program from the root of this repository:

# run the program <prog>, for example go run ./click
$ go run ./<prog>

# build the program <prog>
$ go build -o /tmp/<prog> ./<prog> && /tmp/<prog>

Every program accepts the flag -v. It prints the protocol messages between the program and the browser. Without -v, a program prints only its own output. For example, go run ./cookie -v shows the protocol messages. Run go run ./<prog> -h to see all flags of a program. Put the flags of a program after its folder, as in go run ./multi -out out <url>.

Every program except remote accepts the flag -visible. It shows the browser window instead of a headless browser, and it leaves the browser open when the program ends. The program prints the websocket address and the profile directory of the browser to the standard error. The browser stays running until you close its window, and the profile directory stays on disk until you delete it. To show the window with no flag, set the variable CHROMEDP_VISIBLEWINDOW=1. Any value other than an empty string, 0 and false turns it on. On Linux, a visible window needs DISPLAY or WAYLAND_DISPLAY. The remote program has no -visible flag, because it attaches to a browser that you started yourself. The flag -visible has no effect on the remote browser of forecast -remote. The tabs program works a little differently with -visible. It keeps every tab open and waits until you close the browser, and it does not leave the browser running. Its flag -tabs-in-one-window opens the tabs in one window, as real tabs, and switches between them with the protocol command Target.activateTarget. Without that flag, each tab opens in a window of its own. Try both with -visible to see the difference.

Some programs need arguments:

forecast needs the flag -q, for example go run ./forecast -q Jakarta.
geoip takes IP addresses, for example go run ./geoip 8.8.8.8.
multi takes URLs. See multi/README.md.
remote needs a running browser. See remote/README.md.
upload uploads its own source file, so you can run it from any folder.

The programs download_file, download_image, emulate, har, pdf, pdfstream and screenshot write files into the current directory. The programs fast and forecast write a file only when you give the flag -out, and multi does so only with its flag -out. The programs pdfoptions and screencast write their files into a new temporary directory, or into the directory of their flag -out.

The programs

Example	Description
click	use a selector to click on an element
console	read the console of a page and its uncaught exceptions with chromedp
cookie	set an HTTP cookie on requests
dialogs	handle the JavaScript dialogs of a page
download_file	do headless file downloads
download_image	do headless image downloads
dragdrop	drag and drop with the actions DragAndDrop and DragAndDropXY
emulate	emulate a specific device such as an iPhone
eval	evaluate JavaScript and retrieve the result
eventsiter	listen to the events of a page with iterators
exposefunc	call Go functions from a page with chromedp
extension	install a browser extension, uBlock Origin Lite, into the browser that chromedp starts, and how to show that it blocks the ads of a page
fast	measure the speed of the internet connection and show the result in the terminal
forecast	render the weather forecast of a city in the terminal
frames	reach elements inside an iframe and inside a shadow root
geoip	look up the location of an IP address and show its map in the terminal
har	generate a HAR file from the network events of a page
headers	add extra HTTP headers to browser requests
intercept	block, mock and change the requests of a page with the Fetch domain
keys	send key events to an element
latlon	retrieve the latitude and the longitude of a map from the URL of the page with the navigation events of the page
logic	combine actions and Go code in a function that reads a list from a page
multi	use headless-shell and a container (Docker, Podman, other)
pdf	capture a PDF of a page
pdfoptions	print a page to PDF files with different options of chromedp
pdfstream	print a page to a PDF file with a stream
popups	work with the popups of a page and with several targets
proxy	authenticate to a proxy server that requires authentication
rawcall	send protocol commands that chromedp has no action for
remote	connect to an existing Chrome DevTools instance using a remote WebSocket URL
screencast	record the screen of a page as a series of JPEG images
screenshot	take a screenshot of a specific element and of the entire browser viewport
selectors	choose the elements of a page with the typed selectors
session	save the state of a session and restore it in another browser
structeval	evaluate JavaScript into typed Go values
submit	fill out and submit a form
subtree	populate and travel a subtree of the DOM
tabs	use several tabs of one browser
termcast	stream the screen of the browser to the terminal with terminal graphics
text	extract text from a specific element
upload	upload a file on a form
visible	wait until an element is visible
workers	run many jobs at the same time in one browser with a pool of goroutines

The programs fast, forecast, geoip and remote draw an image in the terminal. Run them in a terminal that can show images. Most other programs have the flag -visible-on-terminal, which the section Draw the page in the terminal describes.

Draw the page in the terminal

Most programs take the flag -visible-on-terminal. It draws the page of the program in the terminal while the program runs, with terminal graphics (Kitty, iTerm2 or Sixel). The flag also works with a headless browser over ssh. The package termcast does this work. It uses the screencast of the Chrome DevTools Protocol and 4 frames each second by default. Use the flag -terminal-fps to change the rate.

go run github.com/chromedp/examples/click@latest -visible-on-terminal

The stream clears the terminal at each redraw. It holds the log lines and the results of the program, and prints them after the final frame. The flag does not work with -v, and it stops with an error when the terminal has no graphics. The programs tabs, popups, workers, multi, session, screencast, pdfstream, har and rawcall do not have the flag. The program termcast shows how to use the package in your own code. It plays an animated SVG and streams it to the terminal.

Verification

The table says which programs run with the current API, and what each program needs. "Offline" means that the program needs no internet and no service. A program that needs a live site reads it from the internet. A program that needs a terminal draws an image with rasterm. Every program runs in a headless Chrome unless you set the flag -visible, so no program in the table needs a display.

The column "Checked" says how the result was found. "Run on 2026-10-04" means that the offline programs ran with go run, with Chrome 154 on Linux, and finished with exit code 0. "Earlier test" means a run of the same code with Chrome 154 on Linux before that date. These programs were not run again on 2026-10-04, because they need a live site that can change. No program was run with the flag -visible.

Example	Needs	Result with the current API	Checked
click	offline	works	run on 2026-10-04
console	offline	works	run on 2026-10-04
cookie	offline	works	run on 2026-10-04
dialogs	offline	works	run on 2026-10-04
download_file	offline	works	run on 2026-10-04
download_image	offline	works	run on 2026-10-04
dragdrop	offline	works	run on 2026-10-04
emulate	offline	works	run on 2026-10-04
eval	offline	works	run on 2026-10-04
eventsiter	offline	works	run on 2026-10-04
exposefunc	offline	works	run on 2026-10-04
extension	offline, the uBlock Origin Lite files on disk	works	run on 2026-10-04
fast	internet (fast.com), terminal	needs a terminal that shows images	earlier test
forecast	terminal	works in a terminal, stops without one	run on 2026-10-04
frames	offline	works	run on 2026-10-04
geoip	terminal	works in a terminal, stops without one	run on 2026-10-04
har	offline	works	run on 2026-10-04
headers	offline	works	run on 2026-10-04
intercept	offline	works	run on 2026-10-04
keys	offline	works	run on 2026-10-04
latlon	offline	works	run on 2026-10-04
logic	offline	works	run on 2026-10-04
multi	offline	works	run on 2026-10-04
pdf	offline	works	run on 2026-10-04
pdfoptions	offline	works	run on 2026-10-04
pdfstream	offline	works	run on 2026-10-04
popups	offline	works	run on 2026-10-04
proxy	offline	works	run on 2026-10-04
rawcall	offline	works	run on 2026-10-04
remote	a Chrome with a debugging port	works up to the terminal image	earlier test
screencast	offline	works	run on 2026-10-04
screenshot	offline	works	run on 2026-10-04
selectors	offline	works	run on 2026-10-04
session	offline	works	run on 2026-10-04
structeval	offline	works	run on 2026-10-04
submit	offline	works	run on 2026-10-04
subtree	offline	works	run on 2026-10-04
tabs	offline	works	run on 2026-10-04
termcast	offline, a terminal	works in a terminal, stops without one	run on 2026-10-04
text	offline	works	run on 2026-10-04
upload	offline	works	run on 2026-10-04
visible	offline, a window	works	earlier test
workers	offline	works	run on 2026-10-04

Notes:

The programs forecast and geoip draw an image with rasterm. Without a terminal that shows images, they stop with the error term graphics not available. fast does the same, and it reads the live site fast.com.
The programs geoip and forecast embed their data files, GeoLite2-City.mmdb and hl.json, so they run from any folder.
remote needs a Chrome that runs with a debugging port, for example chrome --headless --remote-debugging-port=9222. Use the flag -start to let remote start that Chrome.
Every other program reads the local test site in internal/testsite. Use the flag -url to read another site.
extension needs the files of uBlock Origin Lite on disk. Use the flag -ext.

Live sites can change

Only fast reads a live site. The result can be different on another day.

Questions, bugs and changes

Ask questions in the GitHub Discussions of chromedp. Report a bug as an issue of chromedp. Do not open an issue for a question. Pull requests are welcome, and CONTRIBUTING.md says how to prepare one. A new program must keep to the rules in AGENTS.md.

Document	Holds
AGENTS.md	the rules, the layout and the commands for a coding agent and for a person
CONTRIBUTING.md	how to prepare a change
docs/decisions/README.md	the index of the decisions

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
click Command click is a chromedp example demonstrating how to use a selector to click on an element.	Command click is a chromedp example demonstrating how to use a selector to click on an element.
console Command console is a chromedp example demonstrating how to read the console of a page and its uncaught exceptions with chromedp.Console.	Command console is a chromedp example demonstrating how to read the console of a page and its uncaught exceptions with chromedp.Console.
cookie Command cookie is a chromedp example demonstrating how to set an HTTP cookie on requests.	Command cookie is a chromedp example demonstrating how to set an HTTP cookie on requests.
dialogs Command dialogs is a chromedp example demonstrating how to handle the JavaScript dialogs of a page.	Command dialogs is a chromedp example demonstrating how to handle the JavaScript dialogs of a page.
download_file Command download_file is a chromedp example demonstrating how to do headless file downloads.	Command download_file is a chromedp example demonstrating how to do headless file downloads.
download_image Command download_image is a chromedp example demonstrating how to do headless image downloads.	Command download_image is a chromedp example demonstrating how to do headless image downloads.
dragdrop Command dragdrop is a chromedp example demonstrating how to drag and drop with the actions DragAndDrop and DragAndDropXY.	Command dragdrop is a chromedp example demonstrating how to drag and drop with the actions DragAndDrop and DragAndDropXY.
emulate Command emulate is a chromedp example demonstrating how to emulate a specific device such as an iPhone.	Command emulate is a chromedp example demonstrating how to emulate a specific device such as an iPhone.
eval Command eval is a chromedp example demonstrating how to evaluate JavaScript and retrieve the result.	Command eval is a chromedp example demonstrating how to evaluate JavaScript and retrieve the result.
eventsiter Command eventsiter is a chromedp example demonstrating how to listen to the events of a page with iterators.	Command eventsiter is a chromedp example demonstrating how to listen to the events of a page with iterators.
exposefunc Command exposefunc is a chromedp example demonstrating how to call Go functions from a page with chromedp.ExposeFunc.	Command exposefunc is a chromedp example demonstrating how to call Go functions from a page with chromedp.ExposeFunc.
extension Command extension is a chromedp example demonstrating how to install a browser extension, uBlock Origin Lite, into the browser that chromedp starts, and how to show that it blocks the ads of a page.	Command extension is a chromedp example demonstrating how to install a browser extension, uBlock Origin Lite, into the browser that chromedp starts, and how to show that it blocks the ads of a page.
fast Command fast is a chromedp example demonstrating how to measure the speed of the internet connection and show the result in the terminal.	Command fast is a chromedp example demonstrating how to measure the speed of the internet connection and show the result in the terminal.
forecast Command forecast is a chromedp example demonstrating how to render the weather forecast of a city in the terminal.	Command forecast is a chromedp example demonstrating how to render the weather forecast of a city in the terminal.
frames Command frames is a chromedp example demonstrating how to reach elements inside an iframe and inside a shadow root.	Command frames is a chromedp example demonstrating how to reach elements inside an iframe and inside a shadow root.
geoip Command geoip is a chromedp example demonstrating how to look up the location of an IP address and show its map in the terminal.	Command geoip is a chromedp example demonstrating how to look up the location of an IP address and show its map in the terminal.
har Command har is a chromedp example demonstrating how to generate a HAR file from the network events of a page.	Command har is a chromedp example demonstrating how to generate a HAR file from the network events of a page.
headers Command headers is a chromedp example demonstrating how to add extra HTTP headers to browser requests.	Command headers is a chromedp example demonstrating how to add extra HTTP headers to browser requests.
intercept Command intercept is a chromedp example demonstrating how to block, mock and change the requests of a page with the Fetch domain.	Command intercept is a chromedp example demonstrating how to block, mock and change the requests of a page with the Fetch domain.
internal
testsite Package testsite is a local web site for the example programs.	Package testsite is a local web site for the example programs.
keys Command keys is a chromedp example demonstrating how to send key events to an element.	Command keys is a chromedp example demonstrating how to send key events to an element.
latlon Command latlon is a chromedp example demonstrating how to retrieve the latitude and the longitude of a map from the URL of the page with the navigation events of the page.	Command latlon is a chromedp example demonstrating how to retrieve the latitude and the longitude of a map from the URL of the page with the navigation events of the page.
logic Command logic is a chromedp example demonstrating how to combine actions and Go code in a function that reads a list from a page.	Command logic is a chromedp example demonstrating how to combine actions and Go code in a function that reads a list from a page.
multi Command multi is a chromedp example demonstrating how to use headless-shell and a container (Docker, Podman, other).	Command multi is a chromedp example demonstrating how to use headless-shell and a container (Docker, Podman, other).
pdf Command pdf is a chromedp example demonstrating how to capture a PDF of a page.	Command pdf is a chromedp example demonstrating how to capture a PDF of a page.
pdfoptions Command pdfoptions is a chromedp example demonstrating how to print a page to PDF files with different options of chromedp.PrintToPDF.	Command pdfoptions is a chromedp example demonstrating how to print a page to PDF files with different options of chromedp.PrintToPDF.
pdfstream Command pdfstream is a chromedp example demonstrating how to print a page to a PDF file with a stream.	Command pdfstream is a chromedp example demonstrating how to print a page to a PDF file with a stream.
popups Command popups is a chromedp example demonstrating how to work with the popups of a page and with several targets.	Command popups is a chromedp example demonstrating how to work with the popups of a page and with several targets.
proxy Command proxy is a chromedp example demonstrating how to authenticate to a proxy server that requires authentication.	Command proxy is a chromedp example demonstrating how to authenticate to a proxy server that requires authentication.
rawcall Command rawcall is a chromedp example demonstrating how to send protocol commands that chromedp has no action for.	Command rawcall is a chromedp example demonstrating how to send protocol commands that chromedp has no action for.
remote Command remote is a chromedp example demonstrating how to connect to an existing Chrome DevTools instance using a remote WebSocket URL.	Command remote is a chromedp example demonstrating how to connect to an existing Chrome DevTools instance using a remote WebSocket URL.
screencast Command screencast is a chromedp example demonstrating how to record the screen of a page as a series of JPEG images.	Command screencast is a chromedp example demonstrating how to record the screen of a page as a series of JPEG images.
screenshot Command screenshot is a chromedp example demonstrating how to take a screenshot of a specific element and of the entire browser viewport.	Command screenshot is a chromedp example demonstrating how to take a screenshot of a specific element and of the entire browser viewport.
selectors Command selectors is a chromedp example demonstrating how to choose the elements of a page with the typed selectors.	Command selectors is a chromedp example demonstrating how to choose the elements of a page with the typed selectors.
session Command session is a chromedp example demonstrating how to save the state of a session and restore it in another browser.	Command session is a chromedp example demonstrating how to save the state of a session and restore it in another browser.
structeval Command structeval is a chromedp example demonstrating how to evaluate JavaScript into typed Go values.	Command structeval is a chromedp example demonstrating how to evaluate JavaScript into typed Go values.
submit Command submit is a chromedp example demonstrating how to fill out and submit a form.	Command submit is a chromedp example demonstrating how to fill out and submit a form.
subtree Command subtree is a chromedp example demonstrating how to populate and travel a subtree of the DOM.	Command subtree is a chromedp example demonstrating how to populate and travel a subtree of the DOM.
tabs Command tabs is a chromedp example demonstrating how to use several tabs of one browser.	Command tabs is a chromedp example demonstrating how to use several tabs of one browser.
termcast Command termcast is a chromedp example demonstrating how to stream the screen of the browser to the terminal with terminal graphics.	Command termcast is a chromedp example demonstrating how to stream the screen of the browser to the terminal with terminal graphics.
text Command text is a chromedp example demonstrating how to extract text from a specific element.	Command text is a chromedp example demonstrating how to extract text from a specific element.
upload Command upload is a chromedp example demonstrating how to upload a file on a form.	Command upload is a chromedp example demonstrating how to upload a file on a form.
visible Command visible is a chromedp example demonstrating how to wait until an element is visible.	Command visible is a chromedp example demonstrating how to wait until an element is visible.
workers Command workers is a chromedp example demonstrating how to run many jobs at the same time in one browser with a pool of goroutines.	Command workers is a chromedp example demonstrating how to run many jobs at the same time in one browser with a pool of goroutines.