add docs for the Navigation API #21960
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| --- | ||
| title: NavigateEvent.canIntercept | ||
| slug: Web/API/NavigateEvent/canIntercept | ||
| page-type: web-api-instance-property | ||
| tags: | ||
| - API | ||
| - canIntercept | ||
| - Experimental | ||
| - History | ||
| - Navigate | ||
| - NavigateEvent | ||
| - Navigation | ||
| - Navigation API | ||
| - Property | ||
| - Read-only | ||
| - Reference | ||
| - Scroll | ||
| - Traversal | ||
| browser-compat: api.NavigateEvent.canIntercept | ||
| --- | ||
|
|
||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`canIntercept`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns `true` if the navigation can be intercepted, or `false` otherwise (e.g. you can't intercept a cross-origin navigation). | ||
|
|
||
| ## Value | ||
|
|
||
| A boolean value—`true` if the navigation can be intercepted, `false` if not. | ||
|
|
||
| ## Examples | ||
|
|
||
| ```js | ||
| navigation.addEventListener("navigate", event => { | ||
| // Some navigations, e.g. cross-origin navigations, we | ||
| // cannot intercept. Let the browser handle those normally. | ||
| if (!event.canIntercept) { | ||
| return; | ||
| } | ||
|
|
||
| // Don't intercept fragment navigations or downloads. | ||
| if (event.hashChange || event.downloadRequest !== null) { | ||
| return; | ||
| } | ||
|
|
||
| event.intercept({ | ||
| handler() { | ||
| if (event.formData) { | ||
| processFormDataAndUpdateUI(event.formData, event.signal); | ||
| } else { | ||
| doSinglePageAppNav(event.destination, event.signal); | ||
| } | ||
| } | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) | ||
| - [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) | ||
| - Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| --- | ||
| title: NavigateEvent.destination | ||
| slug: Web/API/NavigateEvent/destination | ||
| page-type: web-api-instance-property | ||
| tags: | ||
| - API | ||
| - destination | ||
| - Experimental | ||
| - History | ||
| - Navigate | ||
| - NavigateEvent | ||
| - Navigation | ||
| - Navigation API | ||
| - Property | ||
| - Read-only | ||
| - Reference | ||
| - Scroll | ||
| - Traversal | ||
| browser-compat: api.NavigateEvent.destination | ||
| --- | ||
|
|
||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`destination`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns a {{domxref("NavigationDestination")}} object representing the destination being navigated to. | ||
|
|
||
| ## Value | ||
|
|
||
| A {{domxref("NavigationDestination")}} object. | ||
|
|
||
| ## Examples | ||
|
|
||
| ```js | ||
| navigation.addEventListener('navigate', (event) => { | ||
| // Exit early if this navigation shouldn't be intercepted, | ||
| // e.g. if the navigation is cross-origin, or a download request | ||
| if (shouldNotIntercept(event)) { | ||
| return; | ||
| } | ||
|
|
||
| const url = new URL(event.destination.url); | ||
|
|
||
| if (url.pathname.startsWith('/articles/')) { | ||
| event.intercept({ | ||
| async handler() { | ||
| // The URL has already changed, so show a placeholder while | ||
| //fetching the new content, such as a spinner or loading page | ||
| renderArticlePagePlaceholder(); | ||
|
|
||
| // Fetch the new content and display when ready | ||
| const articleContent = await getArticleContent(url.pathname); | ||
| renderArticlePage(articleContent); | ||
| }, | ||
| }); | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) | ||
| - [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) | ||
| - Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| --- | ||
| title: NavigateEvent.downloadRequest | ||
| slug: Web/API/NavigateEvent/downloadRequest | ||
| page-type: web-api-instance-property | ||
| tags: | ||
| - API | ||
| - downloadRequest | ||
| - Experimental | ||
| - History | ||
| - Navigate | ||
| - NavigateEvent | ||
| - Navigation | ||
| - Navigation API | ||
| - Property | ||
| - Read-only | ||
| - Reference | ||
| - Scroll | ||
| - Traversal | ||
| browser-compat: api.NavigateEvent.downloadRequest | ||
| --- | ||
|
|
||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`downloadRequest`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns the filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise. | ||
|
|
||
| ## Value | ||
|
|
||
| A string containing the filename of the file requested for download, or `null`. | ||
|
|
||
| ## Examples | ||
|
|
||
| ```js | ||
| navigation.addEventListener("navigate", (event) => { | ||
| // Some navigations, e.g. cross-origin navigations, we | ||
| // cannot intercept. Let the browser handle those normally. | ||
| if (!event.canIntercept) { | ||
| return; | ||
| } | ||
|
|
||
| // Don't intercept fragment navigations or downloads. | ||
| if (event.hashChange || event.downloadRequest !== null) { | ||
| return; | ||
| } | ||
|
|
||
| event.intercept({ | ||
| handler() { | ||
| if (event.formData) { | ||
| processFormDataAndUpdateUI(event.formData, event.signal); | ||
| } else { | ||
| doSinglePageAppNav(event.destination, event.signal); | ||
| } | ||
| } | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) | ||
| - [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) | ||
| - Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,70 @@ | ||||||
| --- | ||||||
| title: NavigateEvent.formData | ||||||
| slug: Web/API/NavigateEvent/formData | ||||||
| page-type: web-api-instance-property | ||||||
| tags: | ||||||
| - API | ||||||
| - Experimental | ||||||
| - formData | ||||||
| - History | ||||||
| - Navigate | ||||||
| - NavigateEvent | ||||||
| - Navigation | ||||||
| - Navigation API | ||||||
| - Property | ||||||
| - Read-only | ||||||
| - Reference | ||||||
| - Scroll | ||||||
| - Traversal | ||||||
| browser-compat: api.NavigateEvent.formData | ||||||
| --- | ||||||
|
|
||||||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||||||
|
|
||||||
| The **`formData`** read-only property of the | ||||||
| {{domxref("NavigateEvent")}} interface returns the {{domxref("FormData")}} object representing the submitted data in the case of a `POST` form submission, or `null` otherwise. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Thanks; I've updated this. |
||||||
|
|
||||||
| ## Value | ||||||
|
|
||||||
| A {{domxref("FormData")}} object, or `null`. | ||||||
|
|
||||||
| ## Examples | ||||||
|
|
||||||
| ```js | ||||||
| navigation.addEventListener("navigate", (event) => { | ||||||
| // Some navigations, e.g. cross-origin navigations, we | ||||||
| // cannot intercept. Let the browser handle those normally. | ||||||
| if (!event.canIntercept) { | ||||||
| return; | ||||||
| } | ||||||
|
|
||||||
| // Don't intercept fragment navigations or downloads. | ||||||
| if (event.hashChange || event.downloadRequest !== null) { | ||||||
| return; | ||||||
| } | ||||||
|
|
||||||
| event.intercept({ | ||||||
| handler() { | ||||||
| if (event.formData) { | ||||||
| processFormDataAndUpdateUI(event.formData, event.signal); | ||||||
| } else { | ||||||
| doSinglePageAppNav(event.destination, event.signal); | ||||||
| } | ||||||
| } | ||||||
| }); | ||||||
| }); | ||||||
| ``` | ||||||
|
|
||||||
| ## Specifications | ||||||
|
|
||||||
| {{Specifications}} | ||||||
|
|
||||||
| ## Browser compatibility | ||||||
|
|
||||||
| {{Compat}} | ||||||
|
|
||||||
| ## See also | ||||||
|
|
||||||
| - [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) | ||||||
| - [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) | ||||||
| - Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| --- | ||
| title: NavigateEvent.hashChange | ||
| slug: Web/API/NavigateEvent/hashChange | ||
| page-type: web-api-instance-property | ||
| tags: | ||
| - API | ||
| - Experimental | ||
| - hashChange | ||
| - History | ||
| - Navigate | ||
| - NavigateEvent | ||
| - Navigation | ||
| - Navigation API | ||
| - Property | ||
| - Read-only | ||
| - Reference | ||
| - Scroll | ||
| - Traversal | ||
| browser-compat: api.NavigateEvent.hashChange | ||
| --- | ||
|
|
||
| {{APIRef("Navigation API")}}{{seecompattable}} | ||
|
|
||
| The **`hashChange`** read-only property of the | ||
| {{domxref("NavigateEvent")}} interface returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise. | ||
|
|
||
| ## Value | ||
|
|
||
| A boolean value—`true` if the navigation is a fragment navigation, `false` if not. | ||
|
|
||
| ## Examples | ||
|
|
||
| ```js | ||
| navigation.addEventListener("navigate", (event) => { | ||
| // Some navigations, e.g. cross-origin navigations, we | ||
| // cannot intercept. Let the browser handle those normally. | ||
| if (!event.canIntercept) { | ||
| return; | ||
| } | ||
|
|
||
| // Don't intercept fragment navigations or downloads. | ||
| if (event.hashChange || event.downloadRequest !== null) { | ||
| return; | ||
| } | ||
|
|
||
| event.intercept({ | ||
| handler() { | ||
| if (event.formData) { | ||
| processFormDataAndUpdateUI(event.formData, event.signal); | ||
| } else { | ||
| doSinglePageAppNav(event.destination, event.signal); | ||
| } | ||
| } | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/) | ||
| - [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md) | ||
| - Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be helpful to explain this a little more. Whenever I see an explanation that's only "e.g." I think, well this is an example, but what are the other cases?
The spec says:
I don't like "Generally speaking" there, but at least "can have its URL rewritten" seems to have a clear definition: https://html.spec.whatwg.org/multipage/nav-history-apis.html#can-have-its-url-rewritten. For "except for cross-document back/forward navigations, where it will always be false" I did find this on cross-document navigation: https://chromium.googlesource.com/chromium/src/+/main/docs/navigation_concepts.md#same_document-and-cross_document-navigations , which is presented as a Chromium thing but that seems comprehensible.
So could we say something like:
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The full explanation for this case goes beyond this, and requires reading the whole table at https://github.com/wicg/navigation-api#appendix-types-of-navigations . That's why the non-normative (for web developers) part of the spec uses the vague phrase "generally speaking", because it's too complex to summarize quickly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW As a reader the normative information is what I want first; a general summary that will apply for most circumstances - because most of the time I'm reading for the gist.
But I would absolutely also want more precision on the most common cases as @wbamberg has done for http, https and file. If it can't be cannonical as a list, I'd note that "there are a number of other cases listed in the specification, covering X, Y, Z".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've rewritten this to provide some examples, using some of Will's text, but I've also linked out to the spec for full information. This is one of those cases in which I don't think it's worth trying to repeat the full explanation on MDN. I think most web devs won't need it.