Zen Browser: about:config Tweaks, 1Password Setup, and Customization Guide

Zen Browser is an open-source web browser built on the Firefox engine. It is designed to provide a minimalist, distraction-free environment that prioritizes your workflow.

How to Integrate 1Password with Zen Browser

1Password simplifies credential management. By pairing the 1Password desktop app with Zen Browser, you can enjoy a much more seamless login experience. Note that this specific desktop integration guide applies only to Linux and macOS. Windows users do not require these steps; the standard browser extension handles the connection automatically.

1Password’s full desktop integration typically only supports widely recognized or "trusted" browsers. When active, the desktop app and browser extension share a secure connection to sync your vault and lock state, allowing you to unlock the extension using biometrics.

Linux Solution

On Linux, you must manually create an "allowed-browsers" file to let 1Password recognize Zen. This allows the application to communicate with Zen even though it is not yet officially supported.

1. Create the 1Password configuration directory: sudo mkdir /etc/1password

2. Create the custom allowed browsers file: sudo touch /etc/1password/custom_allowed_browsers

3. Add Zen Browser to the list: echo "zen-bin" | sudo tee -a /etc/1password/custom_allowed_browsers

Credits to u/xmansyx and u/feelspeaceman for this workaround.

macOS Solution

On macOS, you can add Zen Browser directly through the desktop application's settings.

1. Open the 1Password desktop app and navigate to Settings.
2. Select the Browsers tab and click "Add browser".
3. Locate "Zen Browser" in your Applications folder and add it. Authorize the connection when prompted by the system.

Zen Browser Hidden & Advanced Preferences

Zen Browser includes various advanced settings to modify its interface and behavior. To access these, type about:config into the address bar and search for the preferences listed below. Some adjustments may require a browser restart to take effect.

Appearance

• zen.theme.content-element-separation – Adjusts the border width around the browser window. Default: 8.
• zen.theme.accent-color – Defines the primary accent color using a hex code.
• zen.theme.essentials-favicon-bg – Toggles a colorful background for the favicons of "essential" tabs. Enabled by default.
• zen.theme.gradient – Enables a customizable sidebar gradient. Enabled by default.
• zen.theme.gradient.show-custom-colors – Allows the use of specific hex colors for the sidebar gradient. Disabled by default.
• zen.view.experimental-rounded-view – Experimental feature; current effect is undocumented. Disabled by default.
• zen.view.gray-out-inactive-windows – Desaturates the browser theme when the window is not in focus. Enabled by default.
• zen.watermark.enabled – Displays a brief splash screen upon launching Zen. Enabled by default.

Transparency & Blur

• zen.theme.acrylic-elements – (Windows only) Toggles acrylic blur effects. Default: true.
• zen.widget.linux.transparency – (Linux only) Enables transparency for the browser interface.
• browser.tabs.allow_transparent_browser – Matches the default website background to your theme color. Use with caution, as this may cause visual glitches on certain websites. Disabled by default.

Tabs

• zen.tab-unloader.excluded-urls – A comma-separated list of URLs that the browser is prevented from unloading.
• zen.tabs.dim-pending – Visually dims tabs that have been unloaded from memory. Enabled by default.
• zen.tabs.rename-tabs – Enables the ability to rename pinned tabs. Enabled by default.
• zen.ctrlTab.show-pending-tabs – If "Ctrl+Tab cycles through tabs in recently used order" is enabled, this allows switching to unloaded tabs. Disabled by default.
• zen.startup.smooth-scroll-in-tabs – Enables smooth scrolling transitions when navigating the tab bar. Enabled by default.
• toolkit.tabbox.switchByScrolling – Allows switching between tabs by hovering over the tab bar and scrolling. Disabled by default.

New Tab Page

• zen.urlbar.replace-newtab – Focuses the address bar immediately when opening a new tab, allowing for instant searching before the page loads. Enabled by default.
• zen.workspaces.open-new-tab-if-last-unpinned-tab-is-closed – Automatically opens a new tab if all unpinned tabs are closed while pinned tabs remain unloaded. Disabled by default.

