From 0b62e40a6e9755d40bb470a4542673b6ac2f06aa Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Fri, 14 Feb 2025 20:17:53 -0500 Subject: [PATCH] Mention navigator.onLine false negatives (#38052) --- files/en-us/web/api/navigator/online/index.md | 27 +++---------------- 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/files/en-us/web/api/navigator/online/index.md b/files/en-us/web/api/navigator/online/index.md index 2ea76299822b3d5..522a5db24f2174c 100644 --- a/files/en-us/web/api/navigator/online/index.md +++ b/files/en-us/web/api/navigator/online/index.md @@ -8,30 +8,9 @@ browser-compat: api.Navigator.onLine {{ApiRef("HTML DOM")}} -Returns the online status of the browser. The property returns a boolean value, with -`true` meaning online and `false` meaning offline. The property -sends updates whenever the browser's ability to connect to the network changes. The -update occurs when the user follows links or when a script requests a remote page. For -example, the property should return `false` when users click links soon after -they lose internet connection. - -Browsers implement this property differently. - -In Chrome and Safari, if the browser is not able to connect to a local area network -(LAN) or a router, it is offline; all other conditions return `true`. So -while you can assume that the browser is offline when it returns a `false` -value, you cannot assume that a true value necessarily means that the browser can access -the internet. You could be getting false positives, such as in cases where the computer -is running a virtualization software that has virtual ethernet adapters that are always -"connected." Therefore, if you really want to determine the online status of the -browser, you should develop additional means for checking. - -In Firefox, switching the browser to offline mode sends a `false` value. Until Firefox -41, all other conditions returned a `true` value; testing actual behavior on Nightly 68 on -Windows shows that it only looks for LAN connection like Chrome and Safari giving false -positives. - -You can see changes in the network state by listening to the [`online`](/en-US/docs/Web/API/Window/online_event) and [`offline`](/en-US/docs/Web/API/Window/offline_event) events. +The **`onLine`** property of the {{domxref("Navigator")}} interface returns whether the device is connected to the network, with `true` meaning online and `false` meaning offline. The property's value changes after the browser checks its network connection, usually when the user follows links or when a script requests a remote page. For example, the property should return `false` when users click links soon after they lose internet connection. When its value changes, an [`online`](/en-US/docs/Web/API/Window/online_event) or [`offline`](/en-US/docs/Web/API/Window/offline_event) event is fired on the `window`. + +Browsers and operating systems leverage different heuristics to determine whether the device is online. In general, connection to LAN is considered online, even though the LAN may not have Internet access. For example, the computer may be running a virtualization software that has virtual ethernet adapters that are always "connected". On Windows, the online status is determined by whether it can reach a Microsoft home server, which may be blocked by firewalls or VPNs, even if the computer has Internet access. Therefore, this property is inherently unreliable, and you should not disable features based on the online status, only provide hints when the user may seem offline. ## Value