From 2b442d1569190b8a210233fe72f7f67ed9d8e3b8 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Thu, 11 Dec 2025 14:19:51 -0800 Subject: [PATCH 01/15] docs(react-router): working on v9 migration docs for react router --- docs/react/add-to-existing.md | 19 +-- docs/react/navigation.md | 210 ++++++++++++---------------------- docs/react/quickstart.md | 32 ++---- docs/react/your-first-app.md | 18 +-- docs/updating/9-0.md | 70 ++++++++++++ 5 files changed, 161 insertions(+), 188 deletions(-) diff --git a/docs/react/add-to-existing.md b/docs/react/add-to-existing.md index eee23e0f10c..0311d50d170 100644 --- a/docs/react/add-to-existing.md +++ b/docs/react/add-to-existing.md @@ -300,23 +300,16 @@ Then, create `src/pages/Home.css`: #### 5. Set up Routing -:::important - -Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React. - -::: - Install the router packages: ```bash -npm install @ionic/react-router react-router@5 react-router-dom@5 -npm install @types/react-router-dom --save-dev +npm install @ionic/react-router react-router react-router-dom ``` Then, update `src/App.tsx` to add the routes for the Home page: ```tsx title="src/App.tsx" -import { Redirect, Route } from 'react-router-dom'; +import { Route, Navigate } from 'react-router-dom'; import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react'; import { IonReactRouter } from '@ionic/react-router'; import Home from './pages/Home'; @@ -329,12 +322,8 @@ const App: React.FC = () => ( - - - - - - + } /> + } /> diff --git a/docs/react/navigation.md b/docs/react/navigation.md index 9b7129667e9..36de9eba055 100644 --- a/docs/react/navigation.md +++ b/docs/react/navigation.md @@ -30,33 +30,28 @@ const App: React.FC = () => ( - - + } /> + } /> ); ``` -Directly after the `Route`, we define our default `Redirect`, which, when a user visits the root URL of the app ("/"), it redirects them to the "/dashboard" URL. +Directly after the `Route`, we define our default `Navigate`, which, when a user visits the root URL of the app ("/"), redirects them to the "/dashboard" URL. -The redirect also has the `exact` prop set, which means the URL has to match the `from` prop (or the `path` prop if `exact` was used on a `Route`) precisely for this route to be a match. Without it, this redirect would render for every route, since every route begins with "/". - -You can also programmatically redirect from a Route's render method based on a condition, like checking if a user is authed or not: +You can also conditionally redirect based on a condition, like checking if a user is authenticated or not: ```tsx { - return isAuthed ? : ; - }} + element={isAuthed ? : } /> ``` ## IonReactRouter -The `IonReactRouter` component wraps the traditional [`BrowserRouter`](https://v5.reactrouter.com/web/api/BrowserRouter) component from React Router, and sets the app up for routing. Therefore, use `IonReactRouter` in place of `BrowserRouter`. You can pass in any props to `IonReactRouter` and they will be passed down to the underlying `BrowserRouter`. +The `IonReactRouter` component wraps the traditional [`BrowserRouter`](https://reactrouter.com/en/main/router-components/browser-router) component from React Router, and sets the app up for routing. Therefore, use `IonReactRouter` in place of `BrowserRouter`. You can pass in any props to `IonReactRouter` and they will be passed down to the underlying `BrowserRouter`. ## Nested Routes @@ -69,8 +64,8 @@ const DashboardPage: React.FC = () => { return ( - - + } /> + } /> ); @@ -79,23 +74,6 @@ const DashboardPage: React.FC = () => { Here, there are a couple more routes defined to point to pages from within the dashboard portion of the app. Note, that we need to define the whole route in the path, and we can't leave off "/dashboard" even though we arrived to this page from that URL. React Router requires full paths, and relative paths are not supported. -However, we can use the [`match`](https://v5.reactrouter.com/web/api/match) objects `url` property to provide the URL that was matched to render a component, which helps when working with nested routes: - -```tsx -const DashboardPage: React.FC = ({ match }) => { - return ( - - - - - - - ); -}; -``` - -Here, `match.url` contains the value of "/dashboard", since that was the URL used to render the `DashboardPage`. - These routes are grouped in an `IonRouterOutlet`, let's discuss that next. ## IonRouterOutlet @@ -104,39 +82,39 @@ The `IonRouterOutlet` component provides a container for Routes that render Ioni The `DashboardPage` above shows a users list page and a details page. When navigating between the two pages, the `IonRouterOutlet` provides the appropriate platform page transition and keeps the state of the previous page intact so that when a user navigates back to the list page, it appears in the same state as when it left. -An `IonRouterOutlet` should only contain `Route`s or `Redirect`s. Any other component should be rendered either as a result of a `Route` or outside of the `IonRouterOutlet`. +An `IonRouterOutlet` should only contain `Route`s. Any other component should be rendered either as a result of a `Route` or outside of the `IonRouterOutlet`. ## Fallback Route A common routing use case is to provide a "fallback" route to be rendered in the event the location navigated to does not match any of the routes defined. -We can define a fallback route by placing a `Route` component without a `path` property as the last route defined within an `IonRouterOutlet`. +We can define a fallback route by placing a `Route` component with a `path` of `"*"` as the last route defined within an `IonRouterOutlet`. **DashboardPage.tsx** ```tsx -const DashboardPage: React.FC = ({ match }) => { +const DashboardPage: React.FC = () => { return ( - - - } /> + } /> + } /> + } /> ); }; ``` -Here, we see that in the event a location does not match the first two `Route`s the `IonRouterOutlet` will redirect the Ionic React app to the `match.url` path. +Here, we see that in the event a location does not match the first two `Route`s the `IonRouterOutlet` will redirect the Ionic React app to the `/dashboard` path. You can alternatively supply a component to render instead of providing a redirect. ```tsx -const DashboardPage: React.FC = ({ match }) => { +const DashboardPage: React.FC = () => { return ( - - - + } /> + } /> + } /> ); }; @@ -199,7 +177,7 @@ Other components that have the `routerLink` prop are `IonButton`, `IonCard`, `Io Each of these components also have a `routerDirection` prop to explicitly set the type of page transition to use (`"forward"`, `"back"`, or `"root"`). -Outside of these components that have the `routerLink` prop, you can also use React Routers [`Link`](https://v5.reactrouter.com/web/api/Link) component to navigate between views: +Outside of these components that have the `routerLink` prop, you can also use React Router's [`Link`](https://reactrouter.com/en/main/components/link) component to navigate between views: ```html User 1 @@ -207,34 +185,38 @@ Outside of these components that have the `routerLink` prop, you can also use Re We recommend using one of the above methods whenever possible for routing. The advantage to these approaches is that they both render an anchor (``)tag, which is suitable for overall app accessibility. -A programmatic option for navigation is using the [`history`](https://v5.reactrouter.com/web/api/history) prop that React Router provides to the components it renders via routes. +For programmatic navigation, use the `useIonRouter` hook (see [Utilities](#useionrouter)) or React Router's [`useNavigate`](https://reactrouter.com/en/main/hooks/use-navigate) hook: ```tsx - { - e.preventDefault(); - history.push('/dashboard/users/1'); - }} -> - Go to User 1 - -``` +import { useNavigate } from 'react-router-dom'; -:::note -`history` is a prop. -::: +const MyComponent: React.FC = () => { + const navigate = useNavigate(); + + return ( + { + e.preventDefault(); + navigate('/dashboard/users/1'); + }} + > + Go to User 1 + + ); +}; +``` -### Navigating using `history.go` +### Navigating using `navigate` with delta -React Router uses the `history` package which has a [history.go](https://github.com/remix-run/history/blob/dev/docs/api-reference.md#history.go) method that allows developers to move forward or backward through the application history. Let's take a look at an example. +React Router's `navigate` function can accept a delta number to move forward or backward through the application history. Let's take a look at an example. Say you have the following application history: `/pageA` --> `/pageB` --> `/pageC` -If you were to call `router.go(-2)` on `/pageC`, you would be brought back to `/pageA`. If you then called `router.go(2)`, you would be brought to `/pageC`. +If you were to call `navigate(-2)` on `/pageC`, you would be brought back to `/pageA`. If you then called `navigate(2)`, you would be brought to `/pageC`. -Using `history.go()` in Ionic React is not supported at the moment. Interested in seeing support for this get added to Ionic React? [Let us know on GitHub](https://github.com/ionic-team/ionic-framework/issues/23775)! +Using `navigate()` with delta values in Ionic React is not supported at the moment. Interested in seeing support for this get added to Ionic React? [Let us know on GitHub](https://github.com/ionic-team/ionic-framework/issues/23775)! ## URL Parameters @@ -243,12 +225,11 @@ The second route defined in the Dashboard Page has a URL parameter defined (the **UserDetailPage.tsx** ```tsx -interface UserDetailPageProps - extends RouteComponentProps<{ - id: string; - }> {} +import { useParams } from 'react-router-dom'; + +const UserDetailPage: React.FC = () => { + const { id } = useParams<{ id: string }>(); -const UserDetailPage: React.FC = ({ match }) => { return ( @@ -256,15 +237,15 @@ const UserDetailPage: React.FC = ({ match }) => { User Detail - User {match.params.id} + User {id} ); }; ``` -The [`match`](https://v5.reactrouter.com/web/api/match) prop contains information about the matched route, including the URL params. We obtain the `id` param here and display it on the screen. +The [`useParams`](https://reactrouter.com/en/main/hooks/use-params) hook returns an object containing the URL parameters. We obtain the `id` param here and display it on the screen. -Note how we use a TypeScript interface to strongly type the props object. The interface gives us type safety and code completion inside of the component. +Note how we use a TypeScript generic to strongly type the params object. This gives us type safety and code completion inside of the component. ## Linear Routing versus Non-Linear Routing @@ -318,7 +299,7 @@ Why is this non-linear routing? The previous view we were on was the `Search` vi If tapping the back button simply called `history.go(-1)` from the `Ted Lasso` view, we would be brought back to the `Search` view which is not correct. -Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `history.go()` cannot be used in this non-linear environment. This means that `history.go()` should not be used when using tabs or nested outlets. +Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `navigate()` with delta values cannot be used in this non-linear environment. This means that `navigate(-1)` or similar delta navigation should not be used when using tabs or nested outlets. ### Which one should I choose? @@ -343,12 +324,8 @@ const App: React.FC = () => ( - - - - - - + } /> + } /> @@ -366,9 +343,7 @@ const App: React.FC = () => ( - - - + } /> @@ -376,17 +351,13 @@ const App: React.FC = () => ( const DashboardRouterOutlet: React.FC = () => ( - - - - - - + } /> + } /> ); ``` -The above routes are nested because they are in the `children` array of the parent route. Notice that the parent route renders the `DashboardRouterOutlet` component. When you nest routes, you need to render another instance of `IonRouterOutlet`. +The above routes are nested because they are in the `children` array of the parent route. Notice that the parent route renders the `DashboardRouterOutlet` component and uses a `/*` suffix to match all sub-paths. When you nest routes, you need to render another instance of `IonRouterOutlet`. ### Which one should I choose? @@ -404,23 +375,20 @@ When working with tabs, Ionic needs a way to know which view belongs to which ta - } /> - - - + } /> + } /> ``` -Here, our `tabs` path loads a `Tabs` component. We provide each tab as a route object inside of this component. In this example, we call the path `tabs`, but this can be customized. +Here, our `tabs` path loads a `Tabs` component. We provide each tab as a route object inside of this component. In this example, we call the path `tabs`, but this can be customized. Note the `/*` suffix which allows the route to match all sub-paths within tabs. Let's start by taking a look at our `Tabs` component: ```tsx -import { Redirect, Route } from 'react-router-dom'; +import { Route, Navigate } from 'react-router-dom'; import { IonIcon, IonLabel, IonRouterOutlet, IonTabBar, IonTabButton, IonTabs } from '@ionic/react'; -import { IonReactRouter } from '@ionic/react-router'; import { ellipse, square, triangle } from 'ionicons/icons'; import Tab1 from './pages/Tab1'; import Tab2 from './pages/Tab2'; @@ -429,19 +397,10 @@ import Tab3 from './pages/Tab3'; const Tabs: React.FC = () => ( - - - - - - - - - - - - - + } /> + } /> + } /> + } /> @@ -484,22 +443,11 @@ When adding additional routes to tabs you should write them as sibling routes wi ```tsx - - - - - - - - - - - - - - - - + } /> + } /> + } /> + } /> + } /> @@ -570,20 +518,16 @@ For example, the routes for a view with two tabs (sessions and speakers) can be ```tsx - - - + } /> + } /> + } /> ``` -If the navigated URL were "/sessions", it would match the first route and add a URL parameter named "tab" with the value of "sessions" to the resulting `match` object passed into `SessionsPage`. +If the navigated URL were "/sessions", it would match the first route and add a URL parameter named "tab" with the value of "sessions". You can access this parameter using the `useParams` hook. When a user navigates to a session detail page ("/sessions/1" for instance), the second route adds a URL parameter named "tab" with a value of "sessions". When `IonRouterOutlet` sees that both pages are in the same "sessions" tab, it provides an animated page transition to the new view. If a user navigates to a new tab ("speakers" in this case), `IonRouterOutlet` knows not to provide the animation. -### Switches in IonRouterOutlet - -Since `IonRouterOutlet` takes over the job in determining which routes get rendered, using a `Switch` from React Router has no effect when used inside of an `IonRouterOutlet`. Switches still function as expected when used outside an `IonRouterOutlet`. - ## Utilities ### useIonRouter @@ -643,12 +587,4 @@ const MyComponent: React.FC = () => { ## More Information -For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://v5.reactrouter.com/web](https://v5.reactrouter.com/web). - -## From the Community - - - -[Ionic 4 and React: Navigation](https://alligator.io/ionic/ionic-4-react-navigation) - Paul Halliday - - +For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://reactrouter.com](https://reactrouter.com). diff --git a/docs/react/quickstart.md b/docs/react/quickstart.md index 220dc010585..93d7bfdf006 100644 --- a/docs/react/quickstart.md +++ b/docs/react/quickstart.md @@ -78,7 +78,7 @@ Let's walk through these files to understand the app's structure. The root of your app is defined in `App.tsx`: ```tsx title="src/App.tsx" -import { Redirect, Route } from 'react-router-dom'; +import { Route, Navigate } from 'react-router-dom'; import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react'; import { IonReactRouter } from '@ionic/react-router'; import Home from './pages/Home'; @@ -91,12 +91,8 @@ const App: React.FC = () => ( - - - - - - + } /> + } /> @@ -113,12 +109,8 @@ Routes are defined within the `IonRouterOutlet` in `App.tsx`: ```tsx title="src/App.tsx" - - - - - - + } /> + } /> ``` @@ -240,15 +232,9 @@ Then, add its route in `IonRouterOutlet`: ```tsx title="src/App.tsx" - - - - - - - - - + } /> + } /> + } /> ``` @@ -259,7 +245,7 @@ Once that is done, update the button in `Home.tsx`: ``` :::info -Navigating can also be performed programmatically using React Router's `history` prop. See the [React Navigation documentation](/docs/react/navigation.md#navigating-using-history) for more information. +Navigating can also be performed programmatically using the `useIonRouter` hook. See the [React Navigation documentation](/docs/react/navigation.md#useionrouter) for more information. ::: ## Add Icons to the New Page diff --git a/docs/react/your-first-app.md b/docs/react/your-first-app.md index 539c40fff27..7f188396391 100644 --- a/docs/react/your-first-app.md +++ b/docs/react/your-first-app.md @@ -234,7 +234,7 @@ export default Tab2; Next, open `src/App.tsx`. Change the label to "Photos" and the `ellipse` icon to `images` for the middle tab button. ```tsx -import { Redirect, Route } from 'react-router-dom'; +import { Route, Navigate } from 'react-router-dom'; import { IonApp, IonIcon, @@ -259,18 +259,10 @@ const App: React.FC = () => ( - - - - - - - - - - - - + } /> + } /> + } /> + } /> diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index b5599de0664..bd639788e90 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -44,6 +44,76 @@ npm install react@latest react-dom@latest npm install @ionic/react@latest @ionic/react-router@latest ``` +3. Update to React Router v6: + +```shell +npm install react-router@latest react-router-dom@latest +``` + +#### React Router v6 Migration + +Ionic React now requires React Router v6. This is a significant change from React Router v5. Below are the key changes you'll need to make: + +**Route Definition Changes** + +The `component` prop has been replaced with the `element` prop, which accepts JSX: + +```diff +- ++ } /> +``` + +**Redirect Changes** + +The `` component has been replaced with ``: + +```diff +- import { Redirect } from 'react-router-dom'; ++ import { Navigate } from 'react-router-dom'; + +- ++ +``` + +**Nested Route Paths** + +Routes that contain nested routes or child `IonRouterOutlet` components need a `/*` suffix to match sub-paths: + +```diff +- } /> ++ } /> +``` + +**Accessing Route Parameters** + +Route parameters are now accessed via the `useParams` hook instead of props: + +```diff +- import { RouteComponentProps } from 'react-router-dom'; ++ import { useParams } from 'react-router-dom'; + +- const MyComponent: React.FC> = ({ match }) => { +- const id = match.params.id; ++ const MyComponent: React.FC = () => { ++ const { id } = useParams<{ id: string }>(); +``` + +**Programmatic Navigation** + +Use the `useNavigate` hook or `useIonRouter` hook instead of the `history` prop: + +```diff +- const MyComponent: React.FC = ({ history }) => { +- const goToPage = () => history.push('/my-page'); ++ import { useNavigate } from 'react-router-dom'; ++ ++ const MyComponent: React.FC = () => { ++ const navigate = useNavigate(); ++ const goToPage = () => navigate('/my-page'); +``` + +For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/en/main/upgrading/v5). + ### Vue 1. Ionic 9 supports Vue 3.0.6+. Update to the latest version of Vue: From 8fcf1cf6b7ff3570109465539eded833dfc96935 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Thu, 5 Mar 2026 07:19:40 -0800 Subject: [PATCH 02/15] docs(react-router): update navigation guide and expand v5-to-v6 migration guide --- docs/react/navigation.md | 106 +++++++++++++-------------- docs/updating/9-0.md | 150 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 193 insertions(+), 63 deletions(-) diff --git a/docs/react/navigation.md b/docs/react/navigation.md index 36de9eba055..8ed85f13234 100644 --- a/docs/react/navigation.md +++ b/docs/react/navigation.md @@ -30,7 +30,7 @@ const App: React.FC = () => ( - } /> + } /> } /> @@ -38,20 +38,20 @@ const App: React.FC = () => ( ); ``` -Directly after the `Route`, we define our default `Navigate`, which, when a user visits the root URL of the app ("/"), redirects them to the "/dashboard" URL. +Directly after the `Route`, we define our default `Navigate`, which, when a user visits the root URL of the app ("/"), redirects them to the "/dashboard" URL. Note the `/*` suffix on the dashboard route. This allows the nested routes inside `DashboardPage` to match sub-paths like `/dashboard/users/:id`. You can also conditionally redirect based on a condition, like checking if a user is authenticated or not: ```tsx : } /> ``` ## IonReactRouter -The `IonReactRouter` component wraps the traditional [`BrowserRouter`](https://reactrouter.com/en/main/router-components/browser-router) component from React Router, and sets the app up for routing. Therefore, use `IonReactRouter` in place of `BrowserRouter`. You can pass in any props to `IonReactRouter` and they will be passed down to the underlying `BrowserRouter`. +The `IonReactRouter` component wraps the traditional [`BrowserRouter`](https://reactrouter.com/6.28.0/router-components/browser-router) component from React Router, and sets the app up for routing. Therefore, use `IonReactRouter` in place of `BrowserRouter`. You can pass in any props to `IonReactRouter` and they will be passed down to the underlying `BrowserRouter`. ## Nested Routes @@ -64,15 +64,15 @@ const DashboardPage: React.FC = () => { return ( - } /> - } /> + } /> + } /> ); }; ``` -Here, there are a couple more routes defined to point to pages from within the dashboard portion of the app. Note, that we need to define the whole route in the path, and we can't leave off "/dashboard" even though we arrived to this page from that URL. React Router requires full paths, and relative paths are not supported. +Since the parent route already matches `/dashboard/*`, the child routes use **relative paths**. The `index` route matches the parent path (`/dashboard`) and `"users/:id"` resolves to `/dashboard/users/:id`. Absolute paths (e.g., `path="/dashboard/users/:id"`) still work if you prefer explicit full paths. These routes are grouped in an `IonRouterOutlet`, let's discuss that next. @@ -95,11 +95,13 @@ We can define a fallback route by placing a `Route` component with a `path` of ` ```tsx const DashboardPage: React.FC = () => { return ( - - } /> - } /> - } /> - + + + } /> + } /> + } /> + + ); }; ``` @@ -111,11 +113,13 @@ You can alternatively supply a component to render instead of providing a redire ```tsx const DashboardPage: React.FC = () => { return ( - - } /> - } /> - } /> - + + + } /> + } /> + } /> + + ); }; ``` @@ -177,7 +181,7 @@ Other components that have the `routerLink` prop are `IonButton`, `IonCard`, `Io Each of these components also have a `routerDirection` prop to explicitly set the type of page transition to use (`"forward"`, `"back"`, or `"root"`). -Outside of these components that have the `routerLink` prop, you can also use React Router's [`Link`](https://reactrouter.com/en/main/components/link) component to navigate between views: +Outside of these components that have the `routerLink` prop, you can also use React Router's [`Link`](https://reactrouter.com/6.28.0/components/link) component to navigate between views: ```html User 1 @@ -185,7 +189,7 @@ Outside of these components that have the `routerLink` prop, you can also use Re We recommend using one of the above methods whenever possible for routing. The advantage to these approaches is that they both render an anchor (``)tag, which is suitable for overall app accessibility. -For programmatic navigation, use the `useIonRouter` hook (see [Utilities](#useionrouter)) or React Router's [`useNavigate`](https://reactrouter.com/en/main/hooks/use-navigate) hook: +For programmatic navigation, use the `useIonRouter` hook (see [Utilities](#useionrouter)) or React Router's [`useNavigate`](https://reactrouter.com/6.28.0/hooks/use-navigate) hook: ```tsx import { useNavigate } from 'react-router-dom'; @@ -208,7 +212,7 @@ const MyComponent: React.FC = () => { ### Navigating using `navigate` with delta -React Router's `navigate` function can accept a delta number to move forward or backward through the application history. Let's take a look at an example. +React Router's `navigate` function can accept a delta number to move forward or backward through the application history. Say you have the following application history: @@ -216,7 +220,7 @@ Say you have the following application history: If you were to call `navigate(-2)` on `/pageC`, you would be brought back to `/pageA`. If you then called `navigate(2)`, you would be brought to `/pageC`. -Using `navigate()` with delta values in Ionic React is not supported at the moment. Interested in seeing support for this get added to Ionic React? [Let us know on GitHub](https://github.com/ionic-team/ionic-framework/issues/23775)! +Using `navigate()` with delta values is not recommended in Ionic React because it follows the browser's linear history, which does not account for Ionic's non-linear tab and nested outlet navigation stacks. Use the `useIonRouter` hook's [`goBack()`](#useionrouter) method instead, which navigates within the current Ionic navigation stack. ## URL Parameters @@ -243,7 +247,7 @@ const UserDetailPage: React.FC = () => { }; ``` -The [`useParams`](https://reactrouter.com/en/main/hooks/use-params) hook returns an object containing the URL parameters. We obtain the `id` param here and display it on the screen. +The [`useParams`](https://reactrouter.com/6.28.0/hooks/use-params) hook returns an object containing the URL parameters. We obtain the `id` param here and display it on the screen. Note how we use a TypeScript generic to strongly type the params object. This gives us type safety and code completion inside of the component. @@ -297,7 +301,7 @@ From here, we switch to the `Search` tab. Then, we tap the `Originals` tab again Why is this non-linear routing? The previous view we were on was the `Search` view. However, pressing the back button on the `Ted Lasso` view should bring us back to the root `Originals` view. This happens because each tab in a mobile app is treated as its own stack. The [Working with Tabs](#working-with-tabs) sections goes over this in more detail. -If tapping the back button simply called `history.go(-1)` from the `Ted Lasso` view, we would be brought back to the `Search` view which is not correct. +If tapping the back button simply called `navigate(-1)` from the `Ted Lasso` view, we would be brought back to the `Search` view which is not correct. Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `navigate()` with delta values cannot be used in this non-linear environment. This means that `navigate(-1)` or similar delta navigation should not be used when using tabs or nested outlets. @@ -332,7 +336,7 @@ const App: React.FC = () => ( ); ``` -The above routes are considered "shared" because they reuse the `dashboard` piece of the URL. +The above routes are considered "shared" because they reuse the `dashboard` piece of the URL. Since these routes are flat siblings in the same `IonRouterOutlet` (not nested), they don't need a `/*` suffix. ### Nested Routes @@ -350,14 +354,16 @@ const App: React.FC = () => ( ); const DashboardRouterOutlet: React.FC = () => ( - - } /> - } /> - + + + } /> + } /> + + ); ``` -The above routes are nested because they are in the `children` array of the parent route. Notice that the parent route renders the `DashboardRouterOutlet` component and uses a `/*` suffix to match all sub-paths. When you nest routes, you need to render another instance of `IonRouterOutlet`. +The above routes are nested because they are rendered inside the `DashboardRouterOutlet` component, which is a child of the parent route. The parent route uses a `/*` suffix to match all sub-paths, and the nested `IonRouterOutlet` renders the appropriate child route. ### Which one should I choose? @@ -397,10 +403,10 @@ import Tab3 from './pages/Tab3'; const Tabs: React.FC = () => ( - } /> - } /> - } /> - } /> + } /> + } /> + } /> + } /> @@ -422,7 +428,7 @@ const Tabs: React.FC = () => ( export default Tabs; ``` -If you have worked with Ionic Framework before, this should feel familiar. We create an `IonTabs` component and provide an `IonTabBar`. The `IonTabBar` provides `IonTabButton` components, each with a `tab` property that is associated with its corresponding tab in the router config. We also provide an `IonRouterOutlet` to give `IonTabs` an outlet to render the different tab views in. +If you have worked with Ionic Framework before, this should feel familiar. We create an `IonTabs` component and provide an `IonTabBar`. The `IonTabBar` provides `IonTabButton` components, each with a `tab` property that is associated with its corresponding tab in the router config. We also provide an `IonRouterOutlet` to give `IonTabs` an outlet to render the different tab views in. Note how the `Route` paths are relative (e.g., `"tab1"` instead of `"/tabs/tab1"`) since the parent route already matches `/tabs/*`. :::tip `IonTabs` renders an `IonPage` for you, so you do not need to add `IonPage` manually here. @@ -438,16 +444,16 @@ Since Ionic is focused on helping developers build mobile apps, the tabs in Ioni ### Child Routes within Tabs -When adding additional routes to tabs you should write them as sibling routes with the parent tab as the path prefix. The example below defines the `/tabs/tab1/view` route as a sibling of the `/tabs/tab1` route. Since this new route has the `tab1` prefix, it will be rendered inside of the `Tabs` component, and Tab 1 will still be selected in the `IonTabBar`. +When adding additional routes to tabs you should write them as sibling routes with the parent tab as the path prefix. The example below defines the `tab1/view` route as a sibling of the `tab1` route. Since this new route has the `tab1` prefix, it will be rendered inside of the `Tabs` component, and Tab 1 will still be selected in the `IonTabBar`. ```tsx - } /> - } /> - } /> - } /> - } /> + } /> + } /> + } /> + } /> + } /> @@ -510,29 +516,25 @@ If you would prefer to get hands on with the concepts and code described above, ### IonRouterOutlet in a Tabs View -When working in a tabs view, Ionic React needs a way to determine what views belong to which tabs. We accomplish this by taking advantage of the fact that the paths provided to a `Route` are regular expressions. - -While the syntax looks a bit strange, it is reasonably straightforward once you understand it. +When working in a tabs view, Ionic React needs a way to determine what views belong to which tabs. It does this by matching the path prefix of each route. For example, the routes for a view with two tabs (sessions and speakers) can be set up as such: ```tsx - } /> - } /> - } /> + } /> + } /> + } /> ``` -If the navigated URL were "/sessions", it would match the first route and add a URL parameter named "tab" with the value of "sessions". You can access this parameter using the `useParams` hook. - -When a user navigates to a session detail page ("/sessions/1" for instance), the second route adds a URL parameter named "tab" with a value of "sessions". When `IonRouterOutlet` sees that both pages are in the same "sessions" tab, it provides an animated page transition to the new view. If a user navigates to a new tab ("speakers" in this case), `IonRouterOutlet` knows not to provide the animation. +When a user navigates to a session detail page ("/sessions/1" for instance), `IonRouterOutlet` sees that both the list and detail pages share the same "sessions" path prefix and provides an animated page transition to the new view. If a user navigates to a different tab ("speakers" in this case), `IonRouterOutlet` knows not to provide the animation. ## Utilities ### useIonRouter -The `useIonRouter` hook can be used for more direct control over routing in Ionic React. It allows you to pass additional metadata to Ionic, such as a custom animation, before calling React Router. +The `useIonRouter` hook gives you more control over routing in Ionic React, including custom page transition animations and Ionic-aware back navigation via `goBack()`. The `useIonRouter` hook returns a `UseIonRouterResult` which has several convenience methods for routing: @@ -559,7 +561,7 @@ type UseIonRouterResult = { */ goBack(animationBuilder?: AnimationBuilder): void; /** - * Determines if there are any additional routes in the the Router's history. However, routing is not prevented if the browser's history has more entries. Returns true if more entries exist, false if not. + * Determines if there are any additional routes in the Router's history. However, routing is not prevented if the browser's history has more entries. Returns true if more entries exist, false if not. */ canGoBack(): boolean; /** @@ -587,4 +589,4 @@ const MyComponent: React.FC = () => { ## More Information -For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://reactrouter.com](https://reactrouter.com). +For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://reactrouter.com/6.28.0](https://reactrouter.com/6.28.0). diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index bd639788e90..60fac6a8861 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -47,22 +47,37 @@ npm install @ionic/react@latest @ionic/react-router@latest 3. Update to React Router v6: ```shell -npm install react-router@latest react-router-dom@latest +npm install react-router@6 react-router-dom@6 +``` + +If you have `@types/react-router` or `@types/react-router-dom` installed, remove them. React Router v6 includes its own TypeScript definitions: + +```shell +npm uninstall @types/react-router @types/react-router-dom ``` #### React Router v6 Migration -Ionic React now requires React Router v6. This is a significant change from React Router v5. Below are the key changes you'll need to make: +Ionic React now requires React Router v6, which has a different API from v5. Below are the key changes you'll need to make: **Route Definition Changes** -The `component` prop has been replaced with the `element` prop, which accepts JSX: +The `component` and `render` props have been replaced with the `element` prop, which accepts JSX: ```diff - + } /> ``` +Routes can no longer render content via nested children. All route content must be passed through the `element` prop: + +```diff +- +- +- ++ } /> +``` + **Redirect Changes** The `` component has been replaced with ``: @@ -98,21 +113,128 @@ Route parameters are now accessed via the `useParams` hook instead of props: + const { id } = useParams<{ id: string }>(); ``` -**Programmatic Navigation** +**RouteComponentProps Removed** + +The `RouteComponentProps` type and its `history`, `location`, and `match` props are no longer available in React Router v6. Use the equivalent hooks instead: -Use the `useNavigate` hook or `useIonRouter` hook instead of the `history` prop: +- `history` -> `useNavigate` (see below) or `useIonRouter` +- `match.params` -> `useParams` (covered above) +- `location` -> `useLocation` ```diff -- const MyComponent: React.FC = ({ history }) => { -- const goToPage = () => history.push('/my-page'); -+ import { useNavigate } from 'react-router-dom'; -+ +- import { RouteComponentProps } from 'react-router-dom'; ++ import { useNavigate, useLocation } from 'react-router-dom'; ++ import { useIonRouter } from '@ionic/react'; + +- const MyComponent: React.FC = ({ history, location }) => { +- history.push('/path'); +- history.replace('/path'); +- history.goBack(); +- console.log(location.pathname); + const MyComponent: React.FC = () => { + const navigate = useNavigate(); -+ const goToPage = () => navigate('/my-page'); ++ const router = useIonRouter(); ++ const location = useLocation(); ++ // In an event handler or useEffect: ++ navigate('/path'); ++ navigate('/path', { replace: true }); ++ router.goBack(); ++ console.log(location.pathname); ``` -For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/en/main/upgrading/v5). +**Exact Prop Removed** + +The `exact` prop is no longer needed. React Router v6 routes match exactly by default. To match sub-paths, use a `/*` suffix on the path: + +```diff +- ++ +``` + +**Render Prop Removed** + +The `render` prop has been replaced with the `element` prop: + +```diff +- } /> ++ } /> +``` + +**Programmatic Navigation** + +The `useHistory` hook has been replaced with `useNavigate`: + +```diff +- import { useHistory } from 'react-router-dom'; ++ import { useNavigate } from 'react-router-dom'; ++ import { useIonRouter } from '@ionic/react'; + +- const history = useHistory(); ++ const navigate = useNavigate(); ++ const router = useIonRouter(); + +- history.push('/path'); ++ navigate('/path'); + +- history.replace('/path'); ++ navigate('/path', { replace: true }); + +- history.goBack(); ++ router.goBack(); +``` + +**Custom History Prop Removed** + +The `history` prop has been removed from `IonReactRouter`, `IonReactHashRouter`, and `IonReactMemoryRouter`. React Router v6 routers no longer accept custom `history` objects. + +```diff +- import { createBrowserHistory } from 'history'; +- const history = createBrowserHistory(); +- ++ +``` + +For `IonReactMemoryRouter` (commonly used in tests), use `initialEntries` instead: + +```diff +- import { createMemoryHistory } from 'history'; +- const history = createMemoryHistory({ initialEntries: ['/start'] }); +- ++ +``` + +**IonRedirect Removed** + +The `IonRedirect` component has been removed. Use React Router's `` component instead: + +```diff +- import { IonRedirect } from '@ionic/react'; +- ++ import { Navigate } from 'react-router-dom'; ++ } /> +``` + +**Path Regex Constraints Removed** + +React Router v6 no longer supports regex constraints in path parameters (e.g., `/:tab(sessions)`). Use literal paths instead: + +```diff +- +- ++ } /> ++ } /> +``` + +**IonRoute API Changes** + +The `IonRoute` component follows the same API changes as React Router's ``. The `render` prop has been replaced with `element`, and the `exact` prop has been removed: + +```diff +- } /> ++ } /> +``` + +For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/6.28.0/upgrading/v5). ### Vue @@ -135,3 +257,9 @@ npm install @ionic/vue@latest @ionic/vue-router@latest ```shell npm install @ionic/core@latest ``` + +## Need Help Upgrading? + +Be sure to look at the [Ionic 9 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) for the complete list of breaking changes. This upgrade guide only covers changes that require action from developers. + +If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/). From bcf73fe0589bd8076387ea0380d565ca94cf2513 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Thu, 5 Mar 2026 07:44:25 -0800 Subject: [PATCH 03/15] chore(lint): running lint --- docs/react/navigation.md | 5 +- .../version-v8/api/accordion-group.md | 12 +- versioned_docs/version-v8/api/accordion.md | 49 ++-- versioned_docs/version-v8/api/action-sheet.md | 15 +- versioned_docs/version-v8/api/alert.md | 20 +- versioned_docs/version-v8/api/app.md | 26 +- versioned_docs/version-v8/api/avatar.md | 13 +- versioned_docs/version-v8/api/back-button.md | 15 +- versioned_docs/version-v8/api/backdrop.md | 13 +- versioned_docs/version-v8/api/badge.md | 14 +- versioned_docs/version-v8/api/breadcrumb.md | 13 +- versioned_docs/version-v8/api/breadcrumbs.md | 12 +- versioned_docs/version-v8/api/button.md | 15 +- versioned_docs/version-v8/api/buttons.md | 32 ++- versioned_docs/version-v8/api/card-content.md | 11 +- versioned_docs/version-v8/api/card-header.md | 11 +- .../version-v8/api/card-subtitle.md | 11 +- versioned_docs/version-v8/api/card-title.md | 16 +- versioned_docs/version-v8/api/card.md | 21 +- versioned_docs/version-v8/api/checkbox.md | 15 +- versioned_docs/version-v8/api/chip.md | 14 +- versioned_docs/version-v8/api/col.md | 19 +- versioned_docs/version-v8/api/content.md | 21 +- .../version-v8/api/datetime-button.md | 14 +- versioned_docs/version-v8/api/datetime.md | 50 ++-- versioned_docs/version-v8/api/fab-button.md | 17 +- versioned_docs/version-v8/api/fab-list.md | 11 +- versioned_docs/version-v8/api/fab.md | 14 +- versioned_docs/version-v8/api/footer.md | 19 +- versioned_docs/version-v8/api/grid.md | 22 +- versioned_docs/version-v8/api/header.md | 22 +- versioned_docs/version-v8/api/icon.md | 2 - versioned_docs/version-v8/api/img.md | 16 +- .../version-v8/api/infinite-scroll-content.md | 10 +- .../version-v8/api/infinite-scroll.md | 22 +- versioned_docs/version-v8/api/input-otp.md | 39 ++- .../version-v8/api/input-password-toggle.md | 16 +- versioned_docs/version-v8/api/input.md | 22 +- versioned_docs/version-v8/api/item-divider.md | 19 +- versioned_docs/version-v8/api/item-group.md | 16 +- versioned_docs/version-v8/api/item-option.md | 16 +- versioned_docs/version-v8/api/item-options.md | 21 +- versioned_docs/version-v8/api/item-sliding.md | 19 +- versioned_docs/version-v8/api/item.md | 183 ++++++++++--- versioned_docs/version-v8/api/label.md | 15 +- versioned_docs/version-v8/api/list-header.md | 14 +- versioned_docs/version-v8/api/list.md | 19 +- versioned_docs/version-v8/api/loading.md | 22 +- versioned_docs/version-v8/api/menu-button.md | 16 +- versioned_docs/version-v8/api/menu-toggle.md | 16 +- versioned_docs/version-v8/api/menu.md | 23 +- versioned_docs/version-v8/api/modal.md | 35 ++- versioned_docs/version-v8/api/nav-link.md | 16 +- versioned_docs/version-v8/api/nav.md | 22 +- versioned_docs/version-v8/api/note.md | 15 +- .../version-v8/api/picker-column-option.md | 9 +- .../version-v8/api/picker-column.md | 9 +- .../version-v8/api/picker-legacy.md | 14 +- versioned_docs/version-v8/api/picker.md | 21 +- versioned_docs/version-v8/api/popover.md | 28 +- versioned_docs/version-v8/api/progress-bar.md | 22 +- versioned_docs/version-v8/api/radio-group.md | 17 +- versioned_docs/version-v8/api/radio.md | 18 +- versioned_docs/version-v8/api/range.md | 18 +- .../version-v8/api/refresher-content.md | 11 +- versioned_docs/version-v8/api/refresher.md | 28 +- .../version-v8/api/reorder-group.md | 18 +- versioned_docs/version-v8/api/reorder.md | 21 +- .../version-v8/api/ripple-effect.md | 19 +- .../version-v8/api/route-redirect.md | 28 +- versioned_docs/version-v8/api/route.md | 101 ++++---- versioned_docs/version-v8/api/router-link.md | 17 +- .../version-v8/api/router-outlet.md | 20 +- versioned_docs/version-v8/api/router.md | 24 +- versioned_docs/version-v8/api/row.md | 18 +- versioned_docs/version-v8/api/searchbar.md | 24 +- .../version-v8/api/segment-button.md | 21 +- .../version-v8/api/segment-content.md | 15 +- versioned_docs/version-v8/api/segment-view.md | 15 +- versioned_docs/version-v8/api/segment.md | 22 +- .../version-v8/api/select-option.md | 18 +- versioned_docs/version-v8/api/select.md | 55 ++-- .../version-v8/api/skeleton-text.md | 16 +- versioned_docs/version-v8/api/spinner.md | 17 +- versioned_docs/version-v8/api/split-pane.md | 32 ++- versioned_docs/version-v8/api/tab-bar.md | 26 +- versioned_docs/version-v8/api/tab-button.md | 32 +-- versioned_docs/version-v8/api/tab.md | 19 +- versioned_docs/version-v8/api/tabs.md | 14 +- versioned_docs/version-v8/api/text.md | 15 +- versioned_docs/version-v8/api/textarea.md | 14 +- versioned_docs/version-v8/api/thumbnail.md | 13 +- versioned_docs/version-v8/api/title.md | 16 +- versioned_docs/version-v8/api/toast.md | 22 +- versioned_docs/version-v8/api/toggle.md | 19 +- versioned_docs/version-v8/api/toolbar.md | 25 +- .../version-v8/reference/glossary.md | 245 ++++++++++++------ 97 files changed, 1557 insertions(+), 775 deletions(-) diff --git a/docs/react/navigation.md b/docs/react/navigation.md index 8ed85f13234..1821d0d2977 100644 --- a/docs/react/navigation.md +++ b/docs/react/navigation.md @@ -43,10 +43,7 @@ Directly after the `Route`, we define our default `Navigate`, which, when a user You can also conditionally redirect based on a condition, like checking if a user is authenticated or not: ```tsx - : } -/> + : } /> ``` ## IonReactRouter diff --git a/versioned_docs/version-v8/api/accordion-group.md b/versioned_docs/version-v8/api/accordion-group.md index 6fbaffbbefd..c273b293d1c 100644 --- a/versioned_docs/version-v8/api/accordion-group.md +++ b/versioned_docs/version-v8/api/accordion-group.md @@ -1,6 +1,7 @@ --- -title: "ion-accordion-group" +title: 'ion-accordion-group' --- + import Props from '@ionic-internal/component-api/v8/accordion-group/props.md'; import Events from '@ionic-internal/component-api/v8/accordion-group/events.md'; import Methods from '@ionic-internal/component-api/v8/accordion-group/methods.md'; @@ -16,7 +17,6 @@ Accordion group is a container for accordion instances. It manages the state of See the [Accordion](./accordion) documentation for more information. - ## Interfaces ### AccordionGroupChangeEventDetail @@ -38,22 +38,26 @@ interface AccordionGroupCustomEvent extends CustomEvent { } ``` - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/accordion.md b/versioned_docs/version-v8/api/accordion.md index 7e4d33f324d..2f9c187b9c9 100644 --- a/versioned_docs/version-v8/api/accordion.md +++ b/versioned_docs/version-v8/api/accordion.md @@ -1,6 +1,7 @@ --- -title: "ion-accordion" +title: 'ion-accordion' --- + import Props from '@ionic-internal/component-api/v8/accordion/props.md'; import Events from '@ionic-internal/component-api/v8/accordion/events.md'; import Methods from '@ionic-internal/component-api/v8/accordion/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/accordion/slots.md'; ion-accordion: Accordion Components: How to Build & Examples - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information. All `ion-accordion` components should be grouped inside `ion-accordion-group` components. ## Basic Usage @@ -120,18 +123,18 @@ import ExpansionStyles from '@site/static/usage/v8/accordion/customization/expan You can customize the expansion behavior by styling based on the accordion's state. There are four state classes applied to `ion-accordion`. Styling using these classes can allow you to create advanced state transitions: -| Class Name | Description | -| ---------- | ----------- | -| `.accordion-expanding` | Applied when the accordion is actively expanding | -| `.accordion-expanded` | Applied when the accordion is fully expanded | +| Class Name | Description | +| ----------------------- | ------------------------------------------------- | +| `.accordion-expanding` | Applied when the accordion is actively expanding | +| `.accordion-expanded` | Applied when the accordion is fully expanded | | `.accordion-collapsing` | Applied when the accordion is actively collapsing | -| `.accordion-collapsed` | Applied when the accordion is fully collapsed | +| `.accordion-collapsed` | Applied when the accordion is fully collapsed | If you need to target specific pieces of the accordion, we recommend targeting the element directly. For example, if you want to customize the ion-item in your header slot when the accordion is expanded, you can use the following selector: ```css -ion-accordion.accordion-expanding ion-item[slot="header"], -ion-accordion.accordion-expanded ion-item[slot="header"] { +ion-accordion.accordion-expanding ion-item[slot='header'], +ion-accordion.accordion-expanded ion-item[slot='header'] { --color: red; } ``` @@ -174,15 +177,15 @@ import AccessibilityAnimations from '@site/static/usage/v8/accordion/accessibili When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard support for interacting with the component. The following table details what each key does: -| Key | Description | -| ------------------------------------ | ------------------------------------------------------------ | -| Space or Enter | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. | -| Tab | Moves focus to the next focusable element. | -| Shift + Tab | Moves focus to the previous focusable element. | -| Down Arrow | - When focus is on an accordion header, moves focus to the next accordion header.
- When focus is on the last accordion header, moves focus to the first accordion header. | -| Up Arrow | - When focus is on an accordion header, moves focus to the previous accordion header.
- When focus is on the first accordion header, moves focus to the last accordion header. | -| Home | When focus is on an accordion header, moves focus to the first accordion header. | -| End | When focus is on an accordion header, moves focus to the last accordion header. | +| Key | Description | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Space or Enter | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. | +| Tab | Moves focus to the next focusable element. | +| Shift + Tab | Moves focus to the previous focusable element. | +| Down Arrow | - When focus is on an accordion header, moves focus to the next accordion header.
- When focus is on the last accordion header, moves focus to the first accordion header. | +| Up Arrow | - When focus is on an accordion header, moves focus to the previous accordion header.
- When focus is on the first accordion header, moves focus to the last accordion header. | +| Home | When focus is on an accordion header, moves focus to the first accordion header. | +| End | When focus is on an accordion header, moves focus to the last accordion header. | ## Performance @@ -190,7 +193,7 @@ When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard sup The accordion animation works by knowing the height of the `content` slot when the animation starts. The accordion expects that this height will remain consistent throughout the animation. As a result, developers should avoid performing any operation that may change the height of the content during the animation. -For example, using [ion-img](./img) may cause layout shifts as it lazily loads images. This means that as the animation plays, `ion-img` will load the image data, and the dimensions of `ion-img` will change to account for the loaded image data. This can result in the height of the `content` slot changing. Developers have a few options for avoiding this: +For example, using [ion-img](./img) may cause layout shifts as it lazily loads images. This means that as the animation plays, `ion-img` will load the image data, and the dimensions of `ion-img` will change to account for the loaded image data. This can result in the height of the `content` slot changing. Developers have a few options for avoiding this: 1. Use an `img` element without any lazy loading. `ion-img` always uses lazy loading, but `img` does not use lazy loading by default. This is the simplest option and works well if you have small images that do not significantly benefit from lazy loading. @@ -199,19 +202,25 @@ For example, using [ion-img](./img) may cause layout shifts as it lazily loads i 3. If neither of these options are applicable, developers may want to consider disabling animations altogether by using the `animated` property on [ion-accordion-group](./accordion-group). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/action-sheet.md b/versioned_docs/version-v8/api/action-sheet.md index 1ff6ff2a26f..e1a0fac49a1 100644 --- a/versioned_docs/version-v8/api/action-sheet.md +++ b/versioned_docs/version-v8/api/action-sheet.md @@ -1,6 +1,7 @@ --- -title: "ion-action-sheet" +title: 'ion-action-sheet' --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -13,14 +14,16 @@ import Slots from '@ionic-internal/component-api/v8/action-sheet/slots.md'; ion-action-sheet: Action Sheet Dialog for iOS and Android - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. ## Inline Action Sheets (Recommended) @@ -280,19 +283,25 @@ interface ActionSheetOptions { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/alert.md b/versioned_docs/version-v8/api/alert.md index 2a2310fb3c2..40b277674e8 100644 --- a/versioned_docs/version-v8/api/alert.md +++ b/versioned_docs/version-v8/api/alert.md @@ -1,6 +1,7 @@ --- -title: "ion-alert" +title: 'ion-alert' --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -13,7 +14,10 @@ import Slots from '@ionic-internal/component-api/v8/alert/slots.md'; ion-alert: Ionic Alert Buttons with Custom Message Prompts - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -58,7 +62,6 @@ import Buttons from '@site/static/usage/v8/alert/buttons/index.md'; - ## Inputs Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as `url`, `email`, `text`, `textarea` etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead. @@ -106,7 +109,7 @@ import Customization from '@site/static/usage/v8/alert/customization/index.md'; :::note - If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. +If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. ::: ## Accessibility @@ -181,7 +184,6 @@ const alert = await alertController.create({ - All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert. #### Alert Buttons Description @@ -281,7 +283,6 @@ interface AlertButton { } ``` - ### AlertInput ```typescript @@ -306,7 +307,6 @@ interface AlertInput { } ``` - ### AlertOptions ```typescript @@ -332,19 +332,25 @@ interface AlertOptions { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/app.md b/versioned_docs/version-v8/api/app.md index 5e20f74cd20..773abf04b4e 100644 --- a/versioned_docs/version-v8/api/app.md +++ b/versioned_docs/version-v8/api/app.md @@ -1,6 +1,7 @@ --- -title: "ion-app" +title: 'ion-app' --- + import Props from '@ionic-internal/component-api/v8/app/props.md'; import Events from '@ionic-internal/component-api/v8/app/events.md'; import Methods from '@ionic-internal/component-api/v8/app/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/app/slots.md'; ion-app: Container Element for an Ionic Application - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -19,12 +23,12 @@ App is a container element for an Ionic application. There should only be one `< Using `ion-app` enables the following behaviors: -* [Keyboard Lifecycle Events](../developing/keyboard#keyboard-lifecycle-events) without the need for any native plugins -* [Hardware Back Button Listeners](../developing/hardware-back-button) for customizing the hardware back button behavior on Android devices -* Status bar support in Capacitor or Cordova which allows users to scroll to the top of the view by tapping the status bar -* Scroll assist utilities which scroll the content so focused text inputs are not covered by the on-screen keyboard -* [Ripple effect](./ripple-effect) when activating buttons on Material Design mode -* Other tap and focus utilities which make the experience of using an Ionic app feel more native +- [Keyboard Lifecycle Events](../developing/keyboard#keyboard-lifecycle-events) without the need for any native plugins +- [Hardware Back Button Listeners](../developing/hardware-back-button) for customizing the hardware back button behavior on Android devices +- Status bar support in Capacitor or Cordova which allows users to scroll to the top of the view by tapping the status bar +- Scroll assist utilities which scroll the content so focused text inputs are not covered by the on-screen keyboard +- [Ripple effect](./ripple-effect) when activating buttons on Material Design mode +- Other tap and focus utilities which make the experience of using an Ionic app feel more native ## Programmatic Focus @@ -35,19 +39,25 @@ import SetFocus from '@site/static/usage/v8/app/set-focus/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/avatar.md b/versioned_docs/version-v8/api/avatar.md index ab9f52f3d93..35c09f9603b 100644 --- a/versioned_docs/version-v8/api/avatar.md +++ b/versioned_docs/version-v8/api/avatar.md @@ -1,5 +1,5 @@ --- -title: "ion-avatar" +title: 'ion-avatar' --- import Props from '@ionic-internal/component-api/v8/avatar/props.md'; @@ -11,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/avatar/slots.md'; ion-avatar: Circular Application Avatar Icon Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -49,19 +52,25 @@ import CSSProps from '@site/static/usage/v8/avatar/theming/css-properties/index. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/back-button.md b/versioned_docs/version-v8/api/back-button.md index 3491e7cc65e..c59a012d8f2 100644 --- a/versioned_docs/version-v8/api/back-button.md +++ b/versioned_docs/version-v8/api/back-button.md @@ -1,6 +1,7 @@ --- -title: "ion-back-button" +title: 'ion-back-button' --- + import Props from '@ionic-internal/component-api/v8/back-button/props.md'; import Events from '@ionic-internal/component-api/v8/back-button/events.md'; import Methods from '@ionic-internal/component-api/v8/back-button/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/back-button/slots.md'; ion-back-button: Custom Menu Back Button for Applications - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The back button navigates back in the app's history when clicked. It is only displayed when there is history in the navigation stack, unless [`defaultHref`](#default-back-history) is set. The back button displays different text and icon based on the mode, but this can be customized. ## Basic Usage @@ -39,19 +42,25 @@ import Custom from '@site/static/usage/v8/back-button/custom/index.md'; Occasionally an app may need to show the back button and navigate back when there is no history. This can be done by setting the `defaultHref` on the back button to a path. In order to use `defaultHref`, the app must contain a router with paths set. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/backdrop.md b/versioned_docs/version-v8/api/backdrop.md index 5d9ce676078..462da52a180 100644 --- a/versioned_docs/version-v8/api/backdrop.md +++ b/versioned_docs/version-v8/api/backdrop.md @@ -1,6 +1,7 @@ --- -title: "ion-backdrop" +title: 'ion-backdrop' --- + import Props from '@ionic-internal/component-api/v8/backdrop/props.md'; import Events from '@ionic-internal/component-api/v8/backdrop/events.md'; import Methods from '@ionic-internal/component-api/v8/backdrop/methods.md'; @@ -24,7 +25,7 @@ import Basic from '@site/static/usage/v8/backdrop/basic/index.md'; ## Styling -The backdrop can be customized by assigning CSS properties directly to the backdrop element. Common properties include `background-color`, `background` and `opacity`. +The backdrop can be customized by assigning CSS properties directly to the backdrop element. Common properties include `background-color`, `background` and `opacity`. Content can be displayed above the backdrop by setting a `z-index` on the content, higher than the backdrop (defaults to `2`). @@ -33,19 +34,25 @@ import Styling from '@site/static/usage/v8/backdrop/styling/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/versioned_docs/version-v8/api/badge.md b/versioned_docs/version-v8/api/badge.md index 6a4e6671919..7904dc127e7 100644 --- a/versioned_docs/version-v8/api/badge.md +++ b/versioned_docs/version-v8/api/badge.md @@ -1,6 +1,7 @@ --- -title: "ion-badge" +title: 'ion-badge' --- + import Props from '@ionic-internal/component-api/v8/badge/props.md'; import Events from '@ionic-internal/component-api/v8/badge/events.md'; import Methods from '@ionic-internal/component-api/v8/badge/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/badge/slots.md'; ion-badge: iOS & Android App Notification Badge Icons - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -52,19 +56,25 @@ import CSSProps from '@site/static/usage/v8/badge/theming/css-properties/index.m ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/breadcrumb.md b/versioned_docs/version-v8/api/breadcrumb.md index 0866779da61..f068ca3a8df 100644 --- a/versioned_docs/version-v8/api/breadcrumb.md +++ b/versioned_docs/version-v8/api/breadcrumb.md @@ -1,6 +1,7 @@ --- -title: "ion-breadcrumb" +title: 'ion-breadcrumb' --- + import Props from '@ionic-internal/component-api/v8/breadcrumb/props.md'; import Events from '@ionic-internal/component-api/v8/breadcrumb/events.md'; import Methods from '@ionic-internal/component-api/v8/breadcrumb/methods.md'; @@ -12,7 +13,6 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - A Breadcrumb is a single navigation item that is a child of the Breadcrumbs component. A breadcrumb can link elsewhere in an app or it can be plain text. Each breadcrumb has a separator between it and the next breadcrumb and can optionally contain an icon. See the [Breadcrumbs](./breadcrumbs) documentation for more information. @@ -38,23 +38,26 @@ interface BreadcrumbCustomEvent extends CustomEvent { } ``` - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/breadcrumbs.md b/versioned_docs/version-v8/api/breadcrumbs.md index da1c92e04fe..f3396c2770b 100644 --- a/versioned_docs/version-v8/api/breadcrumbs.md +++ b/versioned_docs/version-v8/api/breadcrumbs.md @@ -1,6 +1,7 @@ --- -title: "ion-breadcrumbs" +title: 'ion-breadcrumbs' --- + import Props from '@ionic-internal/component-api/v8/breadcrumbs/props.md'; import Events from '@ionic-internal/component-api/v8/breadcrumbs/events.md'; import Methods from '@ionic-internal/component-api/v8/breadcrumbs/methods.md'; @@ -8,8 +9,6 @@ import Parts from '@ionic-internal/component-api/v8/breadcrumbs/parts.md'; import CustomProps from '@ionic-internal/component-api/v8/breadcrumbs/custom-props.mdx'; import Slots from '@ionic-internal/component-api/v8/breadcrumbs/slots.md'; - - import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -84,21 +83,26 @@ import CSSProps from '@site/static/usage/v8/breadcrumbs/theming/css-properties/i - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/button.md b/versioned_docs/version-v8/api/button.md index bd0e00afb37..2c69abac06f 100644 --- a/versioned_docs/version-v8/api/button.md +++ b/versioned_docs/version-v8/api/button.md @@ -1,6 +1,7 @@ --- -title: "ion-button" +title: 'ion-button' --- + import Props from '@ionic-internal/component-api/v8/button/props.md'; import Events from '@ionic-internal/component-api/v8/button/events.md'; import Methods from '@ionic-internal/component-api/v8/button/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/button/slots.md'; ion-button: Style Buttons with Custom CSS Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -41,7 +45,6 @@ import Shape from '@site/static/usage/v8/button/shape/index.md'; - ## Fill This property determines the background and border color of the button. By default, buttons have a solid background unless the button is inside of a toolbar, in which case it has a transparent background. @@ -97,19 +100,25 @@ import TextWrapping from '@site/static/usage/v8/button/text-wrapping/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/buttons.md b/versioned_docs/version-v8/api/buttons.md index eaade91073c..10e90159090 100644 --- a/versioned_docs/version-v8/api/buttons.md +++ b/versioned_docs/version-v8/api/buttons.md @@ -1,6 +1,7 @@ --- -title: "ion-buttons" +title: 'ion-buttons' --- + import Props from '@ionic-internal/component-api/v8/buttons/props.md'; import Events from '@ionic-internal/component-api/v8/buttons/events.md'; import Methods from '@ionic-internal/component-api/v8/buttons/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/buttons/slots.md'; ion-buttons: Toolbar Element with Named Slots for Buttons - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The Buttons component is a container element. It should be used inside of a [toolbar](./toolbar) and can contain several types of buttons, including standard [buttons](./button), [menu buttons](./menu-button), and [back buttons](./back-button). ## Basic Usage @@ -26,23 +29,21 @@ import Basic from '@site/static/usage/v8/buttons/basic/index.md'; - ## Buttons Placement Buttons can be positioned inside of the toolbar using a named slot. The below chart has a description of each slot. -| Slot | Description | -|--------------|----------------------------------------------------------------------------------------------------------| -| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | -| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | -| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | -| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | +| Slot | Description | +| ----------- | ------------------------------------------------------------------------------------------------------- | +| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | +| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | +| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | +| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | import Placement from '@site/static/usage/v8/buttons/placement/index.md'; - ## Types of Buttons A button in a toolbar is styled to be clear by default, but this can be changed using the [`fill`](./button#fill) property on the button. The properties included on [back button](./back-button) and [menu button](./menu-button) in this example are for display purposes; see their respective documentation for proper usage. @@ -51,7 +52,6 @@ import Types from '@site/static/usage/v8/buttons/types/index.md'; - ## Collapsible Buttons The `collapse` property can be set on the buttons to collapse them when the header collapses. This is typically used with [collapsible large titles](./title#collapsible-large-titles). @@ -63,25 +63,31 @@ This feature is only available for iOS. ::: + import CollapsibleLargeTitleButtons from '@site/static/usage/v8/title/collapsible-large-title/buttons/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/card-content.md b/versioned_docs/version-v8/api/card-content.md index 1e5edada47b..b810f88012c 100644 --- a/versioned_docs/version-v8/api/card-content.md +++ b/versioned_docs/version-v8/api/card-content.md @@ -1,6 +1,7 @@ --- -title: "ion-card-content" +title: 'ion-card-content' --- + import Props from '@ionic-internal/component-api/v8/card-content/props.md'; import Events from '@ionic-internal/component-api/v8/card-content/events.md'; import Methods from '@ionic-internal/component-api/v8/card-content/methods.md'; @@ -10,26 +11,30 @@ import Slots from '@ionic-internal/component-api/v8/card-content/slots.md'; import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card content is a child component of card that adds padding around its contents. It is recommended that any text content for a card should be placed inside of card content. See the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/card-header.md b/versioned_docs/version-v8/api/card-header.md index 3e00688e07b..77039618c6a 100644 --- a/versioned_docs/version-v8/api/card-header.md +++ b/versioned_docs/version-v8/api/card-header.md @@ -1,6 +1,7 @@ --- -title: "ion-card-header" +title: 'ion-card-header' --- + import Props from '@ionic-internal/component-api/v8/card-header/props.md'; import Events from '@ionic-internal/component-api/v8/card-header/events.md'; import Methods from '@ionic-internal/component-api/v8/card-header/methods.md'; @@ -12,26 +13,30 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card header is a child component of card that should be placed before the card content. It can contain a [card title](./card-title) and a [card subtitle](./card-subtitle). See the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/card-subtitle.md b/versioned_docs/version-v8/api/card-subtitle.md index 1fece927bfe..a1871a8af7a 100644 --- a/versioned_docs/version-v8/api/card-subtitle.md +++ b/versioned_docs/version-v8/api/card-subtitle.md @@ -1,6 +1,7 @@ --- -title: "ion-card-subtitle" +title: 'ion-card-subtitle' --- + import Props from '@ionic-internal/component-api/v8/card-subtitle/props.md'; import Events from '@ionic-internal/component-api/v8/card-subtitle/events.md'; import Methods from '@ionic-internal/component-api/v8/card-subtitle/methods.md'; @@ -12,26 +13,30 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card subtitle is a child component of card that should be placed inside of a [card header](./card-header). See the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/card-title.md b/versioned_docs/version-v8/api/card-title.md index 956a2490007..e37f343c322 100644 --- a/versioned_docs/version-v8/api/card-title.md +++ b/versioned_docs/version-v8/api/card-title.md @@ -1,6 +1,7 @@ --- -title: "ion-card-title" +title: 'ion-card-title' --- + import Props from '@ionic-internal/component-api/v8/card-title/props.md'; import Events from '@ionic-internal/component-api/v8/card-title/events.md'; import Methods from '@ionic-internal/component-api/v8/card-title/methods.md'; @@ -12,31 +13,38 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; ion-card-title: Ionic App Card Title Component - + - Card title is a child component of card that should be placed inside of a [card header](./card-header). See the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/card.md b/versioned_docs/version-v8/api/card.md index ab8189925c8..04f95e08906 100644 --- a/versioned_docs/version-v8/api/card.md +++ b/versioned_docs/version-v8/api/card.md @@ -1,6 +1,7 @@ --- -title: "ion-card" +title: 'ion-card' --- + import Props from '@ionic-internal/component-api/v8/card/props.md'; import Events from '@ionic-internal/component-api/v8/card/events.md'; import Methods from '@ionic-internal/component-api/v8/card/methods.md'; @@ -12,47 +13,44 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; ion-card: Card UI Components for Ionic Framework API - + - Cards are containers that display content such as text, images, buttons, and lists. A card can be a single component, but is often made up of a header, title, subtitle, and content. Cards are broken up into several components to accommodate this structure: [card header](./card-header), [card title](./card-title), [card subtitle](./card-subtitle), and [card content](./card-content). - ## Basic Usage import Basic from '@site/static/usage/v8/card/basic/index.md'; - ## Media Cards import Media from '@site/static/usage/v8/card/media/index.md'; - ## Card Buttons import Buttons from '@site/static/usage/v8/card/buttons/index.md'; - ## List Card import List from '@site/static/usage/v8/card/list/index.md'; - ## Theming ### Colors @@ -67,21 +65,26 @@ import CSSProps from '@site/static/usage/v8/card/theming/css-properties/index.md - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/checkbox.md b/versioned_docs/version-v8/api/checkbox.md index ddc9331f50e..9549e84616d 100644 --- a/versioned_docs/version-v8/api/checkbox.md +++ b/versioned_docs/version-v8/api/checkbox.md @@ -1,5 +1,5 @@ --- -title: "ion-checkbox" +title: 'ion-checkbox' --- import Props from '@ionic-internal/component-api/v8/checkbox/props.md'; @@ -11,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/checkbox/slots.md'; ion-checkbox: Ionic App Checkbox to Select Multiple Options - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Checkboxes allow the selection of multiple options from a set of options. They appear as checked (ticked) when activated. Clicking on a checkbox will toggle the `checked` property. They can also be checked programmatically by setting the `checked` property. ## Basic Usage @@ -55,7 +57,6 @@ import Justify from '@site/static/usage/v8/checkbox/justify/index.md'; - :::note `ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly. ::: @@ -115,19 +116,25 @@ interface CheckboxCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/chip.md b/versioned_docs/version-v8/api/chip.md index 3dfcbc3c540..04bc0f72ec7 100644 --- a/versioned_docs/version-v8/api/chip.md +++ b/versioned_docs/version-v8/api/chip.md @@ -1,6 +1,7 @@ --- -title: "ion-chip" +title: 'ion-chip' --- + import Props from '@ionic-internal/component-api/v8/chip/props.md'; import Events from '@ionic-internal/component-api/v8/chip/events.md'; import Methods from '@ionic-internal/component-api/v8/chip/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/chip/slots.md'; ion-chip: Text, Icon and Avatar for Ionic Framework Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -46,19 +50,25 @@ import CSSProps from '@site/static/usage/v8/chip/theming/css-properties/index.md ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/col.md b/versioned_docs/version-v8/api/col.md index d1254d28321..f6d9d0359ac 100644 --- a/versioned_docs/version-v8/api/col.md +++ b/versioned_docs/version-v8/api/col.md @@ -1,6 +1,7 @@ --- -title: "ion-col" +title: 'ion-col' --- + import Props from '@ionic-internal/component-api/v8/col/props.md'; import Events from '@ionic-internal/component-api/v8/col/events.md'; import Methods from '@ionic-internal/component-api/v8/col/methods.md'; @@ -10,40 +11,44 @@ import Slots from '@ionic-internal/component-api/v8/col/slots.md'; ion-col: Column Component Padding and Other Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Columns are cellular components of the [grid](./grid) system and go inside of a [row](./row). They will expand to fill the row. All content within a grid should go inside of a column. See the [grid](./grid) documentation for more information. - ## Column Alignment By default, columns will stretch to fill the entire height of the row. Columns are [flex items](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Item), so there are several [CSS classes](/docs/layout/css-utilities#flex-item-properties) that can be applied to a column to customize this behavior. - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/content.md b/versioned_docs/version-v8/api/content.md index c6b8ca6f290..a6407ea905c 100644 --- a/versioned_docs/version-v8/api/content.md +++ b/versioned_docs/version-v8/api/content.md @@ -1,6 +1,7 @@ --- -title: "ion-content" +title: 'ion-content' --- + import Props from '@ionic-internal/component-api/v8/content/props.md'; import Events from '@ionic-internal/component-api/v8/content/events.md'; import Methods from '@ionic-internal/component-api/v8/content/methods.md'; @@ -10,28 +11,28 @@ import Slots from '@ionic-internal/component-api/v8/content/slots.md'; ion-content: Scrollable Component for Ionic App Content - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The content component provides an easy to use content area with some useful methods to control the scrollable area. There should only be one content in a single view. Content, along with many other Ionic components, can be customized to modify its padding, margin, and more using the global styles provided in the [CSS Utilities](/docs/layout/css-utilities) or by individually styling it using CSS and the available [CSS Custom Properties](#css-custom-properties). - ## Basic Usage import Basic from '@site/static/usage/v8/content/basic/index.md'; - ## Header & Footer Content can be the only top-level component in a page, or it can be used alongside a [header](./header), [footer](./footer), or both. When used with a header or footer, it will adjust its size to fill the remaining height. @@ -40,7 +41,6 @@ import HeaderFooter from '@site/static/usage/v8/content/header-footer/index.md'; - ## Fullscreen Content By default, content fills the space between a [header](./header) and [footer](./footer) but does not go behind them. In certain cases, it may be desired to have the content scroll behind the header and footer, such as when the `translucent` property is set on either of them, or `opacity` is set on the toolbar. This can be achieved by setting the `fullscreen` property on the content to `true`. @@ -49,7 +49,6 @@ import Fullscreen from '@site/static/usage/v8/content/fullscreen/index.md'; - ## Fixed Content To place elements outside of the scrollable area, assign them to the `fixed` slot. Doing so will [absolutely position](https://developer.mozilla.org/en-US/docs/Web/CSS/position#absolute_positioning) the element to the top left of the content. In order to change the position of the element, it can be styled using the [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS properties. @@ -76,7 +75,6 @@ import ScrollEvents from '@site/static/usage/v8/content/scroll-events/index.md'; - ## Theming ### Colors @@ -161,21 +159,26 @@ interface ScrollCustomEvent extends ScrollBaseCustomEvent { } ``` - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/datetime-button.md b/versioned_docs/version-v8/api/datetime-button.md index 1fbd19c7187..5d603cd2aa4 100644 --- a/versioned_docs/version-v8/api/datetime-button.md +++ b/versioned_docs/version-v8/api/datetime-button.md @@ -1,6 +1,7 @@ --- -title: "ion-datetime-button" +title: 'ion-datetime-button' --- + import Props from '@ionic-internal/component-api/v8/datetime-button/props.md'; import Events from '@ionic-internal/component-api/v8/datetime-button/events.md'; import Methods from '@ionic-internal/component-api/v8/datetime-button/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/datetime-button/slots.md'; ion-datetime-button: Ionic Input for Datetime Picker - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -62,19 +66,25 @@ TODO --> ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/datetime.md b/versioned_docs/version-v8/api/datetime.md index 54a1efc8750..cfd41374a52 100644 --- a/versioned_docs/version-v8/api/datetime.md +++ b/versioned_docs/version-v8/api/datetime.md @@ -1,6 +1,7 @@ --- -title: "ion-datetime" +title: 'ion-datetime' --- + import Props from '@ionic-internal/component-api/v8/datetime/props.md'; import Events from '@ionic-internal/component-api/v8/datetime/events.md'; import Methods from '@ionic-internal/component-api/v8/datetime/methods.md'; @@ -46,7 +47,10 @@ import WheelStyling from '@site/static/usage/v8/datetime/styling/wheel-styling/i ion-datetime: Ionic API Input for Datetime Format Picker - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -75,15 +79,15 @@ and parse within JSON objects and databases. Below are some examples of ISO 8601 formats that can be used with `ion-datetime`: -| Description | Format | Datetime Value Example | -| -------------------- | ------------------------ | ------------------------------ | -| Year | `YYYY` | `1994` | -| Year and Month | `YYYY-MM` | `1994-12` | -| Complete Date | `YYYY-MM-DD` | `1994-12-15` | -| Date and Time | `YYYY-MM-DDTHH:mm` | `1994-12-15T13:47` | -| UTC Timezone | `YYYY-MM-DDTHH:mm:ssZ` | `1994-12-15T13:47:20Z` | -| Timezone Offset | `YYYY-MM-DDTHH:mm:ssTZD` | `1994-12-15T13:47:20+05:00` | -| Hour and Minute | `HH:mm` | `13:47` | +| Description | Format | Datetime Value Example | +| --------------- | ------------------------ | --------------------------- | +| Year | `YYYY` | `1994` | +| Year and Month | `YYYY-MM` | `1994-12` | +| Complete Date | `YYYY-MM-DD` | `1994-12-15` | +| Date and Time | `YYYY-MM-DDTHH:mm` | `1994-12-15T13:47` | +| UTC Timezone | `YYYY-MM-DDTHH:mm:ssZ` | `1994-12-15T13:47:20Z` | +| Timezone Offset | `YYYY-MM-DDTHH:mm:ssTZD` | `1994-12-15T13:47:20+05:00` | +| Hour and Minute | `HH:mm` | `13:47` | Note that the year is always four-digits, milliseconds (if it's added) is always three-digits, and all others are always two-digits. So the number representing @@ -156,18 +160,17 @@ The time label is not automatically localized. See [Time Label](#time-label) for There are 4 primary hour cycle types: -| Hour cycle type | Description | -| --------------- | ------------------------------------------------------------ | -| `'h12'` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. | -| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. | -| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. | -| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | +| Hour cycle type | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------- | +| `'h12'` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. | +| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. | +| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. | +| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | :::note - Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle +Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle ::: - There may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help. In the following example, we can use the `hourCycle` property to force `ion-datetime` to use the 12 hour cycle even though the locale is `en-GB`, which uses a 24 hour cycle by default: @@ -195,7 +198,7 @@ For example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you c :::note -Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. +Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. ::: ## Presentation @@ -415,7 +418,6 @@ console.log(formattedString); // Jun 4, 2021 See https://date-fns.org/docs/format for a list of all the valid format tokens. - ## Advanced Datetime Validation and Manipulation The datetime picker provides the simplicity of selecting an exact format, and @@ -481,19 +483,25 @@ interface DatetimeCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/fab-button.md b/versioned_docs/version-v8/api/fab-button.md index ec31f2f7a3b..3107d43fe5f 100644 --- a/versioned_docs/version-v8/api/fab-button.md +++ b/versioned_docs/version-v8/api/fab-button.md @@ -1,6 +1,7 @@ --- -title: "ion-fab-button" +title: 'ion-fab-button' --- + import Props from '@ionic-internal/component-api/v8/fab-button/props.md'; import Events from '@ionic-internal/component-api/v8/fab-button/events.md'; import Methods from '@ionic-internal/component-api/v8/fab-button/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/fab-button/slots.md'; ion-fab-button: Ionic FAB Button Icon for Primary Action - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Floating Action Buttons (FABs) represent the primary action in an application. By default, they have a circular shape. When pressed, the button may open more related actions. As the name suggests, FABs generally float over the content in a fixed position. This is achieved by wrapping the fab button in a [fab](./fab) component. If the button is not wrapped with a fab, it will scroll with the content. @@ -25,19 +28,25 @@ As the name suggests, FABs generally float over the content in a fixed position. For usage examples, see the [fab documentation](./fab). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/versioned_docs/version-v8/api/fab-list.md b/versioned_docs/version-v8/api/fab-list.md index eb004debfa3..0b5e9969186 100644 --- a/versioned_docs/version-v8/api/fab-list.md +++ b/versioned_docs/version-v8/api/fab-list.md @@ -1,6 +1,7 @@ --- -title: "ion-fab-list" +title: 'ion-fab-list' --- + import Props from '@ionic-internal/component-api/v8/fab-list/props.md'; import Events from '@ionic-internal/component-api/v8/fab-list/events.md'; import Methods from '@ionic-internal/component-api/v8/fab-list/methods.md'; @@ -17,19 +18,25 @@ The fab list component is a container for multiple [fab buttons](./fab-button). For usage examples, see the [fab documentation](./fab). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/versioned_docs/version-v8/api/fab.md b/versioned_docs/version-v8/api/fab.md index 068a068364c..eada4553579 100644 --- a/versioned_docs/version-v8/api/fab.md +++ b/versioned_docs/version-v8/api/fab.md @@ -1,6 +1,7 @@ --- -title: "ion-fab" +title: 'ion-fab' --- + import Props from '@ionic-internal/component-api/v8/fab/props.md'; import Events from '@ionic-internal/component-api/v8/fab/events.md'; import Methods from '@ionic-internal/component-api/v8/fab/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/fab/slots.md'; ion-fab: Ionic Floating Action Button for Android and iOS - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -112,19 +116,25 @@ import CSSShadowParts from '@site/static/usage/v8/fab/theming/css-shadow-parts/i Since FABs are allowed to contain only icons, developers must provide an `aria-label` on each `ion-fab-button` instance. Without this label, assistive technologies will not be able to announce the purpose of each button. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/footer.md b/versioned_docs/version-v8/api/footer.md index 475537201fb..f45e9b6a85d 100644 --- a/versioned_docs/version-v8/api/footer.md +++ b/versioned_docs/version-v8/api/footer.md @@ -1,6 +1,7 @@ --- -title: "ion-footer" +title: 'ion-footer' --- + import Props from '@ionic-internal/component-api/v8/footer/props.md'; import Events from '@ionic-internal/component-api/v8/footer/events.md'; import Methods from '@ionic-internal/component-api/v8/footer/methods.md'; @@ -10,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v8/footer/slots.md'; ion-footer: Page Footer | Ionic App Footer Root Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Footer is a root component of a page that aligns itself to the bottom of the page. It is recommended to be used as a wrapper for one or more [toolbars](./toolbar), but it can be used to wrap any element. When a toolbar is used inside of a footer, the content will be adjusted so it is sized correctly, and the footer will account for any device safe areas. ## Basic Usage @@ -24,7 +27,6 @@ import Basic from '@site/static/usage/v8/footer/basic/index.md'; - ## Translucent Footer Footers can match the transparency found in native iOS applications by setting the `translucent` property. In order to see the content scrolling behind the footer, the `fullscreen` property needs to be set on the content. This effect will only apply when the mode is `"ios"` and the device supports [backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter#browser_compatibility). @@ -33,7 +35,6 @@ import Translucent from '@site/static/usage/v8/footer/translucent/index.md'; - ## Fade Footer Many native iOS applications have a fade effect on the toolbar. This can be achieved by setting the `collapse` property on the footer to `"fade"`. When the content is scrolled to the end, the background and border on the footer will fade away. This effect will only apply when the mode is `"ios"`. @@ -42,7 +43,6 @@ import Fade from '@site/static/usage/v8/footer/fade/index.md'; - ### Usage with Virtual Scroll A fade footer requires a scroll container to work properly. When using a virtual scrolling solution, a custom scroll target needs to be provided. Scrolling on the content needs to be disabled and the `.ion-content-scroll-host` class needs to be added to the element responsible for scrolling. @@ -59,21 +59,26 @@ import NoBorder from '@site/static/usage/v8/footer/no-border/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/grid.md b/versioned_docs/version-v8/api/grid.md index e0b34b5669e..e573c6b9e37 100644 --- a/versioned_docs/version-v8/api/grid.md +++ b/versioned_docs/version-v8/api/grid.md @@ -1,6 +1,7 @@ --- -title: "ion-grid" +title: 'ion-grid' --- + import Props from '@ionic-internal/component-api/v8/grid/props.md'; import Events from '@ionic-internal/component-api/v8/grid/events.md'; import Methods from '@ionic-internal/component-api/v8/grid/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/grid/slots.md'; ion-grid: Display Grids for Mobile-First Custom App Layout - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The grid is a powerful mobile-first flexbox system for building custom layouts. It is composed of three units — a grid, [row(s)](row.md) and [column(s)](col.md). Columns will expand to fill the row, and will resize to fit additional columns. It is based on a 12 column layout with different breakpoints based on the screen size. The number of columns can be customized using CSS. ## Overview @@ -49,7 +52,6 @@ The default breakpoints for the grid and the corresponding properties are define | lg | 992px | `sizeLg` | `offsetLg` | `pushLg` | `pullLg` | Set columns when (min-width: 992px) | | xl | 1200px | `sizeXl` | `offsetXl` | `pushXl` | `pullXl` | Set columns when (min-width: 1200px) | - ## Basic Usage By default, columns will take up equal width inside of a row for all devices and screen sizes. @@ -58,7 +60,6 @@ import Basic from '@site/static/usage/v8/grid/basic/index.md'; - ## Fixed Grid Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, see [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen to see the grid width change. @@ -75,7 +76,6 @@ import Fixed from '@site/static/usage/v8/grid/fixed/index.md'; - ## Column Size Columns can be set to specific sizes to take up a certain number out of the total number of columns, or resize their width based on the content. The default number of columns is 12, but this can be customized. See the [Number of Columns](#number-of-columns) section below for more information. @@ -88,7 +88,6 @@ import SizeAuto from '@site/static/usage/v8/grid/size-auto/index.md'; - ### Specified size Set the `size` of a column and the others will automatically resize around it. If a size is specified on all of the columns and it doesn't add up to the total number of columns, there will be empty space after the columns. @@ -105,7 +104,6 @@ import SizeResponsive from '@site/static/usage/v8/grid/size-responsive/index.md' - ## Column Offset Columns can be offset to shift to the right by a certain number of columns out of the total number of columns. @@ -126,7 +124,6 @@ import OffsetResponsive from '@site/static/usage/v8/grid/offset-responsive/index - ## Column Push & Pull Columns can be pushed to to the right or pulled to the left by a certain number of columns out of the total number of columns. @@ -157,7 +154,6 @@ import VerticalAlignment from '@site/static/usage/v8/grid/vertical-alignment/ind - ### Horizontal Alignment All columns can be horizontally aligned inside of a row by adding different classes to the row. For a list of available classes, see [css utilities](/layout/css-utilities.md#flex-container-properties). @@ -197,19 +193,25 @@ import Padding from '@site/static/usage/v8/grid/customizing/padding/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/header.md b/versioned_docs/version-v8/api/header.md index 45a71ea5359..5dd1d28f753 100644 --- a/versioned_docs/version-v8/api/header.md +++ b/versioned_docs/version-v8/api/header.md @@ -1,6 +1,7 @@ --- -title: "ion-header" +title: 'ion-header' --- + import Props from '@ionic-internal/component-api/v8/header/props.md'; import Events from '@ionic-internal/component-api/v8/header/events.md'; import Methods from '@ionic-internal/component-api/v8/header/methods.md'; @@ -10,22 +11,22 @@ import Slots from '@ionic-internal/component-api/v8/header/slots.md'; ion-header: Header Parent Component for Ionic Framework Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Header is a root component of a page that aligns itself to the top of the page. It is recommended to be used as a wrapper for one or more [toolbars](./toolbar), but it can be used to wrap any element. When a toolbar is used inside of a header, the content will be adjusted so it is sized correctly, and the header will account for any device safe areas. - ## Basic Usage import Basic from '@site/static/usage/v8/header/basic/index.md'; - ## Translucent Header Headers can match the transparency found in native iOS applications by setting the `translucent` property. In order to see the content scrolling behind the header, the `fullscreen` property needs to be set on the content. This effect will only apply when the mode is `"ios"` and the device supports [backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter#browser_compatibility). @@ -34,7 +35,6 @@ import Translucent from '@site/static/usage/v8/header/translucent/index.md'; - ## Condensed Header Ionic provides the functionality found in native iOS applications to show a large toolbar title and then collapse it to a small title when scrolling. This can be done by adding two headers, one above the content and one inside of the content, and then setting the `collapse` property to `"condense"` on the header inside of the content. This effect will only apply when the mode is "ios". @@ -43,7 +43,6 @@ import Condense from '@site/static/usage/v8/header/condense/index.md'; - ## Fade Header Many native iOS applications have a fade effect on the toolbar. This can be achieved by setting the `collapse` property on the header to `"fade"`. When the page is first loaded, the background and border on the header will be hidden. As the content is scrolled, the header will fade back in. This effect will only apply when the mode is "ios". @@ -54,7 +53,6 @@ import Fade from '@site/static/usage/v8/header/fade/index.md'; - ### Usage with Virtual Scroll A fade header requires a scroll container to work properly. When using a virtual scrolling solution, a custom scroll target needs to be provided. Scrolling on the content needs to be disabled and the `.ion-content-scroll-host` class needs to be added to the element responsible for scrolling. @@ -63,7 +61,6 @@ import CustomScrollTarget from '@site/static/usage/v8/header/custom-scroll-targe - ## Borders In `"md"` mode, the header will have a `box-shadow` on the bottom. In `"ios"` mode, it will receive a `border` on the bottom. These can be removed by adding the `.ion-no-border` class to the header. @@ -72,21 +69,26 @@ import NoBorder from '@site/static/usage/v8/header/no-border/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/icon.md b/versioned_docs/version-v8/api/icon.md index 435175ef119..eb311b6a2b9 100644 --- a/versioned_docs/version-v8/api/icon.md +++ b/versioned_docs/version-v8/api/icon.md @@ -20,7 +20,6 @@ import Basic from '@site/static/usage/v8/icon/basic/index.md'; - ## Accessibility Icons that are purely decorative content should have aria-hidden="true". This will not visually hide the icon, but it will hide the element from assistive technology. @@ -29,7 +28,6 @@ Icons that are purely decorative content should have aria-hidden="true" ``` - If the icon is interactive, it should have alternate text defined by adding an aria-label. ```html diff --git a/versioned_docs/version-v8/api/img.md b/versioned_docs/version-v8/api/img.md index bc812a8ca0b..bf6a23948cb 100644 --- a/versioned_docs/version-v8/api/img.md +++ b/versioned_docs/version-v8/api/img.md @@ -1,5 +1,5 @@ --- -title: "ion-img" +title: 'ion-img' --- import Props from '@ionic-internal/component-api/v8/img/props.md'; @@ -11,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/img/slots.md'; ion-img: Img Tag to Lazy Load Images in Viewport - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Img is a tag that will lazily load an image whenever the tag is in the viewport. This is extremely useful when generating a large list as images are only loaded when they're visible. The component uses [Intersection Observer](https://caniuse.com/#feat=intersectionobserver) internally, which is supported in most modern browsers, but falls back to a `setTimeout` when it is not supported. ## Basic Usage @@ -28,19 +30,25 @@ import Basic from '@site/static/usage/v8/img/basic/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/versioned_docs/version-v8/api/infinite-scroll-content.md b/versioned_docs/version-v8/api/infinite-scroll-content.md index 069852c9f03..9ec68556edf 100644 --- a/versioned_docs/version-v8/api/infinite-scroll-content.md +++ b/versioned_docs/version-v8/api/infinite-scroll-content.md @@ -1,5 +1,5 @@ --- -title: "ion-infinite-scroll-content" +title: 'ion-infinite-scroll-content' --- import Props from '@ionic-internal/component-api/v8/infinite-scroll-content/props.md'; @@ -16,19 +16,25 @@ The `ion-infinite-scroll-content` component is the default child used by the `io For more information as well as usage, see the [Infinite Scroll Documentation](./infinite-scroll.md#infinite-scroll-content). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/versioned_docs/version-v8/api/infinite-scroll.md b/versioned_docs/version-v8/api/infinite-scroll.md index 5a8d29dc832..ba93930b876 100644 --- a/versioned_docs/version-v8/api/infinite-scroll.md +++ b/versioned_docs/version-v8/api/infinite-scroll.md @@ -1,5 +1,5 @@ --- -title: "ion-infinite-scroll" +title: 'ion-infinite-scroll' --- import Props from '@ionic-internal/component-api/v8/infinite-scroll/props.md'; @@ -11,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v8/infinite-scroll/slots.md'; ion-infinite-scroll: Infinite Scroller Action Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The Infinite Scroll component calls an action to be performed when the user scrolls a specified distance from the bottom or top of the page. The expression assigned to the `ionInfinite` event is called when the user reaches that defined distance. When this expression has finished any and all tasks, it should call the `complete()` method on the infinite scroll instance. @@ -75,12 +77,8 @@ For example, when rendering a collection of items in an `ion-list`: ```html - - First item - - - Second item - + First item + Second item ... @@ -105,19 +103,25 @@ interface InfiniteScrollCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/input-otp.md b/versioned_docs/version-v8/api/input-otp.md index 71439665e47..ffab19ef675 100644 --- a/versioned_docs/version-v8/api/input-otp.md +++ b/versioned_docs/version-v8/api/input-otp.md @@ -1,6 +1,7 @@ --- -title: "ion-input-otp" +title: 'ion-input-otp' --- + import Props from '@ionic-internal/component-api/v8/input-otp/props.md'; import Events from '@ionic-internal/component-api/v8/input-otp/events.md'; import Methods from '@ionic-internal/component-api/v8/input-otp/methods.md'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v8/input-otp/slots.md'; ion-input-otp: One-Time Password Input Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -32,6 +36,7 @@ import Basic from '@site/static/usage/v8/input-otp/basic/index.md'; The `type` property determines the input format, supporting either numeric or alphanumeric verification codes. It accepts two values: `number` and `text`. It uses `type="number"` by default for entering numeric verification codes. When `type="text"` is specified, it accepts alphanumeric input. This flexibility allows handling different OTP formats, whether numeric-only codes (like SMS verification codes) or alphanumeric codes (like backup codes or recovery keys). The `type` property automatically sets both the `inputmode` and `pattern` attributes: + - When `type="number"`: - Sets `inputmode="numeric"` to show a numeric keyboard on mobile devices - Sets `pattern="[\p{N}]"` to allow only numeric input @@ -72,6 +77,7 @@ import Size from '@site/static/usage/v8/input-otp/size/index.md'; ## Separators The `separators` property adds visual dividers between one or more of the input boxes. Separators can be defined in three ways: + - Comma-separated string of numbers (e.g., `"1,3"`) - Array of numbers (e.g., `[1, 3]`) - String `"all"` to show separators between every input box @@ -85,6 +91,7 @@ import Separators from '@site/static/usage/v8/input-otp/separators/index.md'; ## States The component supports various states for automatic styling of input boxes: + - `disabled` and `readonly` states via respective properties - Form validation states: `valid` and `invalid` visually indicated through CSS classes - In Angular: validation states are automatically managed through the framework's value accessors and form validation @@ -99,6 +106,7 @@ import States from '@site/static/usage/v8/input-otp/states/index.md'; ## Pattern The `pattern` property enables custom validation using regular expressions. It accepts a [string regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Cheatsheet) or [unicode regular expression](https://www.regular-expressions.info/unicode.html) to validate allowed characters. The `pattern` must match the entire value, not just a subset. Default patterns: + - `type="number"`: `"[\p{N}]"` for matching any kind of numeric character in any script. - `type="text"`: `"[\p{L}\p{N}]"` for any kind of numeric character in any script and any kind of letter from any language. @@ -106,9 +114,10 @@ The component will prevent users from entering any characters that don't match t :::tip When using a custom `pattern`, remember that the `type` property controls which keyboard appears on mobile devices: + - Use `type="number"` for numeric-only patterns to show the numeric keyboard - Use `type="text"` for patterns that include letters to show the alphanumeric keyboard -::: + ::: import Pattern from '@site/static/usage/v8/input-otp/pattern/index.md'; @@ -121,7 +130,7 @@ import Pattern from '@site/static/usage/v8/input-otp/pattern/index.md'; The `color` property changes the color palette for input boxes. For `outline` fills, this property changes the caret color, highlight color and border color. For `solid` fills, this property changes the caret color and highlight color. :::note -The `color` property does *not* change the text color of the input OTP. For that, use the [`--color` CSS property](#css-custom-properties-1). +The `color` property does _not_ change the text color of the input OTP. For that, use the [`--color` CSS property](#css-custom-properties-1). ::: import Colors from '@site/static/usage/v8/input-otp/theming/colors/index.md'; @@ -144,30 +153,36 @@ The keyboard navigation for Input OTP follows the [ARIA Authoring Practices Guid These keyboard interactions apply to all `ion-input-otp` elements when the component is not disabled. -| Key | Description | -| --- | --- | -| Tab | When first tabbing into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, tabbing moves to the next focusable element on the page. | -| Shift + Tab | When tabbing backwards into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, shift tabbing focus moves to the previous focusable element on the page. | -| ArrowRight | Moves focus to the next input box, stopping at the first empty box. In RTL mode, moves focus back to any previous box that contains a value. | -| ArrowLeft | Moves focus back to any previous box that contains a value. In RTL mode, moves focus to the next input box, stopping at the first empty box. | -| Any character matching the `pattern` property | Fills the current box and automatically moves focus to the next empty box. If all boxes are filled, focus remains on the last box. If the current box has a value, override the value with the entered character. In RTL mode, input fills boxes from right to left. | -| Backspace | In an empty box: moves focus back one box and clears its value.
In a box with a value: clears that value.
With values in boxes to the right: shifts them all one position to the left. In RTL mode, with values in boxes to the left: shifts them all one position to the right. | +| Key | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Tab | When first tabbing into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, tabbing moves to the next focusable element on the page. | +| Shift + Tab | When tabbing backwards into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, shift tabbing focus moves to the previous focusable element on the page. | +| ArrowRight | Moves focus to the next input box, stopping at the first empty box. In RTL mode, moves focus back to any previous box that contains a value. | +| ArrowLeft | Moves focus back to any previous box that contains a value. In RTL mode, moves focus to the next input box, stopping at the first empty box. | +| Any character matching the `pattern` property | Fills the current box and automatically moves focus to the next empty box. If all boxes are filled, focus remains on the last box. If the current box has a value, override the value with the entered character. In RTL mode, input fills boxes from right to left. | +| Backspace | In an empty box: moves focus back one box and clears its value.
In a box with a value: clears that value.
With values in boxes to the right: shifts them all one position to the left. In RTL mode, with values in boxes to the left: shifts them all one position to the right. | | Ctrl + V
Cmd + V | Pastes content starting from the first box, regardless of which box is currently focused. All existing values are cleared before pasting. For example, if you have "1234" in all boxes and paste "56", the result will be "56" in the first two boxes with the remaining boxes empty. If the pasted content is longer than the available boxes, the extra characters are ignored. | ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/input-password-toggle.md b/versioned_docs/version-v8/api/input-password-toggle.md index 7813203667a..771dea514b7 100644 --- a/versioned_docs/version-v8/api/input-password-toggle.md +++ b/versioned_docs/version-v8/api/input-password-toggle.md @@ -1,6 +1,7 @@ --- -title: "ion-input-password-toggle" +title: 'ion-input-password-toggle' --- + import Props from '@ionic-internal/component-api/v8/input-password-toggle/props.md'; import Events from '@ionic-internal/component-api/v8/input-password-toggle/events.md'; import Methods from '@ionic-internal/component-api/v8/input-password-toggle/methods.md'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/input-password-toggle/slots. ion-input-password-toggle: Toggle the visibility of a password in Input - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The InputPasswordToggle component is a companion component to [Input](./input). It allows users to toggle the visibility of text in a password input. ## Basic Usage @@ -28,25 +31,30 @@ InputPasswordToggle must be used with an [Input](./input) that has its [`type`]( Using any other `type` will cause a warning to be logged. ::: - import Basic from '@site/static/usage/v8/input-password-toggle/basic/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/input.md b/versioned_docs/version-v8/api/input.md index 18d71de4eb8..c893927b599 100644 --- a/versioned_docs/version-v8/api/input.md +++ b/versioned_docs/version-v8/api/input.md @@ -1,6 +1,7 @@ --- -title: "ion-input" +title: 'ion-input' --- + import Props from '@ionic-internal/component-api/v8/input/props.md'; import Events from '@ionic-internal/component-api/v8/input/events.md'; import Methods from '@ionic-internal/component-api/v8/input/methods.md'; @@ -10,24 +11,24 @@ import Slots from '@ionic-internal/component-api/v8/input/slots.md'; ion-input: Custom Input With Styling and CSS Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input and integrates with the keyboard on mobile devices. - ## Basic Usage import Basic from '@site/static/usage/v8/input/basic/index.md'; - ## Types The input component is meant for text type inputs only, such as `"text"`, `"password"`, `"email"`, `"number"`, `"search"`, `"tel"`, and `"url"`. It supports all standard text input events including `keyup`, `keydown`, `keypress`, and more. The default `type` is `"text"`. @@ -78,7 +79,6 @@ import Clear from '@site/static/usage/v8/input/clear/index.md'; - ## Filled Inputs Material Design offers filled styles for an input. The `fill` property on the input can be set to either `"solid"` or `"outline"`. @@ -93,7 +93,6 @@ import Fill from '@site/static/usage/v8/input/fill/index.md'; - ## Helper & Error Text Helper and error text can be used inside of an input with the `helperText` and `errorText` property. The error text will not be displayed unless the `ion-invalid` and `ion-touched` classes are added to the `ion-input`. This ensures errors are not shown before the user has a chance to enter data. @@ -173,7 +172,7 @@ import StartEndSlots from '@site/static/usage/v8/input/start-end-slots/index.md' Setting the `color` property changes the color palette for each input. On `ios` mode, this property changes the caret color. On `md` mode, this property changes the caret color and the highlight/underline color. :::note -The `color` property does *not* change the text color of the input. For that, use the [`--color` CSS property](#css-custom-properties-1). +The `color` property does _not_ change the text color of the input. For that, use the [`--color` CSS property](#css-custom-properties-1). ::: import Colors from '@site/static/usage/v8/input/theming/colors/index.md'; @@ -209,21 +208,26 @@ interface InputCustomEvent extends CustomEvent { } ``` - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item-divider.md b/versioned_docs/version-v8/api/item-divider.md index 6de7f9fe8fc..bac8aaba388 100644 --- a/versioned_docs/version-v8/api/item-divider.md +++ b/versioned_docs/version-v8/api/item-divider.md @@ -1,6 +1,7 @@ --- -title: "ion-item-divider" +title: 'ion-item-divider' --- + import Props from '@ionic-internal/component-api/v8/item-divider/props.md'; import Events from '@ionic-internal/component-api/v8/item-divider/events.md'; import Methods from '@ionic-internal/component-api/v8/item-divider/methods.md'; @@ -10,24 +11,24 @@ import Slots from '@ionic-internal/component-api/v8/item-divider/slots.md'; ion-item-divider: Item Divider Block Element for Ionic Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Item dividers are block elements that can be used to separate [items](./item) in a list. They are similar to list headers, but instead of only being placed at the top of a list, they should go in between groups of items. - ## Basic Usage import Basic from '@site/static/usage/v8/item-divider/basic/index.md'; - ## Theming ### Colors @@ -36,28 +37,32 @@ import Colors from '@site/static/usage/v8/item-divider/theming/colors/index.md'; - ### CSS Custom Properties import CSSProps from '@site/static/usage/v8/item-divider/theming/css-properties/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item-group.md b/versioned_docs/version-v8/api/item-group.md index 6943a72c3ec..c487b260e04 100644 --- a/versioned_docs/version-v8/api/item-group.md +++ b/versioned_docs/version-v8/api/item-group.md @@ -1,6 +1,7 @@ --- -title: "ion-item-group" +title: 'ion-item-group' --- + import Props from '@ionic-internal/component-api/v8/item-group/props.md'; import Events from '@ionic-internal/component-api/v8/item-group/events.md'; import Methods from '@ionic-internal/component-api/v8/item-group/methods.md'; @@ -10,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v8/item-group/slots.md'; ion-item-group: Group Items to Divide into Multiple Sections - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Item groups are containers that organize similar [items](./item) together. They can contain [item dividers](./item-divider) to divide the items into multiple sections. They can also be used to group [sliding items](./item-sliding). ## Basic Usage @@ -30,21 +33,26 @@ import SlidingItems from '@site/static/usage/v8/item-group/sliding-items/index.m - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item-option.md b/versioned_docs/version-v8/api/item-option.md index e39d3e42d56..17a7d3d3e28 100644 --- a/versioned_docs/version-v8/api/item-option.md +++ b/versioned_docs/version-v8/api/item-option.md @@ -1,6 +1,7 @@ --- -title: "ion-item-option" +title: 'ion-item-option' --- + import Props from '@ionic-internal/component-api/v8/item-option/props.md'; import Events from '@ionic-internal/component-api/v8/item-option/events.md'; import Methods from '@ionic-internal/component-api/v8/item-option/methods.md'; @@ -10,33 +11,40 @@ import Slots from '@ionic-internal/component-api/v8/item-option/slots.md'; ion-item-option: Option Button for Sliding Item in Ionic - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The item option component is an button for a sliding item. It must be placed inside of [item options](./item-options). The `ionSwipe` event and the `expandable` property can be combined to create a full swipe action for the item. See the [item sliding](./item-sliding) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item-options.md b/versioned_docs/version-v8/api/item-options.md index f4899c864ca..1d89741d24a 100644 --- a/versioned_docs/version-v8/api/item-options.md +++ b/versioned_docs/version-v8/api/item-options.md @@ -1,6 +1,7 @@ --- -title: "ion-item-options" +title: 'ion-item-options' --- + import Props from '@ionic-internal/component-api/v8/item-options/props.md'; import Events from '@ionic-internal/component-api/v8/item-options/events.md'; import Methods from '@ionic-internal/component-api/v8/item-options/methods.md'; @@ -10,41 +11,45 @@ import Slots from '@ionic-internal/component-api/v8/item-options/slots.md'; ion-item-options: Option Button Components for Ionic Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The item options component is a container for the [item option](./item-option) buttons in a sliding item. These buttons can be placed either on the [start or end side](#side-description). See the [item sliding](./item-sliding) documentation for more information. - ## Side Description | Side | Position | Swipe Direction | -|---------|-----------------------------------------------------------------|-------------------------------------------------------------------| +| ------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | | `start` | To the `left` of the content in LTR, and to the `right` in RTL. | From `left` to `right` in LTR, and from `right` to `left` in RTL. | | `end` | To the `right` of the content in LTR, and to the `left` in RTL. | From `right` to `left` in LTR, and from `left` to `right` in RTL. | - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item-sliding.md b/versioned_docs/version-v8/api/item-sliding.md index 3d8b9a1f61d..61eaf7a13e5 100644 --- a/versioned_docs/version-v8/api/item-sliding.md +++ b/versioned_docs/version-v8/api/item-sliding.md @@ -1,6 +1,7 @@ --- -title: "ion-item-sliding" +title: 'ion-item-sliding' --- + import Props from '@ionic-internal/component-api/v8/item-sliding/props.md'; import Events from '@ionic-internal/component-api/v8/item-sliding/events.md'; import Methods from '@ionic-internal/component-api/v8/item-sliding/methods.md'; @@ -10,15 +11,16 @@ import Slots from '@ionic-internal/component-api/v8/item-sliding/slots.md'; ion-item-sliding: Slide Buttons | Slide Right to Left - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - A sliding item contains an item that can be dragged to reveal option buttons. It requires an [item](./item) component as a child. All options to reveal should be placed in the [item options](./item-options) element. - ## Basic Usage Sliding item options are placed on the `"end"` side of the item by default. This means that options are revealed when the item is swiped from end to start, i.e. from right to left in LTR, but from left to right in RTL. To place them on the opposite side, so that they are revealed when swiping in the opposite direction, set the side attribute to `"start"` on the [item options](./item-options) element. Up to two item options can be used at the same time in order to reveal two different sets of options depending on the swiping direction. @@ -27,7 +29,6 @@ import Basic from '@site/static/usage/v8/item-sliding/basic/index.md'; - ## Icon Options When an icon is placed alongside text in the [item option](./item-option), it will display the icon on top of the text by default. The slot on the icon can be changed to any of the available [item option slots](./item-option#slots) to change its position. @@ -36,7 +37,6 @@ import Icons from '@site/static/usage/v8/item-sliding/icons/index.md'; - ## Expandable Options Options can be expanded to take up the full width of the parent `ion-item` if you swipe past a certain point. This can be combined with the `ionSwipe` event on the [item options](./item-options) to call a method when the item is fully swiped. @@ -45,7 +45,6 @@ import Expandable from '@site/static/usage/v8/item-sliding/expandable/index.md'; - ## Interfaces ### ItemSlidingCustomEvent @@ -59,19 +58,25 @@ interface ItemSlidingCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/versioned_docs/version-v8/api/item.md b/versioned_docs/version-v8/api/item.md index c357c0022a7..789e822fd1f 100644 --- a/versioned_docs/version-v8/api/item.md +++ b/versioned_docs/version-v8/api/item.md @@ -1,6 +1,7 @@ --- -title: "ion-item" +title: 'ion-item' --- + import Props from '@ionic-internal/component-api/v8/item/props.md'; import Events from '@ionic-internal/component-api/v8/item/events.md'; import Methods from '@ionic-internal/component-api/v8/item/methods.md'; @@ -13,7 +14,10 @@ import BestPracticeFigure from '@components/global/BestPracticeFigure'; ion-item: Input, Edit, or Delete iOS and Android Item Elements - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -22,7 +26,6 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Items should only be used as rows in a [List](./list) with other items. Items can be swiped, deleted, reordered, edited, and more. - ## Basic Usage Items left align text and wrap when the text is wider than the item. We can modify this behavior using the CSS Utilities provided by Ionic Framework, such as using `.ion-text-nowrap` in the below example. See the [CSS Utilities Documentation](/docs/layout/css-utilities) for more classes that can be added to an item to transform the text. @@ -31,7 +34,6 @@ import Basic from '@site/static/usage/v8/item/basic/index.md'; - ## Content Types While items in a list take many forms, they typically support 5 different content types: supporting visuals, text, metadata, actions, and controls. However, not all of these content types should be used together at the same time. The following guide shows the different content types as well as how to properly utilize them in an application. @@ -46,8 +48,18 @@ If a visual is required to interact with the item, such as an icon button, then text="Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse." doText="Align visuals on the same side in a list" doNotText="Don't render visuals with different alignments in the same list" - doImage={A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line.} - doNotImage={A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line} + doImage={ + A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line. + } + doNotImage={ + A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line + } /> In the example below, we are creating two lists with supporting visuals. The first list uses icons, and the second list uses avatars. The visuals are decorative, so they all have `aria-hidden="true"`. Additionally, they are presented consistently in the `start` slot. @@ -61,11 +73,27 @@ import SupportingVisuals from '@site/static/usage/v8/item/content-types/supporti The text content type includes form control labels or other visible text. This text serves to indicate the intent of the item. Try to keep the text short and to the point. If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a Note at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.} + text={ + <> + If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional + sentences to a Note at the bottom of the list. Adding the item to its own + list makes it clear which item the text is associated with. + + } doText="Move long text outside of the list" doNotText="Don't try to fit long text in an item" - doImage={A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list.} - doNotImage={A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item.} + doImage={ + A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list. + } + doNotImage={ + A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item. + } /> In the example below, we are creating a list with different types of text. The "First Name" and "Last Name" labels serve to indicate what to type into the text inputs. @@ -86,16 +114,36 @@ Metadata provides additional context for an item such as status text or counts. text="Limit the amount of metadata you include to only the most relevant information." doText="Add only the most important metadata" doNotText="Don't add too much metadata as it can overwhelm or confuse the user." - doImage={A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.} - doNotImage={A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today.} + doImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. + } + doNotImage={ + A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today. + } /> } - cautionImage={A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list.} + doImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. + } + cautionImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list. + } /> In the example below, we are creating two lists with different kinds of metadata. The first list uses [Note](./note) to show how many tasks are in each to-do list. @@ -113,11 +161,32 @@ Actions are interactive elements that do something when you activate them. An it Developers should avoid creating nested interactives which can break the user experience with screen readers. For example, developers should avoid adding a button inside the main content of the Item if the `button` property is set to `true`. Actions can be added by using the Item Sliding component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.} - doText={<>Use an Item Sliding to reveal multiple actions by swiping on the Item.} + text={ + <> + Actions can be added by using the Item Sliding component. Actions can + also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more + than 2 actions. + + } + doText={ + <> + Use an Item Sliding to reveal multiple actions by swiping on the + Item. + + } doNotText="Don't put more than 2 actions within an Item." - doImage={A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item.} - doNotImage={A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off.} + doImage={ + A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item. + } + doNotImage={ + A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off. + } /> In the example below, we are creating a list of contacts. Each item is a stubbed button intended to bring you to the full contact page for that item. There are additional actions associated with each item that users can reveal by swiping on the item. @@ -131,27 +200,74 @@ import Actions from '@site/static/usage/v8/item/content-types/actions/index.md'; Controls are form components such as checkboxes, inputs, radios, and more. Each item in a list should have at most two controls due to screen space constraints. Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. Filled Inputs are a great way of visually defining the input container outside of a list.} + text={ + <> + Metadata such as helper text or character counts should not be used on form controls in list views. If such + metadata is needed, the form control should be placed outside of a list.{' '} + Filled Inputs are a great way of visually defining the input + container outside of a list. + + } doText="Place inputs with metadata outside of the list." doNotText="Don't put metadata for inputs in the list." - doImage={There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with.} - doNotImage={There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with.} + doImage={ + There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with. + } + doNotImage={ + There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with. + } /> Alternatively, the metadata can be placed in a Note at the bottom of the list.} + text={ + <> + Alternatively, the metadata can be placed in a Note at the bottom of the + list. + + } doText="Place metadata for inputs at the end of a list." doNotText="Don't put metadata for inputs in the list." - doImage={There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.} - doNotImage={There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.} + doImage={ + There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above. + } + doNotImage={ + There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with. + } /> Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a Modal that is accessible from the item.} + text={ + <> + Items should typically have no more than two controls. If you need more controls, consider adding the additional + controls in a Modal that is accessible from the item. + + } doText="Move additional controls to a submenu accessible from the item." doNotText="Don't use more than two controls within an item." - doImage={There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.} - doNotImage={There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.} + doImage={ + There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with. + } + doNotImage={ + There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above. + } /> In the example below, we are creating a list of to-do tasks. Each item has a checkbox and an input. The checkbox lets the user mark a task as complete, and the input lets the user change the name of the task. @@ -160,7 +276,6 @@ import Controls from '@site/static/usage/v8/item/content-types/controls/index.md - ## Clickable Items An item is considered "clickable" if it has an `href` or `button` property set. Clickable items have a few visual differences that indicate they can be interacted with. For example, a clickable item receives the ripple effect upon activation in `md` mode, has a highlight when activated in `ios` mode, and has a [detail arrow](#detail-arrows) by default in `ios` mode. @@ -169,7 +284,6 @@ import Clickable from '@site/static/usage/v8/item/clickable/index.md'; - ## Detail Arrows By default [clickable items](#clickable-items) will display a right arrow icon on `ios` mode. To hide the right arrow icon on clickable elements, set the `detail` property to `false`. To show the right arrow icon on an item that doesn't display it naturally, set the `detail` property to `true`. @@ -178,7 +292,6 @@ import DetailArrows from '@site/static/usage/v8/item/detail-arrows/index.md'; - - ## Item Lines Items show an inset bottom border by default. The border has padding on the left and does not appear under any content that is slotted in the `"start"` slot. The `lines` property can be modified to `"full"` or `"none"` which will show a full width border or no border, respectively. @@ -250,6 +362,7 @@ The following guidelines will help ensure your list items are easy to understand ### Keyboard Interactions An `` has the following keyboard interactions when any of these conditions are met: + - The `button` property is set to `"true"`, rendering a native `