Address Bar

• zen.urlbar.hide-one-offs – Hides alternative search engine icons at the bottom of the address bar dropdown. Enabled by default.
• zen.urlbar.show-domain-only-in-sidebar – In single toolbar mode, this displays only the root domain (e.g., example.com) rather than the full URL. Enabled by default.
• zen.urlbar.show-protections-icon – Displays the site security and protection icon in the address bar. Disabled by default.
• zen.urlbar.wait-to-clear – Determines how long (in milliseconds) the address bar retains typed input after losing focus. Default: 45000.

Sidebar

• zen.view.sidebar-collapsed.hide-mute-button – Hides the audio mute icon when the sidebar is in its collapsed state.
• zen.view.sidebar-expanded.max-width – Sets the maximum width for the sidebar in single or multi-toolbar configurations.
• zen.view.sidebar-height-throttle – Internal setting for sidebar rendering. Default: 200.

Window Controls

• zen.view.hide-window-controls – Hides the minimize, maximize, and close buttons. In single toolbar mode, these appear upon hovering. Enabled by default.
• zen.view.experimental-force-window-controls-left – Moves window controls to the left side. If the sidebar is on the left, controls will appear within it. Disabled by default.
• zen.view.experimental-no-window-controls – Completely removes window controls and disables the toolbar in single toolbar mode. Disabled by default.

Workspaces

• zen.workspaces.swipe-actions – Enables switching between workspaces using touchpad swipes on the sidebar. Enabled by default.
• zen.workspaces.wrap-around-navigation – Allows swiping left from the first workspace to reach the last, and vice versa. Enabled by default.
• zen.workspaces.natural-scroll – Reverses the direction of workspace swipe gestures. Disabled by default.
• zen.workspaces.scroll-modifier-key – Sets the modifier key used to switch workspaces by scrolling over the sidebar. Options include ctrl, alt, and shift. Default: ctrl.

Compact Mode

• zen.view.compact.animate-sidebar – Adds an animation to the webpage content when toggling compact mode. Enabled by default.
• zen.view.compact.color-sidebar – Applies your custom theme colors to the sidebar while in compact mode. Enabled by default.
• zen.view.compact.color-toolbar – Applies your custom theme colors to the toolbar while in compact mode. Enabled by default.
• zen.view.show-background-tab-toast – Displays a brief notification when a new tab is opened in the background while in compact mode. Enabled by default.
• zen.view.compact.show-sidebar-and-toolbar-on-hover – Reveals the hidden sidebar and toolbar when the mouse hovers over the edge in compact mode. Enabled by default.
• zen.view.compact.toolbar-flash-popup – Briefly reveals the sidebar whenever a new tab is opened in compact mode. Disabled by default.
• zen.view.compact.toolbar-flash-popup.duration – Sets the duration (in milliseconds) of the sidebar "flash." Default: 800.
• zen.view.compact.toolbar-hide-after-hover.duration – Sets the delay (in milliseconds) before the toolbar hides after the mouse leaves the area. Default: 1000.

Split View

• zen.splitView.enable-tab-drop – Enables split-screen mode by dragging a tab from the sidebar onto an active page. Enabled by default.
• zen.splitView.min-resize-width – Sets the minimum width of a split-view pane as a percentage of the total window width. Default: 7.
• zen.splitView.rearrange-hover-size – Internal hit-box setting for rearranging split tabs. Default: 24.

Media

• zen.mediacontrols.enabled – Displays a media player interface when audio is playing or a specialized UI during video conferences. Enabled by default.
• media.videocontrols.picture-in-picture.enabled – Enables the Picture-in-Picture (PiP) toggle. Enabled by default.
• media.videocontrols.picture-in-picture.enable-when-switching-tabs.enabled – Automatically launches PiP mode when you switch tabs while a video is playing. Disabled by default.

Miscellaneous

