ThumbmarkJS is a free, open-source JavaScript browser fingerprinting library. Use it to identify returning visitors, detect fraud and bots, and more — all client-side, with no backend required.

MIT-licensed and commercially usable, it is used on 60,000+ websites, generating over a billion fingerprints every month.

Try it now

Visit the live demo → to see your browser's fingerprint and the individual components that make it up.

Or paste this into your browser's developer console to get your fingerprint hash and component breakdown directly:

import('https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.umd.js')
  .then(() => {
    const tm = new ThumbmarkJS.Thumbmark();
    tm.get().then((res) => console.log(res));
  })

Performance

The client library achieves ~80% uniqueness across general browser populations. Mac/Safari users can show higher collision rates or higher noise depending on the audience.

Need higher accuracy? Try the ThumbmarkJS API

The open-source library is great for many use cases, but if you need production-grade accuracy for fraud prevention or user identification, the ThumbmarkJS API takes it significantly further. A free tier is available.

The API combines the client-side signals with server-side analysis — including TLS handshake details, HTTP headers, and connection-level data — to produce fingerprints with over 99% uniqueness. It also adds smart signals: bot detection, VPN and TOR detection, datacenter traffic identification, and a threat level score per visitor.

Learn more at thumbmarkjs.com →

Installation

NPM

npm install @thumbmarkjs/thumbmarkjs

⚠️ ThumbmarkJS runs in the browser. It requires browser APIs to compute fingerprint components and cannot run server-side.

See the NPM usage guide →

CDN (jsDelivr)

Transpiled bundles are available on jsDelivr:

Format	URL
UMD	https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.umd.js
CommonJS	https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.cjs.js
ESM	https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.esm.js

Documentation

Full documentation at docs.thumbmarkjs.com — including installation, configuration, integrations, and the API reference.

Configuration

Options are passed to the Thumbmark constructor:

const tm = new ThumbmarkJS.Thumbmark({
  option_key: option_value
})

Option	Type	Default	Description
api_key	string	—	API key from thumbmarkjs.com. Enables server-side signals and visitorId.
exclude	string[]	—	Components to exclude from the fingerprint hash. Excluding a top-level component also improves performance.
include	string[]	—	Only include these components. exclude still applies.
permissions_to_check	string[]	—	Limit which browser permissions are checked. Permissions are the slowest component to resolve.
timeout	integer	5000	Component timeout in milliseconds.
logging	boolean	true	At most 0.01% of runs send an anonymous sample to improve the library. See Sampled logging.
collect_beacon	boolean	true	When the pro API asks the client to (see Collect beacon), sends the User-Agent and thumbmark hash to collect.thumbmarkjs.com. Never fires on an anonymous install (one that sets neither api_key nor simple_request), since no API call is made at all in that case.
performance	boolean	false	When true, includes per-component resolution time in milliseconds.
stabilize	string[]	['private', 'iframe']	Preset exclusion list for stability across private browsing and iframes.
metadata	varies	—	Passed to webhooks. Does not affect the fingerprint.

See the configuration reference →

Sampled logging

By default, at most 0.01% of runs — and never more than once per browser session — send an anonymous sample to api.thumbmarkjs.com/log. This is how the library gets improved: it shows which components turn out to be unstable across real browsers.

When a run is sampled, the library also fetches a small script from experimental.thumbmarkjs.com and evaluates it. That script computes fraud-prevention signals that are still under evaluation — they are included in the sample but are not part of the fingerprint hash and are never returned to the caller. Keeping them out of the bundle means they can be iterated without a release.

The script is published in readable, non-minified form alongside the minified build the library actually loads, so you can read exactly what runs: experimental.js

Nothing is fetched or evaluated on the other 99.99% of runs. To disable both the sample and the fetch:

const tm = new ThumbmarkJS.Thumbmark({ logging: false })

If your Content Security Policy omits 'unsafe-eval', or does not allow experimental.thumbmarkjs.com, the fetch or evaluation fails silently and fingerprinting is unaffected.

Collect beacon

If you use a pro api_key (or proxy requests via simple_request), the API can occasionally instruct the client to send one small extra request, direct from the browser to collect.thumbmarkjs.com (or your collect_endpoint):

{
  "ua": "<navigator.userAgent>",
  "thumbmark": "<the resolved thumbmark hash>",
  "ja4": "<the JA4 TLS fingerprint the API observed>",
  "ja4_source": "<the header the API read it from>"
}

The receiving server also fingerprints the TLS handshake of that connection (its "JA4") and stores it alongside those fields. This builds network-level fraud-detection signals for your account — it is not library telemetry. An install with neither api_key nor simple_request makes no API call, so it never receives the instruction and never sends this beacon.

The response is never read, so nothing about it reaches your code or affects getThumbmark(). At most one beacon per browser session, best-effort. If your CSP connect-src disallows the host, the browser blocks the request and logs a CSP violation.

logging: false does not disable this — that flag covers only the anonymous sample above. Use collect_beacon: false.

Integrations

React, Vue, Angular, and Preact integration plugins are available. See the integrations docs →

Fingerprint components

ThumbmarkJS combines multiple browser fingerprinting techniques to maximise uniqueness. The following signals are collected client-side:

• Audio fingerprinting
• Canvas fingerprinting
• WebGL fingerprinting and GPU info
• Available fonts and rendering behaviour
• Hardware details
• Browser languages and timezone
• Math precision characteristics
• Browser permissions
• Installed plugins
• Screen details and media queries
• Speech synthesis voices
• System and browser details
• WebRTC fingerprinting

The following are available via the API only:

• TLS handshake details
• HTTP headers
• Connection and IP details

See the full components reference →

Custom components

Add your own signals to the fingerprint with includeComponent(key, fn):

tm.includeComponent('my_signal', () => 'custom_value');

The function can return a string, number, or object. See the custom components docs →

Technical details

The library is intentionally simple to build, extend, and audit. See technical_details.md for an overview of the architecture.

Enjoying ThumbmarkJS?

If it's working well for you, a quick review on SourceForge helps other developers find it when they're comparing fingerprinting libraries. Takes about 5 minutes — thank you!

Community & support

• 💬 Discord — questions, ideas, and discussion
• 📧 [email protected]
• 📖 Documentation