diff --git a/docs/developing/managing-focus.md b/docs/developing/managing-focus.md new file mode 100644 index 00000000000..01b112ea68c --- /dev/null +++ b/docs/developing/managing-focus.md @@ -0,0 +1,238 @@ +--- +title: Managing Focus +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + Managing Focus + + + +Ionic provides a `setFocus` API on components such as [Input](../api/input), [Searchbar](../api/searchbar), and [Textarea](../api/textarea) that allows developers to manually set focus to an element. This API should be used in place of the `autofocus` attribute and called within: + +- The `ionViewDidEnter` lifecycle event for routing applications when a page is entered. +- The `didPresent` lifecycle event for overlays when an overlay is presented. +- The `appload` event for vanilla JavaScript applications when the application loads. +- The result of a user gesture or interaction. + +## Why not autofocus? + +The `autofocus` attribute is a standard HTML attribute that allows developers to set focus to an element when a page loads. This attribute is commonly used to set focus to the first input element on a page. However, the `autofocus` attribute can cause issues in routing applications when navigating between pages. This is because the `autofocus` attribute will set focus to the element when the page loads, but will not set focus to the element when the page is revisited. Learn more about the `autofocus` attribute in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus). + +## Platform Restrictions + +There are platform restrictions you should be aware of when using the `setFocus` API, including: + +1. Android requires user interaction before setting focus to an element. This can be as simple as a user tapping on the screen. +2. Interactive elements can only focused a result of a user gesture on Mobile Safari (iOS), such as calling `setFocus` as the result of a button click. + +## Basic Usage + +The example below demonstrates how to use the `setFocus` API to request focus on an input when the user clicks a button. + +import Basic from '@site/static/usage/v7/input/set-focus/index.md'; + + + +## Routing + +Developers can use the `ionViewDidEnter` lifecycle event to set focus to an element when a page is entered. + +````mdx-code-block + + + + +```ts +/* example.component.ts */ +import { Component, ViewChild } from '@angular/core'; +import { IonInput } from '@ionic/angular'; + +@Component({ + selector: 'app-example', + templateUrl: './example.component.html', +}) +export class ExampleComponent { + @ViewChild('input') input!: IonInput; + + ionViewDidEnter() { + this.input.setFocus(); + } +} +``` + + + +```tsx +import React, { useRef } from 'react'; +import { IonInput, IonPage, useIonViewDidEnter } from '@ionic/react'; + +const Home = () => { + const input = useRef(null); + + useIonViewDidEnter(() => { + input.current?.setFocus(); + }); + + return ( + + + + ); +}; + +export default Home; +``` + + + + +```html + + + +``` + + + +```` + +## Overlays + +Developers can use the `didPresent` lifecycle event to set focus to an element when an overlay is presented. + +````mdx-code-block + + + + +```html + + + + + +``` + + + + + +```ts +/* example.component.ts */ +import { Component, ViewChild } from '@angular/core'; +import { IonInput } from '@ionic/angular'; + +@Component({ + selector: 'app-example', + templateUrl: './example.component.html', +}) +export class ExampleComponent { + @ViewChild('input') input!: IonInput; + + onDidPresent() { + this.input.setFocus(); + } +} +``` + +```html + + + + +``` + + + + +```tsx +import React, { useRef } from 'react'; +import { IonInput, IonModal } from '@ionic/react'; + +const Home = () => { + const input = useRef(null); + + const onDidPresent = () => { + input.current?.setFocus(); + }; + + return ( + + + + ); +}; + +export default Home; +``` + + + + +```html + + + +``` + + + +```` diff --git a/sidebars.js b/sidebars.js index 069e5ec59dc..ac8d9c721d8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -26,6 +26,7 @@ module.exports = { 'developing/hardware-back-button', 'developing/keyboard', 'developing/config', + 'developing/managing-focus', ], }, { diff --git a/static/usage/v7/input/set-focus/angular.md b/static/usage/v7/input/set-focus/angular.md new file mode 100644 index 00000000000..92c9d6b2561 --- /dev/null +++ b/static/usage/v7/input/set-focus/angular.md @@ -0,0 +1,10 @@ +```html + + + Click to set focus + + + + + +``` diff --git a/static/usage/v7/input/set-focus/demo.html b/static/usage/v7/input/set-focus/demo.html new file mode 100644 index 00000000000..7ebd39bec3a --- /dev/null +++ b/static/usage/v7/input/set-focus/demo.html @@ -0,0 +1,33 @@ + + + + + + setFocus + + + + + + + + + + + + Click to set focus + + + + + + + + + + diff --git a/static/usage/v7/input/set-focus/index.md b/static/usage/v7/input/set-focus/index.md new file mode 100644 index 00000000000..4728673f041 --- /dev/null +++ b/static/usage/v7/input/set-focus/index.md @@ -0,0 +1,17 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; +import angular from './angular.md'; +import vue from './vue.md'; +import react from './react.md'; + + diff --git a/static/usage/v7/input/set-focus/javascript.md b/static/usage/v7/input/set-focus/javascript.md new file mode 100644 index 00000000000..1d5a5b4cfbc --- /dev/null +++ b/static/usage/v7/input/set-focus/javascript.md @@ -0,0 +1,17 @@ +```html + + + Click to set focus + + + + + + + +``` diff --git a/static/usage/v7/input/set-focus/react.md b/static/usage/v7/input/set-focus/react.md new file mode 100644 index 00000000000..023abbd8968 --- /dev/null +++ b/static/usage/v7/input/set-focus/react.md @@ -0,0 +1,21 @@ +```tsx +import React, { useRef } from 'react'; +import { IonInput, IonItem, IonList, IonButton } from '@ionic/react'; + +const Home = () => { + const input = useRef(null); + + return ( + + + input.current?.setFocus()}>Click to set focus + + + + + + ); +}; + +export default Home; +``` diff --git a/static/usage/v7/input/set-focus/vue.md b/static/usage/v7/input/set-focus/vue.md new file mode 100644 index 00000000000..84ee1879142 --- /dev/null +++ b/static/usage/v7/input/set-focus/vue.md @@ -0,0 +1,23 @@ +```html + + + +```