Routing Rules
How link routing works
First-match-wins evaluation, rule order, the fallback browser, the modifier override, and short-link expansion.
Every time you click a web link, BrowserFairy runs through your rules and picks one browser to open it in. This page explains exactly how that decision is made, so you can build rules that route links where you expect.
What happens when you click a link
When you click a link in Mail, Slack, Notes, a calendar, or any other app, macOS hands that link to your default browser. Because BrowserFairy is set as your default browser, the link comes to BrowserFairy first instead of opening a web page.
BrowserFairy does not show a page. It looks at the link, checks it against your rules, decides which browser should handle it, and opens the link there. All of this happens in a moment, so it feels like the link opened straight in the right browser.
Set BrowserFairy as default first
Routing only works when BrowserFairy is your default browser and owns both http and https. If Settings shows BrowserFairy only handles some web links or BrowserFairy is not the default browser, follow Set your default browser before relying on rules.
First match wins
BrowserFairy reads your rules from top to bottom. It uses the first rule that is both turned on and whose conditions match the link, opens that rule's browser, and stops looking.
Here is the order of checks for a single link:
- Start at the top rule in the list.
- Skip the rule if it is turned off.
- If the rule is on, test its conditions against the link.
- If the conditions match, open the link in that rule's browser and stop. No later rules are checked.
- If the conditions do not match, move to the next rule down and repeat.
Because BrowserFairy stops at the first match, only one rule ever handles a link. Turned-off rules are skipped entirely, which is why disabling a rule is a safe way to test a setup without deleting it.
Rule order is priority
Since the first matching rule wins, the order of your rules is their priority. Put specific rules above broad rules, or the broad rule will catch the link first and the specific rule will never get a turn.
Picture two rules:
- A rule for Link address contains
calendar.google.comthat opens your work browser. - A rule for Link address contains
google.comthat opens your personal browser.
A calendar link contains both calendar.google.com and google.com, so both rules match. If the broad google.com rule sits above the specific calendar.google.com rule, every calendar link opens in your personal browser, and the work rule never runs. Move the calendar.google.com rule above the google.com rule and calendar links go to work, while the rest of Google goes to personal.
To change priority, drag a rule up or down in the rules list. The list order is the matching order.
Broad rules can hide specific ones
A rule that matches a lot of links (like one for google.com, or a rule whose condition is left empty so it matches everything) will swallow links you meant for a more specific rule sitting below it. If a specific rule never seems to fire, check whether a broader rule above it is matching first, and drag the specific rule higher.
For how to build the conditions inside a rule, see Create rules. For every available condition and operator, see the Conditions reference.
When the target browser is not installed
If a rule matches but its target browser is not installed on your Mac, BrowserFairy does not stop or show an error. It skips that rule and keeps checking the rules below it, just as if the rule had not matched. The next rule that matches and points to an installed browser wins. If none of the remaining rules match, the link goes to your fallback browser.
This means a rule pointing at a browser you have since removed will quietly hand the link off to the next best rule, rather than failing.
The fallback browser
If BrowserFairy reaches the bottom of your list without a match, it opens the link in your Fallback browser. You set this in Settings under General, in the Fallback browser row, described as Opens links when no rule matches. It starts out as whatever browser was your system default before you installed BrowserFairy, and you can change it to any installed browser.
The fallback is your safety net: anything your rules do not cover still opens somewhere sensible.
BrowserLauncherForce the Browser Launcher with a key
Sometimes you want to pick a browser by hand for one link, even though a rule would route it automatically. Hold the Browser Launcher modifier key (Option by default) while clicking a link, and BrowserFairy skips routing and opens the Browser Launcher instead, so you can choose a browser yourself.
This override beats your rules: as long as you are holding the key when you click, the launcher appears no matter which rule would have matched. You can change the key, or use the global shortcut (⌥⌘B by default) to open a standalone picker. See Keyboard shortcuts for both, and Browser Launcher for what the picker can do.
Short links are expanded before matching
Some links are shorteners that redirect to a longer address (for example a bit.ly link that lands on a specific page). A rule written for the final destination would never match the short link itself, so BrowserFairy expands certain short links before checking your rules.
This only happens for links that look genuinely short: a short address (about 30 characters or fewer) with a small host, a short path, and no ? query or # fragment. For one of those, BrowserFairy does a quick lookup that follows the redirect, with a 2 second timeout, and then matches your rules against the final address it lands on. If the lookup is slow or fails, it falls back to matching the original short link as is.
Normal, everyday links are never expanded. They are matched exactly as you clicked them, with no extra network request, so routing stays instant.
Write rules for the real destination
Because short links are expanded first, a rule for the page they lead to (such as a rule for figma.com) will catch a short link that redirects there, even though the short link does not contain that text.