Overriding Chrome settings  |  Chrome Extensions  |  Chrome for Developers
Skip to main content
Docs
Build with Chrome
Learn how Chrome works, participate in origin trials, and build with Chrome everywhere.
Web Platform
Capabilities
ChromeDriver
Extensions
Chrome Web Store
Chromium
Web on Android
Origin trials
Release notes
Productivity
Create the best experience for your users with the web's best tools.
DevTools
Lighthouse
Chrome UX Report
Accessibility
Modern Web Guidance
Get things done quicker and neater, with our ready-made libraries.
Workbox
Puppeteer
Experience
Design a beautiful and performant web with Chrome.
AI
Performance
CSS and UI
Identity
Payments
Privacy and security
Resources
More from Chrome and Google.
All documentation
Baseline
web.dev
PageSpeed Insights audit
Isolated Web Apps (IWA)
Case studies
Blog
New in Chrome
/
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Nederlands
Polski
Português – Brasil
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어
Sign in
Docs
Chrome Extensions
Overview
Get Started
Develop
How To
AI
Reference
API
Permissions
Manifest
Samples
Chrome Web Store
Prepare your Extension
Publish in the Chrome Web Store
Program Policies
Docs
More
Overview
Get Started
Develop
How To
AI
Reference
More
Samples
Chrome Web Store
More
Case studies
Blog
New in Chrome
Manifest file format
Shared modules
Overriding Chrome settings
background
content_scripts
cross_origin_embedder_policy
content_security_policy
cross_origin_opener_policy
description
default_locale
event_rules
externally_connectable
file_handlers
homepage_url
incognito
icons
input_components
key
manifest_version
mime_types_handler
minimum_chrome_version
name
oauth2
requirements
sandbox
short_name
storage
trial_tokens
version
web_accessible_resources
Build with Chrome
Web Platform
Capabilities
ChromeDriver
Extensions
Chrome Web Store
Chromium
Web on Android
Origin trials
Release notes
Productivity
DevTools
Lighthouse
Chrome UX Report
Accessibility
Modern Web Guidance
Workbox
Puppeteer
Experience
AI
Performance
CSS and UI
Identity
Payments
Privacy and security
Resources
All documentation
Baseline
web.dev
PageSpeed Insights audit
Isolated Web Apps (IWA)
API
Permissions
Manifest
Prepare your Extension
Publish in the Chrome Web Store
Program Policies
Home
Docs
Chrome Extensions
Reference
Overriding Chrome settings
Stay organized with collections
Save and categorize content based on your preferences.
Settings overrides are a way for extensions to override selected Chrome settings. The API is
available on Windows and Mac in all current versions of Chrome.
Homepage, search provider, and startup pages
Here is an example of how homepage, search provider, and startup pages can be modified
in the extension manifest. Any domain used in the settings API must be verified (via
Google Search Console) by the same developer account publishing the extension. Note that if you
verify ownership for a domain (for example, https://example.com) you can use any subdomain or page
(for example, https://app.example.com or https://example.com/page.html) within your extension.
Using the settings override permission while also requesting any additional capabilities or permissions is inconsistent with our single purpose policy. When Chrome detects that an item is potentially violating our single purpose policy, a confirmation dialog is shown to the user. Extensions that limit themselves to only modifying a single setting without seeking additional capabilities or permissions do not get a confirmation dialog.
This applies to Chrome 107 and later.
{
"name": "My extension",
...
"chrome_settings_overrides": {
"homepage": "https://www.homepage.com",
"search_provider": {
"name": "name.__MSG_url_domain__",
"keyword": "keyword.__MSG_url_domain__",
"search_url": "https://www.foo.__MSG_url_domain__/s?q={searchTerms}",
"favicon_url": "https://www.foo.__MSG_url_domain__/favicon.ico",
"suggest_url": "https://www.foo.__MSG_url_domain__/suggest?q={searchTerms}",
"instant_url": "https://www.foo.__MSG_url_domain__/instant?q={searchTerms}",
"image_url": "https://www.foo.__MSG_url_domain__/image?q={searchTerms}",
"search_url_post_params": "search_lang=__MSG_url_domain__",
"suggest_url_post_params": "suggest_lang=__MSG_url_domain__",
"instant_url_post_params": "instant_lang=__MSG_url_domain__",
"image_url_post_params": "image_lang=__MSG_url_domain__",
"alternate_urls": [
"https://www.moo.__MSG_url_domain__/s?q={searchTerms}",
"https://www.noo.__MSG_url_domain__/s?q={searchTerms}"
],
"encoding": "UTF-8",
"is_default": true
},
"startup_pages": ["https://www.startup.com"]
},
"default_locale": "de",
...
}
Customizing values
Values in the manifest can be customized in the following ways:
All values of the search_provider, homepage, and startup_pages properties can be localized
using the chrome.i18n API.
For external extensions, the search_provider, homepage and startup_pages URL values can
be parametrized using a registry key. Create a new registry entry next to the
"update_url" key (see instructions here). The key name is "install_parameter", the value
is an arbitrary string:
{
"update_url": "https://clients2.google.com/service/update2/crx",
"install_parameter": "Value"
}
All occurrences of the substring "__PARAM__" in the manifest URLs will be substituted with the
"install_parameter" value. If "install_parameter" is absent, occurrences of "__PARAM__" are
removed. Note that "__PARAM__" cannot be part of the hostname. It needs to occur after the
first '/' in the URL.
Reference
An extension can override one or more of the following properties in the manifest:
alternate_urls (array of strings, optional)
A list of URL patterns that can be used in addition to search_url.
encoding (string, optional)
The encoding used for search terms. This is required if you don't set prepopulated_id.
favicon_url (string, optional)
An icon URL for the search engine. This is required if you don't set prepopulated_id.
homepage (string, optional)
The new value for the homepage.
image_url (string, optional)
The URL the search engine uses for image search. If this isn't used, the engine doesn't support image search.
image_url_post_params (string, optional)
The post parameters for image_url.
is_default (boolean, required)
Specifies whether the search provider should be default.
keyword (string, optional)
An omnibox keyword for the search engine. This is required if you don't set prepopulated_id.
name (string, optional)
Name of the search engine displayed to user. This is required if you don't set prepopulated_id.
prepopulated_id (integer, optional)
An ID for Chrome's built-in search engine.
search_provider (object, optional)
A search engine.
search_url (string, required)
The search URL the search engine uses.
search_url_post_params (string, optional)
The post parameters for search_url.
startup_pages (array of strings, optional)
An array of length one containing a URL to be used as the startup page.
suggest_url (string, optional)
The URL the search engine uses for suggestions. If this isn't used, the engine doesn't support suggestions.
suggest_url_post_params (string, optional)
The post parameters for suggest_url.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2014-02-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2014-02-14 UTC."],[],[]]
Contribute
File a bug
See open issues
Related content
Chromium updates
Case studies
Archive
Podcasts & shows
Follow
@ChromiumDev on X
YouTube
Chrome for Developers on LinkedIn
RSS
Terms
Privacy
Manage cookies
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Nederlands
Polski
Português – Brasil
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어