Skip to content

docs(components): remove legacy syntax sections from all form controls for v8 #4202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 25, 2025
Merged

docs(components): remove legacy syntax sections from all form controls for v8 #4202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ea9b50a
docs(input): removed mentions of legacy syntax support for ion-input
kkindrai Jul 18, 2025
dff8fd3
docs(components): remove all legacy syntax sections from v8
brandyscarney Jul 24, 2025
6b74afc
docs(usage): remove migration code examples from v8
brandyscarney Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 1 addition & 25 deletions docs/api/checkbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ import Justify from '@site/static/usage/v8/checkbox/justify/index.md';
import Indeterminate from '@site/static/usage/v8/checkbox/indeterminate/index.md';

<Indeterminate />

## Links inside of Labels

Checkbox labels can sometimes be accompanied with links. These links can provide more information related to the checkbox. However, clicking the link should not check the checkbox. To achieve this, we can use [stopPropagation](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) to prevent the click event from bubbling. When using this approach, the rest of the label still remains clickable.
Expand Down Expand Up @@ -114,30 +114,6 @@ interface CheckboxCustomEvent<T = any> extends CustomEvent {
}
```

## Migrating from Legacy Checkbox Syntax

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.

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.

### Using the Modern Syntax

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`.

import Migration from '@site/static/usage/v8/checkbox/migration/index.md';

<Migration />


:::note
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.
:::

### Using the Legacy Syntax

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.


## Properties
<Props />

Expand Down
22 changes: 0 additions & 22 deletions docs/api/input.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,28 +188,6 @@ import CSSProps from '@site/static/usage/v8/input/theming/css-properties/index.m

<CSSProps />

## Migrating from Legacy Input Syntax

A simpler input syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an input, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one input at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

### Using the Modern Syntax

Using the modern syntax involves three steps:

1. Remove `ion-label` and use the `label` property on `ion-input` instead. The placement of the label can be configured using the `labelPlacement` property on `ion-input`.
2. Move input-specific properties from `ion-item` on to `ion-input`. This includes the `counter`, `counterFormatter`, `fill`, and `shape` properties.
3. Remove usages of the `helper` and `error` slots on `ion-item` and use the `helperText` and `errorText` properties on `ion-input` instead.

import Migration from '@site/static/usage/v8/input/migration/index.md';

<Migration />

### Using the Legacy Syntax

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

## Interfaces

### InputChangeEventDetail
Expand Down
25 changes: 0 additions & 25 deletions docs/api/radio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,31 +107,6 @@ import CSSParts from '@site/static/usage/v8/radio/theming/css-shadow-parts/index

<CSSParts />

## Migrating from Legacy Radio Syntax

A simpler radio syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an radio, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one radio at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

### Using the Modern Syntax

Using the modern syntax involves removing the `ion-label` and passing the label directly inside of `ion-radio`. The placement of the label can be configured using the `labelPlacement` property on `ion-radio`. The way the label and the control are packed on a line can be controlled using the `justify` property on `ion-radio`.

import Migration from '@site/static/usage/v8/radio/migration/index.md';

<Migration />


:::note
In past versions of Ionic, `ion-item` was required for `ion-radio` to function properly. Starting in Ionic 7.0, `ion-radio` 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-radio` to function properly.
:::

### Using the Legacy Syntax

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



## Properties
<Props />

Expand Down
26 changes: 0 additions & 26 deletions docs/api/range.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,32 +128,6 @@ import CSSParts from '@site/static/usage/v8/range/theming/css-shadow-parts/index

<CSSParts />

## Migrating from Legacy Range Syntax

A simpler range syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an range, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one range at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

### Using the Modern Syntax

Using the modern syntax involves removing the `ion-label` and passing the label to `ion-range` using the `label` property. The placement of the label can be configured using the `labelPlacement` property.

If custom HTML is needed for the label, it can be passed directly inside the `ion-range` using the `label` slot instead.

import Migration from '@site/static/usage/v8/range/migration/index.md';

<Migration />


:::note
In past versions of Ionic, `ion-item` was required for `ion-range` to function properly. Starting in Ionic 7.0, `ion-range` 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-range` to function properly.
:::

### Using the Legacy Syntax

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


## Interfaces

