Skip to content

Refactor chrome_settings_overrides page to use <dl> syntax #42580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rebloor merged 5 commits into from
Jan 5, 2026
Merged

Refactor chrome_settings_overrides page to use <dl> syntax #42580

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2f79c38
Add anchors to `chrome_settings_overrides` fields
RobertCraigie Dec 30, 2025
cbc1b0a
refactor to `<dl>` syntax
RobertCraigie Jan 2, 2026
16a0139
updates
RobertCraigie Jan 4, 2026
4c7492d
Correct parameter name
rebloor Jan 5, 2026
ca0b8df
Merge branch 'main' into chrome-settings-overrides/headers
rebloor Jan 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
227 changes: 92 additions & 135 deletions .../mozilla/add-ons/webextensions/manifest.json/chrome_settings_overrides/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,141 +38,98 @@ Use the `chrome_settings_overrides` key to override the browser's home page and

The `chrome_settings_overrides` key is an object that may have the following properties:

<table class="fullwidth-table standard-table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Type</th>
<th scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>homepage</code></td>
<td><code>String</code></td>
<td>
<p>Defines the page to be used as the browser's homepage.</p>
<p>The replacement is given as a URL. The URL may:</p>
<ul>
<li>
point to a file bundled with the extension, in which case it is
given as a URL relative to the manifest.json file
</li>
<li>be a remote URL, such as "https://developer.mozilla.org/".</li>
</ul>
<p>
If two or more extensions both set this value, then the setting from
the most recently installed one will take precedence.
</p>
<p>
To override new tabs, use "<a
href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_url_overrides"
>chrome_url_overrides</a
>" instead.
</p>
<p>
This is a
<a
href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json"
>localizable property</a
>.
</p>
</td>
</tr>
<tr>
<td><code>search_provider</code></td>
<td><code>Object</code></td>
<td>
<p>Defines a search provider to add to the browser.</p>
<p>
The search provider has a name and a primary search URL. Alternative
URLs may be provided, including URLs for more specialized searches
like image search. In the URL you supply, use
<code>{searchTerms}</code> to interpolate the search term into the
URL, like:
<code>https://www.discogs.com/search/?q={searchTerms}</code>. You can
also provide POST parameters to be sent along with the search.
</p>
<p>
The search provider will be presented to the user alongside the
built-in providers. If you include the
<code>is_default</code> property and set it to <code>true</code>, the
new search provider will be the default option. By supplying the
<code>keyword</code> property, you enable the user to select your
search provider by typing the keyword into the search/address bar
before the search term.
</p>
<p>
This is an object with the properties listed below. All string
properties are
<a
href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json"
>localizable</a
>.
</p>
<dl>
<dt><code>name</code></dt>
<dd>String: The search engine's name, displayed to the user.</dd>
<dt><code>search_url</code></dt>
<dd>
String: URL used by the search engine. This must be an HTTPS URL.
</dd>
<dt><code>is_default</code> {{optional_inline}}</dt>
<dd>
Boolean: True if the search engine should be the default choice. On
Firefox, this is opt-in and the user will only be asked the first
time the extension is installed. They will not be asked again if a
search engine is added later.
</dd>
<dt><code>alternate_urls</code> {{optional_inline}}</dt>
<dd>
Array of String: An array of alternative URLs that can be used
instead of <code>search_url</code>.
</dd>
<dt><code>encoding</code> {{optional_inline}}</dt>
<dd>
String: Encoding of the search term, specified as a
<a
href="https://www.iana.org/assignments/character-sets/character-sets.xhtml"
>standard character encoding name</a
>, such as "UTF-8".
</dd>
<dt><code>favicon_url</code> {{optional_inline}}</dt>
<dd>
String: URL pointing to an icon for the search engine. In Manifest V2,
this must be an absolute HTTP or HTTPS URL. In Manifest V3, this must
reference an icon provided in the extension as a path relative to the
extension's root.
</dd>
<dt><code>image_url</code> {{optional_inline}}</dt>
<dd>String: URL used for image search.</dd>
<dt><code>image_url_post_params</code> {{optional_inline}}</dt>
<dd>String: POST parameters to send to <code>image_url</code>.</dd>
<dt><code>instant_url</code> {{optional_inline}}</dt>
<dd>String: URL used for instant search.</dd>
<dt><code>instant_url_post_params</code> {{optional_inline}}</dt>
<dd>String: POST parameters to send to <code>instant_url</code>.</dd>
<dt><code>keyword</code> {{optional_inline}}</dt>
<dd>String: Address bar keyword for the search engine.</dd>
<dt><code>prepopulated_id</code> {{optional_inline}}</dt>
<dd>The ID of a built-in search engine to use.</dd>
<dt><code>search_url_get_params</code> {{optional_inline}}</dt>
<dd>String: GET parameters to send to <code>search_url</code>. Available only in Firefox, for optimal cross-browser compatibility use <code>search_url</code> instead.</dd>
<dt><code>search_url_post_params</code> {{optional_inline}}</dt>
<dd>String: POST parameters to send to <code>search_url</code>.</dd>
<dt><code>suggest_url</code> {{optional_inline}}</dt>
<dd>
String: URL used for search suggestions. This must be an HTTPS URL.
</dd>
<dt><code>suggest_url_get_params</code> {{optional_inline}}</dt>
<dd>String: GET parameters to send to <code>suggest_url</code>. Available only in Firefox, for optimal cross-browser compatibility use <code>suggest_url</code> instead.</dd>
<dt><code>suggest_url_post_params</code> {{optional_inline}}</dt>
<dd>String: POST parameters to send to <code>suggest_url</code>.</dd>
</dl>
</td>
</tr>
</tbody>
</table>
- `homepage`
- : `string`. Defines the page to be used as the browser's homepage.

