# custom-device-emulation-chrome: a device catalogue you can copy into DevTools

> This repository is a dataset and a search tool for device dimensions, pixel ratios and user agent strings, plus a Chrome extension that puts the catalogue in your toolbar. The copy buttons copy text rather than importing devices, and the data carries its own quality labels because not every preset was measured on hardware.

**amirshnll/custom-device-emulation-chrome** — custom device emulation chrome | How To Add Custom Device on Chrome Emulation ?

- Repository: https://github.com/amirshnll/custom-device-emulation-chrome
- Website: https://chromewebstore.google.com/detail/device-viewer/bidghlomhmceghnmpmnmpmcemeddcldk?hl=en&authuser=0
- Stars: 732 · Forks: 79
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/amirshnll-custom-device-emulation-chrome

## A dataset first, and a catalogue second

custom-device-emulation-chrome is a set of device dimensions, pixel ratios and user agents for responsive testing in Chrome DevTools. The stated workflow is to find a preset, copy its values and add a custom device in Chrome.

The repository is arranged as a data project with tooling around it. There is a device.json at the top level, which is the dataset, a scripts/ directory with a build script, an index.html, site.css and site.js which are the static catalogue, a plugin/ directory holding the Chrome extension, and a docs/ directory with the data quality policy and a historical table. There is also a release.sh, a CHANGELOG.md and a CONTRIBUTING.md.

So the data is the product and the two interfaces, the website and the extension, are views onto it.

The project is MIT licensed, with the caveat that cited third-party preset sources retain their own licences, which the data policy covers. The primary language is JavaScript, the default branch is main, the last push was on 2026-09-06, and the release list shows 1.2.0 on 2025-01-13, 1.3.0 on 2025-10-20 and 1.5.0 on 2026-09-06.

The homepage is a Chrome Web Store listing for the extension, which the README qualifies later on. It says no Chrome Web Store listing is linked here because a verified listing has not been provided, so the extension is distributed as unpacked files from the repository rather than as a store install.

## Adding a custom device, one manual step at a time

The quick start is six steps, and step five is the one that matters for anyone using this project.

You find your device in the JSON dataset or the searchable catalogue. You open Chrome DevTools with Command-Option-I on macOS or Ctrl+Shift-I on Windows and Linux. You toggle the device toolbar with Command-Shift-M or Ctrl+Shift+M. You select Dimensions, then Edit, then Add custom device. Then you enter the name, width, height and DPR, choose the Mobile or Desktop type, and the user agent is optional, left blank when the dataset says a dash. Finally you click Add and select the device from Dimensions.

The honest limitation is stated right after the list. The copy buttons copy text, they do not automatically import devices into Chrome.

That is the difference between this and a device list that writes into DevTools, and it is a deliberate one. Chrome has no supported way for an extension or a web page to add an entry to the device toolbar, so any tool claiming to do it is either doing something unsupported or asking you to paste. This project asks you to paste four values, and it makes finding those values the problem it solves.

For a tester with twenty devices to check, that is a reasonable trade. The catalogue exists so you do not have to look up a viewport size, and the extension exists so you do not have to look up the catalogue.

## The static catalogue, and why it must be served over HTTP

The catalogue is a static site, and the README is specific about how to run it locally. From the repository root:

```sh
python3 scripts/build.py
python3 -m http.server 8000 --directory dist
```

You then open http://localhost:8000. The website uses plain HTML, CSS and JavaScript, with no package installation.

The one requirement is that it must be served over HTTP. Opening the HTML file directly cannot reliably load the JSON, because a file:// page fetching a sibling JSON file hits browser security rules. That is a small detail that costs an hour if you skip it, and it is exactly the kind of thing a static site builder cannot work around without a bundler, which this project deliberately avoids.

The site itself searches all devices, filters by device type and by data quality, and copies settings or user agents. Each record shows its source and its measurement notes, so the quality label travels with the value rather than being a separate page.

Publishing it is a GitHub Actions workflow. You push the files to the main branch, set the source in Settings, Pages, Build and deployment to GitHub Actions, and run the Deploy device catalogue to GitHub Pages action, or simply push another commit to main. The workflow validates the dataset, builds the static site and publishes only the dist/ directory, and subsequent pushes to main deploy automatically. No external hosting account and no additional deployment secret is needed.

The site uses relative asset and data URLs, which is why it also works under a repository subpath, so a fork works at its own Pages URL without configuration.

## The extension shows presets but cannot import them

The Chrome extension puts searchable device dimensions in your toolbar, and it is installed as an unpacked extension rather than from the store.

The install steps are: download the repository with Code then Download ZIP and extract it, or clone it. Open chrome://extensions and enable Developer mode. Choose Load unpacked and select the extracted plugin folder. Then pin the extension and open it to search devices and view the dimensions and DPR.

What it does and does not do is stated clearly. The extension displays presets, and you add them to DevTools using the quick start above. It reads the maintained dataset from GitHub, with a bundled offline fallback, and it requests no browsing-history permissions. There is a privacy policy at plugin/privacy.md.

That permission story is worth a second look, because device emulation extensions are a category where a request for browsing history would be plausible. This one says it does not ask for it, and it publishes the policy in the extension folder rather than on a separate site.

