Skip to content

Commit 0fccd65

Browse files
brandyscarneybrandyscarney
authored
docs(app): add documentation and demo for the setFocus method (#3842)
1 parent 54ad011 commit 0fccd65

File tree

8 files changed

+203
-1
lines changed

8 files changed

+203
-1
lines changed

‎docs/api/app.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ import Slots from '@ionic-internal/component-api/v8/app/slots.md';
1515

1616
import EncapsulationPill from '@components/page/api/EncapsulationPill';
1717

18-
1918
App is a container element for an Ionic application. There should only be one `<ion-app>` element per project. An app can have many Ionic components including menus, headers, content, and footers. The overlay components get appended to the `<ion-app>` when they are presented.
2019

2120
Using `ion-app` enables the following behaviors:
@@ -27,6 +26,13 @@ Using `ion-app` enables the following behaviors:
2726
* [Ripple effect](./ripple-effect) when activating buttons on Material Design mode
2827
* Other tap and focus utilities which make the experience of using an Ionic app feel more native
2928

29+
## Programmatic Focus
30+
31+
Ionic offers focus utilities for components with the `ion-focusable` class. These utilities automatically manage focus for components when certain keyboard keys, like <kbd>Tab</kbd>, are pressed. Components can also be programmatically focused in response to user actions using the `setFocus` method from `ion-app`.
32+
33+
import SetFocus from '@site/static/usage/v8/app/set-focus/index.md';
34+
35+
<SetFocus />
3036

3137
## Properties
3238
<Props />

‎static/usage/v8/app/set-focus/angular/example_component_html.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
```html
2+
<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
3+
4+
<ion-radio-group value="a">
5+
<ion-radio id="radioToFocus" value="a">Radio</ion-radio>
6+
</ion-radio-group>
7+
8+
<br />
9+
10+
<ion-button (click)="focusElement('#buttonToFocus')">Focus Button</ion-button>
11+
<ion-button (click)="focusElement('#radioToFocus')">Focus Radio</ion-button>
12+
```

‎static/usage/v8/app/set-focus/angular/example_component_ts.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
```ts
2+
import { Component } from '@angular/core';
3+
4+
@Component({
5+
selector: 'app-example',
6+
templateUrl: 'example.component.html',
7+
styleUrls: ['example.component.css'],
8+
})
9+
export class ExampleComponent {
10+
focusElement(id: string) {
11+
const el = document.querySelector(id) as HTMLElement;
12+
13+
const app = el.closest('ion-app');
14+
if (app) {
15+
app.setFocus([el]);
16+
}
17+
}
18+
}
19+
```

‎static/usage/v8/app/set-focus/demo.html

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>App</title>
7+
<link rel="stylesheet" href="../../common.css" />
8+
<script src="../../common.js"></script>
9+
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@8/dist/ionic/ionic.esm.js"></script>
10+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@8/css/ionic.bundle.css" />
11+
12+
<style>
13+
.container {
14+
display: grid;
15+
grid-template-columns: repeat(2, auto);
16+
column-gap: 10px;
17+
justify-items: center;
18+
}
19+
</style>
20+
</head>
21+
22+
<body>
23+
<ion-app>
24+
<ion-content>
25+
<div class="container">
26+
<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
27+
28+
<ion-radio-group value="a">
29+
<ion-radio id="radioToFocus" value="a">Radio</ion-radio>
30+
</ion-radio-group>
31+
32+
<ion-button onClick="focusElement('#buttonToFocus')">Focus Button</ion-button>
33+
<ion-button onClick="focusElement('#radioToFocus')">Focus Radio</ion-button>
34+
</div>
35+
36+
<script>
37+
function focusElement(id) {
38+
const el = document.querySelector(id);
39+
40+
const app = el.closest('ion-app');
41+
if (app) {
42+
app.setFocus([el]);
43+
}
44+
}
45+
</script>
46+
</ion-content>
47+
</ion-app>
48+
</body>
49+
</html>

‎static/usage/v8/app/set-focus/index.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import Playground from '@site/src/components/global/Playground';
2+
3+
import javascript from './javascript.md';
4+
import react from './react.md';
5+
import vue from './vue.md';
6+
7+
import angular_example_component_html from './angular/example_component_html.md';
8+
import angular_example_component_ts from './angular/example_component_ts.md';
9+
10+
<Playground
11+
version="8"
12+
code={{
13+
javascript,
14+
react,
15+
vue,
16+
angular: {
17+
files: {
18+
'src/app/example.component.html': angular_example_component_html,
19+
'src/app/example.component.ts': angular_example_component_ts,
20+
},
21+
},
22+
}}
23+
src="usage/v8/app/set-focus/demo.html"
24+
size="sm"
25+
/>

‎static/usage/v8/app/set-focus/javascript.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
```html
2+
<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
3+
4+
<ion-radio-group value="a">
5+
<ion-radio id="radioToFocus" value="a">Radio</ion-radio>
6+
</ion-radio-group>
7+
8+
<br />
9+
10+
<ion-button onClick="focusElement('#buttonToFocus')">Focus Button</ion-button>
11+
<ion-button onClick="focusElement('#radioToFocus')">Focus Radio</ion-button>
12+
13+
<script>
14+
function focusElement(id) {
15+
const el = document.querySelector(id);
16+
17+
const app = el.closest('ion-app');
18+
if (app) {
19+
app.setFocus([el]);
20+
}
21+
}
22+
</script>
23+
```

‎static/usage/v8/app/set-focus/react.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
```tsx
2+
import React from 'react';
3+
import { IonButton, IonRadio, IonRadioGroup } from '@ionic/react';
4+
5+
function Example() {
6+
function focusElement(id: string) {
7+
const el = document.querySelector(id) as HTMLElement;
8+
9+
const app = el.closest('ion-app');
10+
if (app) {
11+
app.setFocus([el]);
12+
}
13+
}
14+
15+
return (
16+
<>
17+
<IonButton id="buttonToFocus" fill="outline">
18+
Button
19+
</IonButton>
20+
21+
<IonRadioGroup value="a">
22+
<IonRadio id="radioToFocus" value="a">
23+
Radio
24+
</IonRadio>
25+
</IonRadioGroup>
26+
27+
<br />
28+
29+
<IonButton onClick={() => focusElement('#buttonToFocus')}>Focus Button</IonButton>
30+
<IonButton onClick={() => focusElement('#radioToFocus')}>Focus Radio</IonButton>
31+
</>
32+
);
33+
}
34+
export default Example;
35+
```

‎static/usage/v8/app/set-focus/vue.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
```html
2+
<template>
3+
<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
4+
5+
<ion-radio-group value="a">
6+
<ion-radio id="radioToFocus" value="a">Radio</ion-radio>
7+
</ion-radio-group>
8+
9+
<br />
10+
11+
<ion-button @click="focusElement('#buttonToFocus')">Focus Button</ion-button>
12+
<ion-button @click="focusElement('#radioToFocus')">Focus Radio</ion-button>
13+
</template>
14+
15+
<script lang="ts">
16+
import { IonButton, IonRadio, IonRadioGroup } from '@ionic/vue';
17+
import { defineComponent } from 'vue';
18+
19+
export default defineComponent({
20+
components: { IonButton, IonRadio, IonRadioGroup },
21+
methods: {
22+
focusElement(id) {
23+
const el = document.querySelector(id);
24+
25+
const app = el.closest('ion-app');
26+
if (app) {
27+
app.setFocus([el]);
28+
}
29+
},
30+
},
31+
});
32+
</script>
33+
```

0 commit comments

Comments
 (0)