Skip to content

Commit 622d83d

Browse files
sean-perkinssean-perkins
committed
chore: overhaul example
1 parent 5141a89 commit 622d83d

23 files changed

+343
-335
lines changed

‎docs/developing/autofocus.md

-29
This file was deleted.

‎docs/developing/managing-focus.md

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
title: Managing Focus
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
<head>
9+
<title>Managing Focus</title>
10+
<meta
11+
name="description"
12+
content="Learn how to manage focus in Ionic applications using the setFocus API instead of the autofocus attribute."
13+
/>
14+
</head>
15+
16+
## Autofocus Attribute
17+
18+
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.
19+
20+
## Managing Focus
21+
22+
Ionic provides a `setFocus` API that allows developers to manually set focus to an element. This API should be used in place of the `autofocus` attribute and called within:
23+
24+
- The `ionViewDidEnter` lifecycle event for routing applications when a page is entered.
25+
- The `didPresent` lifecycle event for overlays when an overlay is presented.
26+
- The `appload` event for vanilla JavaScript applications when the application loads.
27+
- The result of a user gesture or interaction.
28+
29+
### Platform Restrictions
30+
31+
There are platform restrictions you should be aware of when using the `setFocus` API, including:
32+
33+
1. Android requires user interaction before setting focus to an element. This can be as simple as a user tapping on the screen.
34+
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.
35+
36+
### Basic Usage
37+
38+
The example below demonstrates how to use the `setFocus` API to request focus on an input when the user clicks a button.
39+
40+
import Basic from '@site/static/usage/v7/input/set-focus/index.md';
41+
42+
<Basic />
43+
44+
### Routing
45+
46+
Developers can use the `ionViewDidEnter` lifecycle event to set focus to an element when a page is entered.
47+
48+
````mdx-code-block
49+
<Tabs
50+
groupId="framework"
51+
defaultValue="angular"
52+
values={[
53+
{ value: 'angular', label: 'Angular' },
54+
{ value: 'react', label: 'React' },
55+
{ value: 'vue', label: 'Vue' },
56+
]
57+
}>
58+
59+
<TabItem value="angular">
60+
61+
```ts
62+
/* example.component.ts */
63+
import { Component, ViewChild } from '@angular/core';
64+
import { IonInput } from '@ionic/angular';
65+
66+
@Component({
67+
selector: 'app-example',
68+
templateUrl: './example.component.html',
69+
})
70+
export class ExampleComponent {
71+
@ViewChild('input') input!: IonInput;
72+
73+
ionViewDidEnter() {
74+
this.input.setFocus();
75+
}
76+
}
77+
```
78+
</TabItem>
79+
<TabItem value="react">
80+
81+
```tsx
82+
import React, { useRef } from 'react';
83+
import { IonInput, IonPage, useIonViewDidEnter } from '@ionic/react';
84+
85+
const Home = () => {
86+
const input = useRef<HTMLIonInputElement>(null);
87+
88+
useIonViewDidEnter(() => {
89+
input.current?.setFocus();
90+
});
91+
92+
return (
93+
<IonPage>
94+
<IonInput ref={input} label="setFocus" labelPlacement="floating"></IonInput>
95+
</IonPage>
96+
);
97+
};
98+
99+
export default Home;
100+
```
101+
102+
</TabItem>
103+
<TabItem value="vue">
104+
105+
```html
106+
<template>
107+
<ion-page>
108+
<ion-input ref="input" label="setFocus" labelPlacement="floating"></ion-input>
109+
</ion-page>
110+
</template>
111+
112+
<script setup lang="ts">
113+
import { IonInput, IonPage, onIonViewDidEnter } from '@ionic/vue';
114+
import { ref } from 'vue';
115+
116+
const input = ref();
117+
onIonViewDidEnter(() => {
118+
requestAnimationFrame(() => {
119+
// requestAnimationFrame is currently required due to:
120+
// https://github.com/ionic-team/ionic-framework/issues/24434
121+
input.value.$el.setFocus();
122+
});
123+
});
124+
</script>
125+
```
126+
127+
</TabItem>
128+
</Tabs>
129+
````
130+
131+
### Overlays
132+
133+
Developers can use the `didPresent` lifecycle event to set focus to an element when an overlay is presented.
134+
135+
````mdx-code-block
136+
<Tabs
137+
groupId="framework"
138+
defaultValue="javascript"
139+
values={[
140+
{ value: 'javascript', label: 'Javascript' },
141+
{ value: 'angular', label: 'Angular' },
142+
{ value: 'react', label: 'React' },
143+
{ value: 'vue', label: 'Vue' },
144+
]
145+
}>
146+
147+
<TabItem value="javascript">
148+
149+
```html
150+
<ion-modal>
151+
<ion-input></ion-input>
152+
</ion-modal>
153+
154+
<script>
155+
const modal = document.querySelector('ion-modal');
156+
modal.addEventListener('didPresent', () => {
157+
const input = modal.querySelector('ion-input');
158+
input.setFocus();
159+
});
160+
</script>
161+
```
162+
163+
</TabItem>
164+
165+
<TabItem value="angular">
166+
167+
```ts
168+
/* example.component.ts */
169+
import { Component, ViewChild } from '@angular/core';
170+
import { IonInput } from '@ionic/angular';
171+
172+
@Component({
173+
selector: 'app-example',
174+
templateUrl: './example.component.html',
175+
})
176+
export class ExampleComponent {
177+
@ViewChild('input') input!: IonInput;
178+
179+
onDidPresent() {
180+
this.input.setFocus();
181+
}
182+
}
183+
```
184+
185+
```html
186+
<!-- example.component.html -->
187+
<ion-modal (didPresent)="onDidPresent()">
188+
<ion-input #input></ion-input>
189+
</ion-modal>
190+
```
191+
192+
</TabItem>
193+
<TabItem value="react">
194+
195+
```tsx
196+
import React, { useRef } from 'react';
197+
import { IonInput, IonModal, IonPage } from '@ionic/react';
198+
199+
const Home = () => {
200+
const input = useRef<HTMLIonInputElement>(null);
201+
202+
const onDidPresent = () => {
203+
input.current?.setFocus();
204+
};
205+
206+
return (
207+
<IonPage>
208+
<IonModal onDidPresent={onDidPresent}>
209+
<IonInput ref={input}></IonInput>
210+
</IonModal>
211+
</IonPage>
212+
);
213+
};
214+
215+
export default Home;
216+
```
217+
218+
</TabItem>
219+
<TabItem value="vue">
220+
221+
```html
222+
<template>
223+
<ion-page>
224+
<ion-modal @didPresent="onDidPresent">
225+
<ion-input ref="input"></ion-input>
226+
</ion-modal>
227+
</ion-page>
228+
</template>
229+
230+
<script setup lang="ts">
231+
import { IonInput, IonPage, IonModal } from '@ionic/vue';
232+
import { ref } from 'vue';
233+
234+
const input = ref();
235+
236+
function onDidPresent() {
237+
input.value.$el.setFocus();
238+
}
239+
</script>
240+
```
241+
242+
</TabItem>
243+
</Tabs>
244+
````

‎sidebars.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ module.exports = {
2626
'developing/hardware-back-button',
2727
'developing/keyboard',
2828
'developing/config',
29-
'developing/autofocus',
29+
'developing/managing-focus',
3030
],
3131
},
3232
{

‎static/usage/v7/autofocus/basic/angular/app_component_html.md

-3
This file was deleted.

‎static/usage/v7/autofocus/basic/angular/app_component_ts.md

-10
This file was deleted.

‎static/usage/v7/autofocus/basic/angular/app_module_ts.md

-19
This file was deleted.

‎static/usage/v7/autofocus/basic/angular/app_routing_module_ts.md

-19
This file was deleted.

‎static/usage/v7/autofocus/basic/angular/example_component_html.md

-10
This file was deleted.

‎static/usage/v7/autofocus/basic/angular/example_component_ts.md

-17
This file was deleted.

0 commit comments

Comments
 (0)