### RangeChangeEventDetail
Expand Down
22 changes: 0 additions & 22 deletions docs/api/select.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,28 +284,6 @@ interface SelectCustomEvent<T = any> extends CustomEvent {
}
```

## Migrating from Legacy Select Syntax

A simpler select syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an select, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one select at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.


### Using the Modern Syntax

Using the modern syntax involves two steps:

1. Remove `ion-label` and use the `label` property on `ion-select` instead. The placement of the label can be configured using the `labelPlacement` property on `ion-select`.
2. Move any usage of `fill` and `shape` from `ion-item` on to `ion-select`.

import Migration from '@site/static/usage/v8/select/migration/index.md';

<Migration />

### Using the Legacy Syntax

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

## Accessibility

### Keyboard Interactions
Expand Down
23 changes: 0 additions & 23 deletions docs/api/textarea.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,29 +127,6 @@ import StartEndSlots from '@site/static/usage/v8/textarea/start-end-slots/index.

<StartEndSlots />

## Migrating from Legacy Textarea Syntax

A simpler textarea syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an textarea, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one textarea at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.


### Using the Modern Syntax

Using the modern syntax involves three steps:

1. Remove `ion-label` and use the `label` property on `ion-textarea` instead. The placement of the label can be configured using the `labelPlacement` property on `ion-textarea`.
2. Move textarea-specific properties from `ion-item` on to `ion-textarea`. This includes the `counter`, `counterFormatter`, `fill`, and `shape` properties.
3. Remove usages of the `helper` and `error` slots on `ion-item` and use the `helperText` and `errorText` properties on `ion-textarea` instead.

import Migration from '@site/static/usage/v8/textarea/migration/index.md';

<Migration />

### Using the Legacy Syntax

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

## Theming

import ThemingPlayground from '@site/static/usage/v8/textarea/theming/index.md';
Expand Down
23 changes: 0 additions & 23 deletions docs/api/toggle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,29 +107,6 @@ import CSSParts from '@site/static/usage/v8/toggle/theming/css-shadow-parts/inde

<CSSParts />

## Migrating from Legacy Toggle Syntax

A simpler toggle syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an toggle, resolves accessibility issues, and improves the developer experience.

While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

### Using the Modern Syntax

Using the modern syntax involves removing the `ion-label` and passing the label directly inside of `ion-toggle`. The placement of the label can be configured using the `labelPlacement` property on `ion-toggle`. The way the label and the control are packed on a line can be controlled using the `justify` property on `ion-toggle`.

import Migration from '@site/static/usage/v8/toggle/migration/index.md';

<Migration />


:::note
In past versions of Ionic, `ion-item` was required for `ion-toggle` to function properly. Starting in Ionic 7.0, `ion-toggle` 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-toggle` to function properly.
:::

### Using the Legacy Syntax

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

## Interfaces

### ToggleChangeEventDetail
Expand Down
12 changes: 6 additions & 6 deletions docs/updating/8-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,13 +215,13 @@ iOS >=15

### Checkbox

1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](../api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](../v7/api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

### Input

1. Remove any usages of the `size` property. CSS should be used to specify the visible width of the input instead.
2. Remove any usages of the `accept` property.
3. Migrate any remaining instances of Input to use the [modern form control syntax](../api/input#migrating-from-legacy-input-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
3. Migrate any remaining instances of Input to use the [modern form control syntax](../v7/api/input#migrating-from-legacy-input-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

### Item

Expand All @@ -243,19 +243,19 @@ iOS >=15

### Radio

1. Migrate any remaining instances of Radio to use the [modern form control syntax](../api/radio#migrating-from-legacy-radio-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
1. Migrate any remaining instances of Radio to use the [modern form control syntax](../v7/api/radio#migrating-from-legacy-radio-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

### Select

1. Migrate any remaining instances of Select to use the [modern form control syntax](../api/select#migrating-from-legacy-select-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
1. Migrate any remaining instances of Select to use the [modern form control syntax](../v7/api/select#migrating-from-legacy-select-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

### Textarea

1. Migrate any remaining instances of Textarea to use the [modern form control syntax](../api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
1. Migrate any remaining instances of Textarea to use the [modern form control syntax](../v7/api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

### Toggle

1. Migrate any remaining instances of Toggle to use the [modern form control syntax](../api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
1. Migrate any remaining instances of Toggle to use the [modern form control syntax](../v7/api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.

## Need Help Upgrading?

Expand Down
Loading
Loading