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.
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.
- 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?
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.
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.
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.
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.