Skip to content

Commit bdba34c

Browse files
liamdebeasiliamdebeasi
authored
docs(checkbox): update for new syntax, add migration guide (#2751)
1 parent 75c5838 commit bdba34c

31 files changed

+502
-119
lines changed

‎docs/api/checkbox.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,27 @@ import Basic from '@site/static/usage/v7/checkbox/basic/index.md';
2727

2828
<Basic />
2929

30+
## Label Placement
31+
32+
Developers can use the `labelPlacement` property to control how the label is placed relative to the control.
33+
34+
import LabelPlacement from '@site/static/usage/v7/checkbox/label-placement/index.md';
35+
36+
<LabelPlacement />
37+
38+
## Justification
39+
40+
Developers can use the `justify` property to control how the label and control are packed on a line.
41+
42+
import Justify from '@site/static/usage/v7/checkbox/justify/index.md';
43+
44+
<Justify />
45+
46+
47+
:::note
48+
`ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly.
49+
:::
50+
3051
## Indeterminate Checkboxes
3152

3253
import Indeterminate from '@site/static/usage/v7/checkbox/indeterminate/index.md';
@@ -63,7 +84,28 @@ interface CheckboxCustomEvent<T = any> extends CustomEvent {
6384
}
6485
```
6586

87+
## Migrating from Legacy Checkbox Syntax
88+
89+
A simpler checkbox syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup a checkbox, resolves accessibility issues, and improves the developer experience.
90+
91+
Developers can perform this migration one checkbox at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.
92+
93+
### Using the Modern Syntax
94+
95+
Using the modern syntax involves removing the `ion-label` and passing the label directly inside of `ion-checkbox`. The placement of the label can be configured using the `labelPlacement` property on `ion-checkbox`. The way the label and the control are packed on a line can be controlled using the `justify` property on `ion-checkbox`.
96+
97+
import Migration from '@site/static/usage/v7/checkbox/migration/index.md';
98+
99+
<Migration />
100+
101+
102+
:::note
103+
In past versions of Ionic, `ion-item` was required for `ion-checkbox` to function properly. Starting in Ionic 7.0, `ion-checkbox` should only be used in an `ion-item` when the item is placed in an `ion-list`. Additionally, `ion-item` is no longer required for `ion-checkbox` to function properly.
104+
:::
105+
106+
### Using the Legacy Syntax
66107

108+
Ionic uses heuristics to detect if an app is using the modern checkbox syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the `legacy` property on `ion-checkbox` to `true` to force that instance of the checkbox to use the legacy syntax.
67109

68110

69111
## Properties

‎static/usage/v7/checkbox/basic/angular.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
```html
2-
<ion-item>
3-
<ion-checkbox slot="start"></ion-checkbox>
4-
<ion-label>I agree to the terms and conditions</ion-label>
5-
</ion-item>
2+
<ion-checkbox>I agree to the terms and conditions</ion-checkbox>
63
```

‎static/usage/v7/checkbox/basic/demo.html

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,18 @@
77
<title>Checkbox</title>
88
<link rel="stylesheet" href="../../../common.css" />
99
<script src="../../../common.js"></script>
10-
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@6/dist/ionic/ionic.esm.js"></script>
11-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@6/css/ionic.bundle.css" />
10+
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7.0.0-beta.1/dist/ionic/ionic.esm.js"></script>
11+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7.0.0-beta.1/css/ionic.bundle.css" />
1212
</head>
1313

1414
<body>
1515
<ion-app>
1616
<ion-content>
1717
<div class="container">
18-
<ion-item>
19-
<ion-checkbox slot="start"></ion-checkbox>
20-
<ion-label>I agree to the terms and conditions</ion-label>
21-
</ion-item>
18+
<ion-checkbox>I agree to the terms and conditions</ion-checkbox>
2219
</div>
2320
</ion-content>
2421
</ion-app>
2522
</body>
2623

27-
</html>
24+
</html>

‎static/usage/v7/checkbox/basic/javascript.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
```html
2-
<ion-item>
3-
<ion-checkbox slot="start"></ion-checkbox>
4-
<ion-label>I agree to the terms and conditions</ion-label>
5-
</ion-item>
2+
<ion-checkbox>I agree to the terms and conditions</ion-checkbox>
63
```

‎static/usage/v7/checkbox/basic/react.md

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
11
```tsx
22
import React from 'react';
3-
import {
4-
IonCheckbox,
5-
IonItem,
6-
IonLabel
7-
} from '@ionic/react';
3+
import { IonCheckbox } from '@ionic/react';
84

95
function Example() {
106
return (
11-
<IonItem>
12-
<IonCheckbox slot="start"></IonCheckbox>
13-
<IonLabel>I agree to the terms and conditions</IonLabel>
14-
</IonItem>
7+
<IonCheckbox>I agree to the terms and conditions</IonCheckbox>
158
);
169
}
1710
export default Example;

‎static/usage/v7/checkbox/basic/vue.md

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,14 @@
11
```html
22
<template>
3-
<ion-item>
4-
<ion-checkbox slot="start"></ion-checkbox>
5-
<ion-label>I agree to the terms and conditions</ion-label>
6-
</ion-item>
3+
<ion-checkbox>I agree to the terms and conditions</ion-checkbox>
74
</template>
85

96
<script lang="ts">
10-
import {
11-
IonCheckbox,
12-
IonItem,
13-
IonLabel
14-
} from '@ionic/vue';
7+
import { IonCheckbox } from '@ionic/vue';
158
import { defineComponent } from 'vue';
169
1710
export default defineComponent({
18-
components: {
19-
IonCheckbox,
20-
IonItem,
21-
IonLabel
22-
}
11+
components: { IonCheckbox }
2312
});
2413
</script>
2514
```

‎static/usage/v7/checkbox/indeterminate/angular.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
```html
2-
<ion-item>
3-
<ion-checkbox slot="start" [indeterminate]="true"></ion-checkbox>
4-
<ion-label>Indeterminate checkbox</ion-label>
5-
</ion-item>
2+
<ion-checkbox [indeterminate]="true">Indeterminate checkbox</ion-checkbox>
63
```

‎static/usage/v7/checkbox/indeterminate/demo.html

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,18 @@
77
<title>Checkbox</title>
88
<link rel="stylesheet" href="../../../common.css" />
99
<script src="../../../common.js"></script>
10-
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@6/dist/ionic/ionic.esm.js"></script>
11-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@6/css/ionic.bundle.css" />
10+
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7.0.0-beta.1/dist/ionic/ionic.esm.js"></script>
11+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7.0.0-beta.1/css/ionic.bundle.css" />
1212
</head>
1313

1414
<body>
1515
<ion-app>
1616
<ion-content>
1717
<div class="container">
18-
<ion-item>
19-
<ion-checkbox slot="start" indeterminate="true"></ion-checkbox>
20-
<ion-label>Indeterminate checkbox</ion-label>
21-
</ion-item>
18+
<ion-checkbox indeterminate="true">Indeterminate checkbox</ion-checkbox>
2219
</div>
2320
</ion-content>
2421
</ion-app>
2522
</body>
2623

27-
</html>
24+
</html>

‎static/usage/v7/checkbox/indeterminate/javascript.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
```html
2-
<ion-item>
3-
<ion-checkbox slot="start" indeterminate="true"></ion-checkbox>
4-
<ion-label>Indeterminate checkbox</ion-label>
5-
</ion-item>
2+
<ion-checkbox indeterminate="true">Indeterminate checkbox</ion-checkbox>
63
```

‎static/usage/v7/checkbox/indeterminate/react.md

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
11
```tsx
22
import React from 'react';
3-
import {
4-
IonCheckbox,
5-
IonItem,
6-
IonLabel
7-
} from '@ionic/react';
3+
import { IonCheckbox } from '@ionic/react';
84

95
function Example() {
106
return (
11-
<IonItem>
12-
<IonCheckbox slot="start" indeterminate={true}></IonCheckbox>
13-
<IonLabel>Indeterminate checkbox</IonLabel>
14-
</IonItem>
7+
<IonCheckbox indeterminate={true}>Indeterminate checkbox</IonCheckbox>
158
);
169
}
1710
export default Example;

0 commit comments

Comments
 (0)