This document covers the user-facing interfaces of uBlock Origin: the popup panel, dashboard, and logger UI. It describes the structure, components, and localization system. For implementation details of content scripts and DOM manipulation tools, see page 5.
uBlock Origin provides three primary user interfaces:
popup-fenix.html / popup-fenix.js) — Quick access interface from the browser toolbar, providing per-site controls and statisticsdashboard.html) — Multi-tab configuration interface for settings, filter lists, and custom ruleslogger-ui.html / logger-ui.js) — Real-time diagnostic tool for monitoring requests and creating filtersAll interfaces are fully localized through a message-based system using messages.json files under _locales/, supporting approximately 60 languages.
UI file map:
| UI Surface | HTML | JavaScript | CSS |
|---|---|---|---|
| Popup panel | popup-fenix.html | popup-fenix.js | popup-fenix.css |
| Dashboard | dashboard.html | dashboard-common.js, per-tab *.js | dashboard-common.css |
| Logger | logger-ui.html | logger-ui.js | logger-ui.css |
| Element picker | epicker-ui.html | epicker.js, epicker-ui.js | epicker.css |
| About page | about.html | about.js | about.css |
UI entry-point and navigation diagram:
Sources: src/popup-fenix.html1-115 src/js/popup-fenix.js1-50 src/_locales/en/messages.json1-70
All user-facing strings are stored in messages.json files organized by locale code under _locales/. Each locale directory contains a single messages.json. The i18n.js module exposes the i18n$() function used throughout the UI JavaScript.
Message entry format (src/_locales/en/messages.json1-10):
Runtime behavior: i18n.js scans the DOM for data-i18n and data-i18n-title attributes and replaces element text or title with the localized string. Placeholder substitution uses {{variableName}} syntax.
HTML example from about.html:
Key message categories:
| Category | Example Keys | Purpose |
|---|---|---|
| Extension metadata | extName, extShortDesc | Extension name / store description |
| Dashboard tabs | settingsPageName, 3pPageName, 1pPageName, rulesPageName | Tab labels |
| Popup interface | popupPowerSwitchInfo, popupBlockedRequestPrompt | Popup panel text |
| Settings | settingsCollapseBlockedPrompt, settingsIconBadgePrompt | Settings checkboxes |
| Logger | logRequestsHeaderType, loggerCurrentTab | Logger column headers |
| Tooltips | popupTipDashboard, popupTipZapper, popupTipPicker | Icon tooltips |
Sources: src/_locales/en/messages.json1-69 src/about.html21-28
The popup panel (popup-fenix.html + popup-fenix.js + popup-fenix.css) appears when clicking the uBlock Origin toolbar icon. It communicates with the background via the popupPanel messaging channel.
Popup data flow and rendering functions:
Sources: src/js/popup-fenix.js74-140 src/js/popup-fenix.js590-692 src/popup-fenix.html17-94
The #switch element toggles filtering for the site or page:
The body receives CSS class off when filtering is disabled, which changes the fill/stroke of the power SVG icon. Message keys: popupPowerSwitchInfo, popupPowerSwitchInfo1, popupPowerSwitchInfo2.
Sources: src/js/popup-fenix.js595-600 src/css/popup-fenix.css82-85
#basicStats)The renderPopup() function populates #basicStats from popupData.pageCounts and popupData.globalBlockedRequestCount. The formatNumber() helper formats counts ≥ 1M using Intl.NumberFormat compact notation.
| Statistic | popupData field | Message key |
|---|---|---|
| Blocked on this page | pageCounts.blocked.any | popupBlockedOnThisPage_v2 |
| Blocked since install | globalBlockedRequestCount | popupBlockedSinceInstall_v2 |
| Domains connected | built by renderPrivacyExposure() | popupDomainsConnected_v2 |
The domain count string uses popupHitDomainCount: "{{count}} out of {{total}}".
Sources: src/js/popup-fenix.js621-652 src/js/popup-fenix.js149-187 src/js/popup-fenix.js531-574
#extraTools)Five .hnSwitch elements in #extraTools are synced by updateHnSwitches(). Each receives the CSS class on when the switch is active.
| Element ID | popupData field | Caption key |
|---|---|---|
#no-popups | noPopups | popupNoPopups_v2 |
#no-large-media | noLargeMedia | popupNoLargeMedia_v2 |
#no-cosmetic-filtering | noCosmeticFiltering | popupNoCosmeticFiltering_v2 |
#no-remote-fonts | noRemoteFonts | popupNoRemoteFonts_v2 |
#no-scripting | noScripting | popupNoScripting_v2 |
Each switch element carries a badge (fa-icon-badge) to show a blocked count where relevant (e.g., popup count, large media count, remote font count).
Sources: src/js/popup-fenix.js578-584 src/popup-fenix.html47-52 src/_locales/en/messages.json190-209
#firewall)The #firewall div holds the point-and-click dynamic filtering grid. buildAllFirewallRows() constructs rows from popupData.hostnameDict, sorted by hostnameCompare() using hostnameToSortableTokenMap. Rows are incrementally updated by reusing existing DOM elements.
updateAllFirewallCells() reads popupData.firewallRules (keyed as "scope des type") and applies CSS classes allowRule, blockRule, noopRule, and ownRule to each cell. Request count indicators use CSS ::before/::after pseudo-elements with data-acount / data-bcount attributes.
Controls:
| Element | i18n key | Action |
|---|---|---|
#saveRules | popupTipSaveRules | Persist changes permanently |
#revertRules | popupTipRevertRules | Discard unsaved changes |
#refresh | — | Reload the page |
Built-in row types in #firewall (from popup-fenix.html):
data-type | Message key | Meaning |
|---|---|---|
* | popupAnyRulePrompt | All resource types |
image | popupImageRulePrompt | Images |
3p | popup3pAnyRulePrompt | All 3rd-party |
inline-script | popupInlineScriptRulePrompt | Inline scripts |
1p-script | popup1pScriptRulePrompt | 1st-party scripts |
3p-script | popup3pScriptRulePrompt | 3rd-party scripts |
3p-frame | popup3pFrameRulePrompt | 3rd-party frames |
The firewall pane can be filtered via the #firewall .filterExpressions section. Filter expressions (blocked/allowed/script/frame, with negation) are persisted to vAPI.localStorage under the key firewallFilters.
Sources: src/js/popup-fenix.js251-441 src/js/popup-fenix.js462-527 src/popup-fenix.html83-93 src/_locales/en/messages.json218-285
The dashboard (dashboard.html) is a multi-tab configuration interface. Each tab is loaded as an iframe pane. Navigation between tabs is handled by dashboard-common.js.
Dashboard tab structure:
Sources: src/about.html1-65 src/_locales/en/messages.json10-65
The Settings tab contains general configuration options organized into sections:
Appearance Section (settingsAppearance)
settingsThemeLabel)settingsThemeAccent0Label)settingsColorBlindPrompt)settingsTooltipsPrompt)settingsIconBadgePrompt)Default Behavior Section (settingPerSiteSwitchGroup)
settingsNoCosmeticFilteringPrompt)settingsNoLargeMediaPrompt)settingsNoRemoteFontsPrompt)settingsNoScriptingPrompt)settingsNoCSPReportsPrompt)Advanced Section (settingsAdvanced)
settingsAdvancedUserPrompt)settingsAdvancedUserSettings)settingsPrefetchingDisabledPrompt)settingsHyperlinkAuditingDisabledPrompt)settingsWebRTCIPAddressHiddenPrompt)settingsUncloakCnamePrompt)Cloud Storage (settingsCloudStorageEnabledPrompt)
Sources: src/_locales/en/messages.json318-413
Manages third-party filter list subscriptions. Shows network and cosmetic filter counts with the format: 3pListsOfBlockedHostsPrompt - "{{netFilterCount}} network filters + {{cosmeticFilterCount}} cosmetic filters from:"
Controls:
3pAutoUpdatePrompt1)3pUpdateNow)3pPurgeAll)3pApplyChanges)Options:
3pParseAllABPHideFiltersPrompt1)3pIgnoreGenericCosmeticFilters)3pSuspendUntilListsAreLoaded)Filter List Groups:
Each list shows "{{used}} used out of {{total}}" (3pListsOfBlockedHostsPerListStats)
| Group | Message Key | Description |
|---|---|---|
| Built-in | 3pGroupDefault | Core uBlock Origin lists |
| Ads | 3pGroupAds | Advertising blocklists |
| Privacy | 3pGroupPrivacy | Tracking protection |
| Malware | 3pGroupMalware | Security lists |
| Social | 3pGroupSocial | Social widget blocking |
| Cookies | 3pGroupCookies | Cookie notice blocking |
| Annoyances | 3pGroupAnnoyances | Annoyance lists |
| Multipurpose | 3pGroupMultipurpose | Multi-category lists |
| Regions | 3pGroupRegions | Language-specific lists |
| Custom | 3pGroupCustom | User-imported lists |
Import custom lists: Use 3pImport with hint 3pExternalListsHint - "One URL per line. Invalid URLs will be silently ignored."
List status indicators:
3pLastUpdate - Last update timestamp tooltip3pUpdating - Update in progress3pNetworkError - Update failed3pExternalListObsolete - Out of date warning3pViewContent - View list contentsSources: src/_locales/en/messages.json422-537
Manages custom static filters created by the user.
Controls:
1pEnableMyFiltersLabel)1pTrustMyFiltersLabel)1pImport)1pExport)1pApplyChanges)Export filename format: 1pExportFilename - "my-ublock-static-filters_{{datetime}}.txt"
Warning: 1pTrustWarning - "Do not add filters from untrusted sources."
Sources: src/_locales/en/messages.json538-565
Manages dynamic filtering rules with separate permanent and temporary sections.
Rule syntax hint: rulesFormatHint - "Rule syntax: source destination type action (full documentation)"
Export filename: rulesDefaultFileName - "my-ublock-dynamic-rules_{{datetime}}.txt"
Sources: src/_locales/en/messages.json566-629
Manages whitelist/exception sites where uBlock Origin is disabled.
Description: whitelistPrompt - "The trusted site directives dictate on which web pages uBlock Origin should be disabled. One entry per line."
Controls:
whitelistImport)whitelistExport)whitelistApply)Export filename: whitelistExportFilename - "my-ublock-trusted-sites_{{datetime}}.txt"
Sources: src/_locales/en/messages.json630-649
Configures keyboard shortcuts for common actions.
Shortcut actions include:
toggleCosmeticFiltering)toggleJavascript)relaxBlockingMode)Shortcuts use placeholder shortcutCapturePlaceholder - "Type a shortcut" for input capture.
Sources: src/_locales/en/messages.json1255-1279
Displays version information, credits, and backup/restore functionality.
The About page is implemented in three files:
The JavaScript retrieves application data via messaging:
Error messages:
aboutRestoreDataError - "The data could not be read or is invalid"errorCantConnectTo - "Network error: {{msg}}"Sources: src/_locales/en/messages.json1019-1090 src/about.html1-65 src/js/about.js1-33
Provides documentation links and issue reporting tools.
Documentation Section (supportS1H)
supportS1P1Questions Section (supportS2H)
supportS2P1Filter Issues Section (supportS3H)
supportS3P1)supportS3P2)supportS3P3)Bug Reports Section (supportS4H)
supportS4P1)Troubleshooting Section (supportS5H)
supportS5P1)Filter Issue Reporter (supportS6H)
supportS6URL)supportS6Select1)supportS6Checkbox1)supportReportSpecificButton)supportFindSpecificButton)Sources: src/_locales/en/messages.json899-1018
The logger provides real-time monitoring of network requests and filtering decisions, with tools for diagnosing issues and creating filters.
Toolbar buttons:
loggerReloadTip)loggerClearTip)loggerPauseTip)loggerUnpauseTip)loggerDomInspectorTip)loggerPopupPanelTip)loggerInfoTip)Row filtering toggle: loggerRowFiltererButtonTip
Built-in filter expressions (loggerRowFiltererBuiltinTip):
loggerRowFiltererBuiltinNot - Negation operatorloggerRowFiltererBuiltinEventful - Show only actionable eventsloggerRowFiltererBuiltinBlocked - Blocked requests onlyloggerRowFiltererBuiltinAllowed - Allowed requests onlyloggerRowFiltererBuiltinModified - Modified requestsloggerRowFiltererBuiltin1p - First-party requestsloggerRowFiltererBuiltin3p - Third-party requestsConfigurable retention settings with message loggerSettingDiscardPrompt:
| Setting | Message Key | Description |
|---|---|---|
| Entry age | loggerSettingPerEntryMaxAge | Preserve entries from last {{input}} minutes |
| Page loads | loggerSettingPerTabMaxLoads | Preserve at most {{input}} page loads per tab |
| Max entries | loggerSettingPerTabMaxEntries | Preserve at most {{input}} entries per tab |
| Line count | loggerSettingPerEntryLineCount | Use {{input}} lines per entry in expanded mode |
Column visibility (loggerSettingHideColumnsPrompt):
When clicking a log entry, the details pane shows:
loggerEntryDetailsFilter)loggerEntryDetailsFilterList)loggerEntryDetailsRule)loggerEntryDetailsContext)loggerEntryDetailsRootContext)loggerEntryDetailsPartyness)loggerEntryDetailsType)loggerEntryDetailsURL)The static filtering wizard (loggerStaticFilteringHeader) generates filter syntax using a sentence template (loggerStaticFilteringSentence):
"{{action}} network requests of {{type}} which URL address matches {{url}} and which originates {{origin}}, {{importance}} there is a matching exception filter."
Sentence components:
loggerStaticFilteringSentencePartBlock or loggerStaticFilteringSentencePartAllowloggerStaticFilteringSentencePartType or loggerStaticFilteringSentencePartAnyTypeloggerStaticFilteringSentencePartOrigin or loggerStaticFilteringSentencePartAnyOriginloggerStaticFilteringSentencePartImportant or loggerStaticFilteringSentencePartNotImportantFilter finder:
loggerStaticFilteringFinderSentence1 - "Static filter {{filter}} found in:"loggerStaticFilteringFinderSentence2 - "Static filter could not be found in any enabled lists"Creates dynamic rules (loggerURLFilteringHeader) with context and type selectors:
loggerURLFilteringContextLabel)loggerURLFilteringTypeLabel)Export log entries in different formats:
loggerExportFormatList)loggerExportFormatTable)loggerExportEncodePlain)loggerExportEncodeMarkdown)Sources: src/_locales/en/messages.json650-897
Interactive tool for creating cosmetic filters by clicking on page elements.
Message keys:
pickerContextMenuEntry - "Block element..."pickerCreatepickerPickpickerQuitpickerPreviewpickerNetFilterspickerCosmeticFilterspickerCosmeticFiltersHint - "Click, Ctrl-click"The picker can create two types of filters:
Temporary element removal tool accessible via popupTipZapper - "Enter element zapper mode". Unlike the picker, the zapper removes elements without creating permanent filters.
Advanced diagnostic tool integrated into the logger UI (loggerDomInspectorTip). Allows inspection of the DOM tree to understand filtering decisions and element visibility.
Browser context menu entries (settingsContextMenuPrompt - "Make use of context menu where appropriate"):
contextMenuBlockElementInFrame)contextMenuSubscribeToList)contextMenuTemporarilyAllowLargeMediaElements)contextMenuViewSource)Sources: src/_locales/en/messages.json286-317 src/_locales/en/messages.json1239-1254
All UI pages communicate with the background process via vAPI.messaging (implemented in vapi-client.js). Each UI surface uses a named channel registered in messaging.js on the background side.
Channel map:
Common message patterns:
| Pattern | what field | Description |
|---|---|---|
| Fetch popup state | getPopupData | Returns popupData including firewallRules, hostnameDict, switch states |
| Fetch app info | getAppData | Returns name, version (used by about.js) |
| Update setting | userSettings | Persists a user setting change |
| Dismiss warning | dismissUnprocessedRequest | Clears the unprocessed-request warning |
| Reload tab | reloadTab | Triggers a tab reload from the popup |
Generic UI message keys (for shared button labels):
genericApplyChanges, genericRevert, genericSubmitgenericCopyToClipboard, genericSelectAllgenericMergeViewScrollLockSources: src/js/popup-fenix.js44-46 src/js/about.js26-32 src/_locales/en/messages.json1223-1270
When strict blocking prevents a page from loading, a special document-blocked page displays.
Components:
docblockedTitle - "Page blocked"docblockedPrompt1 - "uBlock Origin has prevented the following page from loading:"docblockedPrompt2 - "This happened because of the following filter:"docblockedFoundIn - "The filter has been found in:"Actions:
docblockedBackdocblockedClosedocblockedDontWarndocblockedProceed with options:
docblockedDisableTemporarydocblockedDisablePermanentdocblockedDisableBlocking reasons:
docblockedReasonMaliciousdocblockedReasonTrackerdocblockedReasonDisreputableRedirect warning: docblockedRedirectPrompt alerts if the blocked page attempts redirection.
Sources: src/_locales/en/messages.json1131-1198
When cloud storage is enabled (settingsCloudStorageEnabledPrompt), the UI provides cloud synchronization controls.
Cloud actions:
cloudPushcloudPullcloudPullAndMergecloudDeviceNamePromptcloudNoData - "...\n..."Sources: src/_locales/en/messages.json1199-1218
A separate page for power users (advancedSettingsPageName) with warning message advancedSettingsWarning - "Warning! Change these advanced settings at your own risk."
This page allows direct modification of internal configuration values that aren't exposed in the regular Settings tab.
Sources: src/_locales/en/messages.json66-69 src/_locales/en/messages.json1219-1221
The UI uses relative time formatting for displaying timestamps:
| Duration | Message Key | Format |
|---|---|---|
| 1 minute | elapsedOneMinuteAgo | "a minute ago" |
| Multiple minutes | elapsedManyMinutesAgo | "{{value}} minutes ago" |
| 1 hour | elapsedOneHourAgo | "an hour ago" |
| Multiple hours | elapsedManyHoursAgo | "{{value}} hours ago" |
| 1 day | elapsedOneDayAgo | "a day ago" |
| Multiple days | elapsedManyDaysAgo | "{{value}} days ago" |
Generic byte formatting: genericBytes
Sources: src/_locales/en/messages.json1095-1238
This comprehensive UI system ensures uBlock Origin remains accessible to users worldwide while providing both simple quick-access controls and advanced diagnostic tools for power users. The modular design with clear separation between popup, dashboard, and logger interfaces allows each component to serve its specific purpose effectively.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.