What Is It?
When you preview on multiple devices at once, Browser Sync makes events that happen on one device happen on all others simultaneously.
Click a link on your Mac and it's tapped on your iPhone, too. Enter text into a form on your iPad; it shows up everywhere else.
Note: Fast Network Needed
Browser Sync won't work well if your network is slow or congested (i.e. public WiFi). In those cases, turn it off.
Which Events Sync?
Control which events sync by choosing CodeKit > Preferences from the menubar, then selecting Browsers. Changes take effect immediately.
Click
Any click event that occurs on an element other than <body> is recreated on all other devices. All the JavaScript event details (such as which mouse button was pressed) are recreated as well, so your scripts can react appropriately.
Input
Any text typed into a form field or changes to a <select> element are synced. Note: for text entry, CodeKit fires an onInput event and resets the entire string value of the target textfield (as opposed to adding or removing characters one at a time). This is more robust on weaker networks.
Focus & Blur
Any time an element is focused or blurred, that same element will be focused or blurred on other devices. There are a few caveats:
- Browsers won't focus an element unless their window is active. If you have two Chrome windows viewing the same page, the window in the "background" won't focus an element until you switch to it.
- iOS won't open the keyboard when an element is focused via JavaScript. You must tap the screen to get the keyboard.
- When a browser window becomes "inactive", it automatically fires a blur event on all page elements. Likewise, when the window becomes active, it fires a focus event on the element that had focus when the window moved to the background. These events are NOT synced; you don't want them to be.
Bottom line: as you switch browser windows, CodeKit will move the focus to whichever element had it in the old window.
KeyUp & KeyDown
Some scripts use these events to change form appearance, etc. If you need these synced, it's best to choose only one or the other. Otherwise, for every character you type, CodeKit must send three events: KeyDown, Input, KeyUp. This can get unwieldy.
When these events are synced, all KeyboardEvent properties are recreated on every device, so you can inspect the event to determine if modifier keys were pressed, which letter was typed, etc.
It's Not Working!
Here's what to check:
- Is your network fast and stable?
- Are you using a modern browser? You must be on iOS 7+, Android 4.4+ and IE 11+.
- Is the DOM 100% valid? If you're missing a tag or using invalid symbols such as ":" or "/" in an ID or Class name, that will break syncing. In this case, CodeKit should log an error to your browser's console.
- Is one of your scripts intercepting and canceling the event during the capturing phase?
- JavaScript is single-threaded. If your site is running a massive JS task when the sync events arrive, they won't be handled until your task completes. (They may also be dropped or superseded by later events.)
Technical Details
Event Capturing
CodeKit listens for most events on the <body> element and dispatches them during the "capturing" phase. Focus and Blur events are the exception. CodeKit listens for these on the window element so that it can detect when the event is the result of a browser window becoming or resigning active status.
Events that target elements above <body> (such as document) will not be synced.
Because events are handled in the "capturing" (as opposed to "bubbling") phase, events that are canceled with preventDefault() and those that do not bubble (Focus and Blur) are still synced. The presumption is that your scripts on other devices will react to these events the same way and cancel them as needed.
If you have scripts that modify events during the capturing phase, those could potentially conflict with CodeKit and cause unexpected behavior. In that case, disable Browser Sync.
Event Recreation
Events are synced with all information intact. For example, if you provide a custom details property on an event, that property will be available when the event arrives on other devices. Some information, however, such as the timestamp of the event and the view object will obviously be different.
Targeting
When an event is dispatched, CodeKit records the full path from the <body> element to the event's target element as a query selector. If the DOM is invalid because of a syntax error, this path may be incorrect or unresolvable. In that case, CodeKit should log an error message to your browser's console.
If the DOM structure differs across devices—for example, if you use JavaScript to remove certain elements on small screens rather than simply hiding them—CodeKit may not be able to find the correct event target element. Or, it may fire an event on the wrong element altogether.
Page Addresses Are Ignored
CodeKit does not verify that all devices are viewing the same page before syncing events. This is intentional. It lets you click a link and immediately snap all devices to that page.
Blur & Focus Delayed Slightly
To handle browser idiosyncrasies, CodeKit waits a fraction of a second between the time a Focus or Blur event is detected and the time it's dispatched to other devices. It's possible that another event such as Input or KeyUp could occur in that time and, consequently, the Blur or Focus event may arrive on other devices out of order.