• zen.glance.enable-contextmenu-search – Toggles whether right-click searches utilize the "Glance" overlay. Enabled by default.
• zen.keyboard.shortcuts.enabled – Allows users to modify default keyboard shortcuts. Enabled by default.
• zen.glance.open-essential-external-links – Opens external links from "essential" tabs in the Glance preview window. Enabled by default.
• browser.toolbars.bookmarks.visibility – Sets when the bookmarks toolbar is visible (always, newtab, or never). Default: never.
• zen.downloads.download-animation – Toggles the animation that triggers when a download begins. Enabled by default.
• zen.downloads.download-animation-duration – Sets the duration (in milliseconds) of the download animation. Default: 1000.
• zen.haptic-feedback.enabled – (macOS only) Provides haptic feedback during UI interactions like dragging tabs. Enabled by default.
• zen.browser.is-cool – A hardcoded boolean set to true.

Live Theme Editing in Zen Browser

You can customize Zen Browser’s UI in real-time by editing the userChrome.css file.

Step 1: Locate Your Profile Folder

If you are using the Flatpak version, the profile folder is located at: ~/.var/app/app.zen_browser.zen/.zen

For other installations:

1. Open Zen Browser.
2. Enter about:support in the address bar.
3. Under Application Basics, find Profile Folder and click Open Folder.

Step 2: Create the chrome Directory

Inside your profile folder, create a new folder named chrome. Within that folder, create a new text file and name it userChrome.css. Restart Zen Browser to ensure it recognizes the new file.

Step 3: Enable Developer Tools

Beginning with Zen Browser version 1.0.0-a.31, developer tools for the browser UI are disabled by default. To enable them:

1. Navigate to about:config.
2. Set devtools.debugger.remote-enabled to true.
3. Set devtools.chrome.enabled to true.
4. Set toolkit.legacyUserProfileCustomizations.stylesheets to true (this is essential for the browser to read your CSS file).
5. Open the Browser Toolbox by pressing Ctrl + Shift + Alt + I.
6. Go to the Style Editor tab.
7. Use the search bar to locate userChrome.css.

Step 4: Apply Custom Styles

When writing CSS for the browser UI, you may need to add !important to your rules to ensure they override the default system styles.

Pro Tip: To inspect elements that usually disappear (like menus or popups), click the three-dot menu (⋯) in the top right of the Browser Toolbox and select "Disable popup auto-hide."

Any changes saved in the Style Editor (Ctrl + S) will apply instantly, allowing you to fine-tune colors, spacing, and layouts without restarting the browser.

How to Manage Firefox and Zen Profiles

Managing your profiles allows you to back up or migrate essential data, including bookmarks, history, passwords, and open tabs. Note that while you can migrate extensions, their specific settings may not always transfer perfectly.

Step 1: Back Up Your Current Profile

Always close the browser completely before copying profile files to prevent data corruption.

1. Open about:support in the browser.
2. Next to Profile Folder, click Open Folder.
3. Close the browser.

Step 2: Identify Essential Files

You should copy the following files from your profile folder:

• places.sqlite – Bookmarks and browsing history.
• cookies.sqlite – Active login sessions.
• cert9.db, key4.db, logins.json – Encrypted saved passwords.
• extension-preferences.json, extensions.json, extension-settings.json, and the extensions folder – Your installed add-ons.
• search.json.mozlz4 – Custom search engine configurations.
• sessionCheckpoints.json, sessionstore.jsonlz4 – Currently open tabs and windows.
• prefs.js – Your custom about:config preferences.
• Optional: The chrome folder (for UI themes) and the storage folder (for extension data).

Step 3: Set Up a New Profile

If you encounter an "incompatibility" error after moving files to a new profile, locate and delete (or move) the compatibility.ini file within the new profile folder.

1. In the browser, navigate to about:profiles.
2. Select "Create a New Profile" and follow the prompts.
3. Click "Launch profile in new browser" to initialize it, then close that window.
4. Open the new profile's folder via about:support.
5. Ensure the browser is closed, then paste your backed-up files into the new directory, overwriting existing files.

Step 4: Finalize the Setup

Launch the new profile and verify that your data is intact. If everything is correct, return to about:profiles and select "Set as default profile" to make it your primary environment.