The bundled offline fallback is the other detail with practical value. If the extension is offline or the GitHub dataset is unreachable, it still has something to show, which for a testing tool used on a plane or behind a proxy is a real consideration.

The project is honest that the extension is a front end rather than a mechanism. It is a fast way to find a number and put it on the clipboard, and the four values still have to be typed into the DevTools dialog.

## The data quality labels, and why the user agent is not a promise

The section on understanding the data is the most careful part of the README, and it is what separates this project from a list of numbers on a website.

Every record carries a quality label. A source checked label means the value was compared with a cited preset but was not verified against a physical device. A needs review label marks historical community data with an unknown source or unknown measurement conditions.

Three specific caveats follow. The screen-css and viewport-css fields distinguish full screen dimensions from browser content dimensions, which is the difference between the number of pixels on the panel and the number the page actually gets. Desktop viewport depends on window size, display scaling and zoom, so historical desktop presets need review. And a user agent string does not make Chrome emulate Safari, because Device Mode is an approximation and critical behaviour has to be tested on real hardware.

That last point deserves emphasis, because it is the point people get wrong. Setting a custom device in Chrome DevTools changes the viewport size and the pixel ratio, and the user agent string changes what your server sends back, and that is all it does. It does not change the rendering engine, the JavaScript engine, the font stack, the media query support or the touch behaviour. A page that works in an emulated iPhone in Chrome is not evidence that it works on an iPhone.

So the correct use of this catalogue is for layout and breakpoint work, which is what the data is for, and not for feature detection. The measurement and maintenance policy document, the official Chrome guide on Device Mode and the historical table are all linked for people who want the reasoning rather than the numbers.

## Where this project is the wrong tool

The first wrong case is a requirement to test real device behaviour. As the README says, Device Mode is an approximation. A user agent string changes what a server returns, not what the browser can do. If your concern is Safari-specific rendering, or a WebKit engine difference, or physical device performance, this catalogue does not help, and no DevTools preset can substitute for hardware.

The second is a workflow that wants devices imported automatically. The copy buttons copy text, and adding a device is a manual dialog. If you are setting up a test matrix across forty device profiles every morning, a manual paste per device is the wrong shape, and you want a script that writes the DevTools protocol settings or a testing framework with its own device definitions.

The third is trusting the data without reading the label. The catalogue contains historical community data with unknown sources, and the difference between a source checked preset and a needs review one is exactly the difference between a measurement and a guess. If your layout depends on a specific breakpoint, a preset with an unknown origin is worse than no preset, because it looks authoritative.

The fourth is a shared team that needs a single source of truth. The data is a JSON file in a repository, and the extension reads it from GitHub with a bundled fallback, so two people on different commits can be looking at different numbers, and the extension's offline copy can drift from the hosted dataset.

The alternative worth weighing is your own list. A spreadsheet of the ten devices your users actually use, with a note on where each viewport came from, is smaller and more accurate than a catalogue of hundreds, and it is the list that matters. The value here is coverage and search, and if your needs are narrow, a file you maintain yourself beats one you inherit.

## Conclusion

Adopt this catalogue if you regularly test responsive layouts and keep a private list of device presets that Chrome DevTools does not ship, since the JSON is a single file you can grep and the quality labels tell you which entries are worth trusting. Keep away if you need emulation that behaves like the real device, because the README is explicit that a user agent string does not make Chrome emulate Safari and that Device Mode is an approximation. Before you paste a preset into DevTools, check its quality label, and note that the extension is loaded unpacked from a folder rather than installed from the Chrome Web Store, since no verified listing has been provided.

## FAQ

### What is custom-device-emulation-chrome and what does it give me?

It is a dataset and search tool of device dimensions, pixel ratios and user agent strings for Chrome DevTools responsive testing, with a JSON file, a static catalogue website and a Chrome extension that puts the catalogue in your toolbar so you can copy the values into a custom device.

### Does the extension add devices to Chrome DevTools automatically?

No. The copy buttons copy text and do not automatically import devices into Chrome, so you still select Dimensions, Edit, Add custom device and paste the name, width, height and DPR yourself. The extension reads the dataset from GitHub with a bundled offline fallback and requests no browsing-history permissions.

### How do I run the device catalogue website locally?

Run python3 scripts/build.py and then python3 -m http.server 8000 --directory dist from the repository root, and open http://localhost:8000. It must be served over HTTP, because opening the HTML file directly cannot reliably load the JSON.

### Are the device presets in this catalogue verified against real hardware?

Not all of them. Each record carries a quality label: a source checked preset was compared with a cited preset but not verified physically, and a needs review record is historical community data with an unknown source. The README also notes that a user agent string does not make Chrome emulate Safari, since Device Mode is an approximation.

## Sources

- [amirshnll/custom-device-emulation-chrome on GitHub](https://github.com/amirshnll/custom-device-emulation-chrome)
- [License: MIT](https://github.com/amirshnll/custom-device-emulation-chrome/blob/main/LICENSE)
- [Project website](https://chromewebstore.google.com/detail/device-viewer/bidghlomhmceghnmpmnmpmcemeddcldk?hl=en&authuser=0)
- [README](https://github.com/amirshnll/custom-device-emulation-chrome/blob/main/README.md)
- [Releases](https://github.com/amirshnll/custom-device-emulation-chrome/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/amirshnll-custom-device-emulation-chrome