The replacement is given as a URL. The URL may:
- point to a file bundled with the extension, in which case it is
given as a URL relative to the manifest.json file
- be a remote URL, such as "https://developer.mozilla.org/".

If two or more extensions both set this value, then the setting from
the most recently installed one will take precedence.

To override new tabs, use [chrome_url_overrides](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_url_overrides) instead.

This is a [localizable property](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json).

- `search_provider`
- : `object`. Defines a search provider to add to the browser.

The search provider has a name and a primary search URL. Alternative
URLs may be provided, including URLs for more specialized searches
like image search. In the URL you supply, use
`{searchTerms}` to interpolate the search term into the
URL, like:
`https://www.discogs.com/search/?q={searchTerms}`. You can
also provide POST parameters to be sent along with the search.

The search provider will be presented to the user alongside the
built-in providers. If you include the
`is_default` property and set it to `true`, the
new search provider will be the default option. By supplying the
`keyword` property, you enable the user to select your
search provider by typing the keyword into the search/address bar
before the search term.

This object has these properties. All string
properties are [localizable](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization#internationalizing_manifest.json).
- `name`
- : `string`. The search engine's name, displayed to the user.

- `search_url`
- : `string`. URL used by the search engine. This must be an HTTPS URL.

- `is_default` {{optional_inline}}
- : `boolean`. True if the search engine should be the default choice. On
Firefox, this is opt-in and the user will only be asked the first
time the extension is installed. They will not be asked again if a
search engine is added later.

- `alternate_urls` {{optional_inline}}
- : `array` of `string`. An array of alternative URLs that can be used instead of `search_url`.

- `encoding` {{optional_inline}}
- : `string`. Encoding of the search term, specified as a [standard character encoding name](https://www.iana.org/assignments/character-sets/character-sets.xhtml), such as "UTF-8".

- `favicon_url` {{optional_inline}}
- : `string`. URL pointing to an icon for the search engine. In Manifest V2,
this must be an absolute HTTP or HTTPS URL. In Manifest V3, this must
reference an icon provided in the extension as a path relative to the
extension's root.

- `image_url` {{optional_inline}}
- : `string`. URL used for image search.

- `image_url_post_params` {{optional_inline}}
- : `string`. POST parameters to send to `image_url`.

- `instant_url` {{optional_inline}}
- : `string`. URL used for instant search.

- `instant_url_post_params` {{optional_inline}}
- : `string`. POST parameters to send to `instant_url`.

- `keyword` {{optional_inline}}
- : `string`. Address bar keyword for the search engine.

- `prepopulated_id` {{optional_inline}}
- : `string`. The ID of a built-in search engine to use.

- `search_url_get_params` {{optional_inline}}
- : `string`. GET parameters to send to `search_url`. Available only in Firefox, for optimal cross-browser compatibility use `search_url` instead.

- `search_url_post_params` {{optional_inline}}
- : `string`. POST parameters to send to `search_url`.

- `suggest_url` {{optional_inline}}
- : `string`. URL used for search suggestions. This must be an HTTPS URL.

- `suggest_url_get_params` {{optional_inline}}
- : `string`. GET parameters to send to `suggest_url`. Available only in Firefox, for optimal cross-browser compatibility use `suggest_url` instead.

- `suggest_url_post_params` {{optional_inline}}
- : `string`. POST parameters to send to `suggest_url`.

## Example

Expand Down