javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-11-10 00:27:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(overlays): add documentation on customization in scoped overlays (#21283)

Browse Source 
- improves the documentation on customizing scoped overlays using cssClass and/or CSS variables
- includes a section in the Angular usage with information on where the CSS needs to be styled (globally) in order to work for an overlay
This commit is contained in:
Brandy Carney
2020-05-13 11:54:11 -04:00
committed by GitHub
parent 687122127c
commit 898401a7e0
29 changed files with 358 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
core/src/components/action-sheet/readme.md
View File

@ -6,6 +6,34 @@ An Action Sheet is a dialog that displays a set of options. It appears on top of
A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role.
### Customization
Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
```css
/* DOES NOT WORK - not specific enough */
.action-sheet-group {
background: #e5e5e5;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .action-sheet-group {
background: #e5e5e5;
}
```
Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Action Sheet without needing to target individual elements:
```css
.my-custom-class {
--background: #e5e5e5;
}
```
> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
<!-- Auto Generated Below -->
@ -30,6 +58,7 @@ export class ActionSheetExample {
async presentActionSheet() {
const actionSheet = await this.actionSheetController.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [{
text: 'Delete',
role: 'destructive',
@ -71,14 +100,19 @@ export class ActionSheetExample {
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Action Sheet can be presented from within a page, the `ion-action-sheet` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
### Javascript
```javascript
async function presentActionSheet() {
const actionSheet = document.createElement('ion-action-sheet');
actionSheet.header = "Albums";
actionSheet.header = 'Albums';
actionSheet.cssClass = 'my-custom-class';
actionSheet.buttons = [{
text: 'Delete',
role: 'destructive',
@ -120,21 +154,23 @@ async function presentActionSheet() {
### React
```typescript
```tsx
import React, { useState } from 'react';
import { IonActionSheet, IonContent, IonButton } from '@ionic/react';
import { trash, share, caretForwardCircle, heart, close } from 'ionicons/icons';
export const ActionSheetExample: React.FC = () => {
const [showActionSheet, setShowActionSheet] = useState(false);
return (
<IonContent>
<IonButton onClick={() => setShowActionSheet(true)} expand="block">Show Action Sheet</IonButton>
<IonButton onClick={() => setShowActionSheet(true)} expand="block">
Show Action Sheet
</IonButton>
<IonActionSheet
isOpen={showActionSheet}
onDidDismiss={() => setShowActionSheet(false)}
cssClass='my-custom-class'
buttons={[{
text: 'Delete',
role: 'destructive',
@ -171,11 +207,8 @@ export const ActionSheetExample: React.FC = () => {
>
</IonActionSheet>
</IonContent>
);
}
```
@ -194,6 +227,7 @@ export class ActionSheetExample {
async presentActionSheet() {
const actionSheet = await actionSheetController.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [{
text: 'Delete',
role: 'destructive',
@ -258,6 +292,7 @@ export default {
return this.$ionic.actionSheetController
.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [
{
text: 'Delete',

6
core/src/components/action-sheet/usage/angular.md
View File

@ -14,6 +14,7 @@ export class ActionSheetExample {
async presentActionSheet() {
const actionSheet = await this.actionSheetController.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [{
text: 'Delete',
role: 'destructive',
@ -53,3 +54,8 @@ export class ActionSheetExample {
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Action Sheet can be presented from within a page, the `ion-action-sheet` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

4
core/src/components/action-sheet/usage/javascript.md
View File

@ -1,9 +1,9 @@
```javascript
async function presentActionSheet() {
const actionSheet = document.createElement('ion-action-sheet');
actionSheet.header = "Albums";
actionSheet.header = 'Albums';
actionSheet.cssClass = 'my-custom-class';
actionSheet.buttons = [{
text: 'Delete',
role: 'destructive',

11
core/src/components/action-sheet/usage/react.md
View File

@ -1,18 +1,20 @@
```typescript
```tsx
import React, { useState } from 'react';
import { IonActionSheet, IonContent, IonButton } from '@ionic/react';
import { trash, share, caretForwardCircle, heart, close } from 'ionicons/icons';
export const ActionSheetExample: React.FC = () => {
const [showActionSheet, setShowActionSheet] = useState(false);
return (
<IonContent>
<IonButton onClick={() => setShowActionSheet(true)} expand="block">Show Action Sheet</IonButton>
<IonButton onClick={() => setShowActionSheet(true)} expand="block">
Show Action Sheet
</IonButton>
<IonActionSheet
isOpen={showActionSheet}
onDidDismiss={() => setShowActionSheet(false)}
cssClass='my-custom-class'
buttons={[{
text: 'Delete',
role: 'destructive',
@ -49,9 +51,6 @@ export const ActionSheetExample: React.FC = () => {
>
</IonActionSheet>
</IonContent>
);
}
```

1
core/src/components/action-sheet/usage/stencil.md
View File

@ -11,6 +11,7 @@ export class ActionSheetExample {
async presentActionSheet() {
const actionSheet = await actionSheetController.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [{
text: 'Delete',
role: 'destructive',

1
core/src/components/action-sheet/usage/vue.md
View File

@ -12,6 +12,7 @@ export default {
return this.$ionic.actionSheetController
.create({
header: 'Albums',
cssClass: 'my-custom-class',
buttons: [
{
text: 'Delete',

64
core/src/components/alert/readme.md
View File

@ -13,6 +13,34 @@ Optionally, a `role` property can be added to a button, such as `cancel`. If a `
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.
### Customization
Alert uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
```css
/* DOES NOT WORK - not specific enough */
.alert-wrapper {
background: #e5e5e5;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .alert-wrapper {
background: #e5e5e5;
}
```
Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Alert without needing to target individual elements:
```css
.my-custom-class {
--background: #e5e5e5;
}
```
> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
<!-- Auto Generated Below -->
@ -36,6 +64,7 @@ export class AlertExample {
async presentAlert() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -47,6 +76,7 @@ export class AlertExample {
async presentAlertMultipleButtons() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -58,6 +88,7 @@ export class AlertExample {
async presentAlertConfirm() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -82,6 +113,7 @@ export class AlertExample {
async presentAlertPrompt() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -154,6 +186,7 @@ export class AlertExample {
async presentAlertRadio() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -216,6 +249,7 @@ export class AlertExample {
async presentAlertCheckbox() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{
@ -280,16 +314,21 @@ export class AlertExample {
await alert.present();
}
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Alert can be presented from within a page, the `ion-alert` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
### Javascript
```javascript
function presentAlert() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Alert';
alert.subHeader = 'Subtitle';
alert.message = 'This is an alert message.';
@ -301,6 +340,7 @@ function presentAlert() {
function presentAlertMultipleButtons() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Alert';
alert.subHeader = 'Subtitle';
alert.message = 'This is an alert message.';
@ -312,6 +352,7 @@ function presentAlertMultipleButtons() {
function presentAlertConfirm() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Confirm!';
alert.message = 'Message <strong>text</strong>!!!';
alert.buttons = [
@ -336,6 +377,7 @@ function presentAlertConfirm() {
function presentAlertPrompt() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Prompt!';
alert.inputs = [
{
@ -405,6 +447,7 @@ function presentAlertPrompt() {
function presentAlertRadio() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Radio';
alert.inputs = [
{
@ -460,6 +503,7 @@ function presentAlertRadio() {
function presentAlertCheckbox() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Checkbox';
alert.inputs = [
{
@ -547,6 +591,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert1}
onDidDismiss={() => setShowAlert1(false)}
cssClass='my-custom-class'
header={'Alert'}
subHeader={'Subtitle'}
message={'This is an alert message.'}
@ -556,6 +601,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert2}
onDidDismiss={() => setShowAlert2(false)}
cssClass='my-custom-class'
header={'Alert'}
subHeader={'Subtitle'}
message={'This is an alert message.'}
@ -565,6 +611,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert3}
onDidDismiss={() => setShowAlert3(false)}
cssClass='my-custom-class'
header={'Confirm!'}
message={'Message <strong>text</strong>!!!'}
buttons={[
@ -588,6 +635,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert4}
onDidDismiss={() => setShowAlert4(false)}
cssClass='my-custom-class'
header={'Prompt!'}
inputs={[
{
@ -652,6 +700,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert5}
onDidDismiss={() => setShowAlert5(false)}
cssClass='my-custom-class'
header={'Radio'}
inputs={[
{
@ -713,6 +762,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert6}
onDidDismiss={() => setShowAlert6(false)}
cssClass='my-custom-class'
header={'Checkbox'}
inputs={[
{
@ -793,6 +843,7 @@ import { alertController } from '@ionic/core';
export class AlertExample {
async presentAlert() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -804,6 +855,7 @@ export class AlertExample {
async presentAlertMultipleButtons() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -815,6 +867,7 @@ export class AlertExample {
async presentAlertConfirm() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -839,6 +892,7 @@ export class AlertExample {
async presentAlertPrompt() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -911,6 +965,7 @@ export class AlertExample {
async presentAlertRadio() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -973,6 +1028,7 @@ export class AlertExample {
async presentAlertCheckbox() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{
@ -1075,6 +1131,7 @@ export default {
presentAlert() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -1086,6 +1143,7 @@ export default {
presentAlertMultipleButtons() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -1097,6 +1155,7 @@ export default {
presentAlertConfirm() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -1122,6 +1181,7 @@ export default {
presentAlertPrompt() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -1185,6 +1245,7 @@ export default {
presentAlertRadio() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -1242,6 +1303,7 @@ export default {
presentAlertCheckbox() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{

12
core/src/components/alert/usage/angular.md
View File

@ -13,6 +13,7 @@ export class AlertExample {
async presentAlert() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -24,6 +25,7 @@ export class AlertExample {
async presentAlertMultipleButtons() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -35,6 +37,7 @@ export class AlertExample {
async presentAlertConfirm() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -59,6 +62,7 @@ export class AlertExample {
async presentAlertPrompt() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -131,6 +135,7 @@ export class AlertExample {
async presentAlertRadio() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -193,6 +198,7 @@ export class AlertExample {
async presentAlertCheckbox() {
const alert = await this.alertController.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{
@ -257,6 +263,10 @@ export class AlertExample {
await alert.present();
}
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Alert can be presented from within a page, the `ion-alert` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

6
core/src/components/alert/usage/javascript.md
View File

@ -1,6 +1,7 @@
```javascript
function presentAlert() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Alert';
alert.subHeader = 'Subtitle';
alert.message = 'This is an alert message.';
@ -12,6 +13,7 @@ function presentAlert() {
function presentAlertMultipleButtons() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Alert';
alert.subHeader = 'Subtitle';
alert.message = 'This is an alert message.';
@ -23,6 +25,7 @@ function presentAlertMultipleButtons() {
function presentAlertConfirm() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Confirm!';
alert.message = 'Message <strong>text</strong>!!!';
alert.buttons = [
@ -47,6 +50,7 @@ function presentAlertConfirm() {
function presentAlertPrompt() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Prompt!';
alert.inputs = [
{
@ -116,6 +120,7 @@ function presentAlertPrompt() {
function presentAlertRadio() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Radio';
alert.inputs = [
{
@ -171,6 +176,7 @@ function presentAlertRadio() {
function presentAlertCheckbox() {
const alert = document.createElement('ion-alert');
alert.cssClass = 'my-custom-class';
alert.header = 'Checkbox';
alert.inputs = [
{

6
core/src/components/alert/usage/react.md
View File

@ -22,6 +22,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert1}
onDidDismiss={() => setShowAlert1(false)}
cssClass='my-custom-class'
header={'Alert'}
subHeader={'Subtitle'}
message={'This is an alert message.'}
@ -31,6 +32,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert2}
onDidDismiss={() => setShowAlert2(false)}
cssClass='my-custom-class'
header={'Alert'}
subHeader={'Subtitle'}
message={'This is an alert message.'}
@ -40,6 +42,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert3}
onDidDismiss={() => setShowAlert3(false)}
cssClass='my-custom-class'
header={'Confirm!'}
message={'Message <strong>text</strong>!!!'}
buttons={[
@ -63,6 +66,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert4}
onDidDismiss={() => setShowAlert4(false)}
cssClass='my-custom-class'
header={'Prompt!'}
inputs={[
{
@ -127,6 +131,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert5}
onDidDismiss={() => setShowAlert5(false)}
cssClass='my-custom-class'
header={'Radio'}
inputs={[
{
@ -188,6 +193,7 @@ export const AlertExample: React.FC = () => {
<IonAlert
isOpen={showAlert6}
onDidDismiss={() => setShowAlert6(false)}
cssClass='my-custom-class'
header={'Checkbox'}
inputs={[
{

6
core/src/components/alert/usage/stencil.md
View File

@ -10,6 +10,7 @@ import { alertController } from '@ionic/core';
export class AlertExample {
async presentAlert() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -21,6 +22,7 @@ export class AlertExample {
async presentAlertMultipleButtons() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -32,6 +34,7 @@ export class AlertExample {
async presentAlertConfirm() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -56,6 +59,7 @@ export class AlertExample {
async presentAlertPrompt() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -128,6 +132,7 @@ export class AlertExample {
async presentAlertRadio() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -190,6 +195,7 @@ export class AlertExample {
async presentAlertCheckbox() {
const alert = await alertController.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{

6
core/src/components/alert/usage/vue.md
View File

@ -16,6 +16,7 @@ export default {
presentAlert() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -27,6 +28,7 @@ export default {
presentAlertMultipleButtons() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Alert',
subHeader: 'Subtitle',
message: 'This is an alert message.',
@ -38,6 +40,7 @@ export default {
presentAlertConfirm() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Confirm!',
message: 'Message <strong>text</strong>!!!',
buttons: [
@ -63,6 +66,7 @@ export default {
presentAlertPrompt() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Prompt!',
inputs: [
{
@ -126,6 +130,7 @@ export default {
presentAlertRadio() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Radio',
inputs: [
{
@ -183,6 +188,7 @@ export default {
presentAlertCheckbox() {
return this.$ionic.alertController
.create({
cssClass: 'my-custom-class',
header: 'Checkbox',
inputs: [
{

46
core/src/components/loading/readme.md
View File

@ -6,6 +6,37 @@ An overlay that can be used to indicate activity while blocking user interaction
The loading indicator can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the `duration` of the loading options. To dismiss the loading indicator after creation, call the `dismiss()` method on the loading instance. The `onDidDismiss` function can be called to perform an action after the loading indicator is dismissed.
### Customization
Loading uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
```css
/* DOES NOT WORK - not specific enough */
ion-loading {
color: green;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class {
color: green;
}
```
Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Loading without needing to target individual elements:
```css
.my-custom-class {
--background: #222;
--spinner-color: #fff;
color: #fff;
}
```
> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
<!-- Auto Generated Below -->
@ -28,6 +59,7 @@ export class LoadingExample {
async presentLoading() {
const loading = await this.loadingController.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: 2000
});
@ -39,6 +71,7 @@ export class LoadingExample {
async presentLoadingWithOptions() {
const loading = await this.loadingController.create({
cssClass: 'my-custom-class',
spinner: null,
duration: 5000,
message: 'Click the backdrop to dismiss early...',
@ -55,11 +88,18 @@ export class LoadingExample {
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Loading can be presented from within a page, the `ion-loading` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
### Javascript
```javascript
async function presentLoading() {
const loading = document.createElement('ion-loading');
loading.cssClass = 'my-custom-class';
loading.message = 'Please wait...';
loading.duration = 2000;
@ -73,6 +113,7 @@ async function presentLoading() {
async function presentLoadingWithOptions() {
const loading = document.createElement('ion-loading');
loading.cssClass = 'my-custom-class';
loading.spinner = null;
loading.duration = 5000;
loading.message = 'Click the backdrop to dismiss early...';
@ -106,6 +147,7 @@ export const LoadingExample: React.FC = () => {
<IonContent>
<IonButton onClick={() => setShowLoading(true)}>Show Loading</IonButton>
<IonLoading
cssClass='my-custom-class'
isOpen={showLoading}
onDidDismiss={() => setShowLoading(false)}
message={'Please wait...'}
@ -131,6 +173,7 @@ import { loadingController } from '@ionic/core';
export class LoadingExample {
async presentLoading() {
const loading = await loadingController.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: 2000
});
@ -142,6 +185,7 @@ export class LoadingExample {
async presentLoadingWithOptions() {
const loading = await loadingController.create({
cssClass: 'my-custom-class',
spinner: null,
duration: 5000,
message: 'Click the backdrop to dismiss early...',
@ -187,6 +231,7 @@ export default {
presentLoading() {
return this.$ionic.loadingController
.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: this.timeout,
})
@ -200,6 +245,7 @@ export default {
presentLoadingWithOptions() {
return this.$ionic.loadingController
.create({
cssClass: 'my-custom-class',
spinner: null,
duration: this.timeout,
message: 'Click the backdrop to dismiss early...',

7
core/src/components/loading/usage/angular.md
View File

@ -12,6 +12,7 @@ export class LoadingExample {
async presentLoading() {
const loading = await this.loadingController.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: 2000
});
@ -23,6 +24,7 @@ export class LoadingExample {
async presentLoadingWithOptions() {
const loading = await this.loadingController.create({
cssClass: 'my-custom-class',
spinner: null,
duration: 5000,
message: 'Click the backdrop to dismiss early...',
@ -37,3 +39,8 @@ export class LoadingExample {
}
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Loading can be presented from within a page, the `ion-loading` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

3
core/src/components/loading/usage/javascript.md
View File

@ -1,6 +1,8 @@
```javascript
async function presentLoading() {
const loading = document.createElement('ion-loading');
loading.cssClass = 'my-custom-class';
loading.message = 'Please wait...';
loading.duration = 2000;
@ -14,6 +16,7 @@ async function presentLoading() {
async function presentLoadingWithOptions() {
const loading = document.createElement('ion-loading');
loading.cssClass = 'my-custom-class';
loading.spinner = null;
loading.duration = 5000;
loading.message = 'Click the backdrop to dismiss early...';

1
core/src/components/loading/usage/react.md
View File

@ -13,6 +13,7 @@ export const LoadingExample: React.FC = () => {
<IonContent>
<IonButton onClick={() => setShowLoading(true)}>Show Loading</IonButton>
<IonLoading
cssClass='my-custom-class'
isOpen={showLoading}
onDidDismiss={() => setShowLoading(false)}
message={'Please wait...'}

2
core/src/components/loading/usage/stencil.md
View File

@ -10,6 +10,7 @@ import { loadingController } from '@ionic/core';
export class LoadingExample {
async presentLoading() {
const loading = await loadingController.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: 2000
});
@ -21,6 +22,7 @@ export class LoadingExample {
async presentLoadingWithOptions() {
const loading = await loadingController.create({
cssClass: 'my-custom-class',
spinner: null,
duration: 5000,
message: 'Click the backdrop to dismiss early...',

2
core/src/components/loading/usage/vue.md
View File

@ -16,6 +16,7 @@ export default {
presentLoading() {
return this.$ionic.loadingController
.create({
cssClass: 'my-custom-class',
message: 'Please wait...',
duration: this.timeout,
})
@ -29,6 +30,7 @@ export default {
presentLoadingWithOptions() {
return this.$ionic.loadingController
.create({
cssClass: 'my-custom-class',
spinner: null,
duration: this.timeout,
message: 'Click the backdrop to dismiss early...',

54
core/src/components/modal/readme.md
View File

@ -6,6 +6,33 @@ A Modal is a dialog that appears on top of the app's content, and must be dismis
The modal can be dismissed after creation by calling the `dismiss()` method on the modal controller. The `onDidDismiss` function can be called to perform an action after the modal is dismissed.
### Customization
Modal uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
```css
/* DOES NOT WORK - not specific enough */
.modal-wrapper {
background: #222;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .modal-wrapper {
background: #222;
}
```
Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Modal without needing to target individual elements:
```css
.my-custom-class {
--background: #222;
}
```
> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
<!-- Auto Generated Below -->
@ -31,7 +58,8 @@ export class ModalExample {
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage
component: ModalPage,
cssClass: 'my-custom-class'
});
return await modal.present();
}
@ -60,6 +88,7 @@ The previous example can be written to include data:
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
componentProps: {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -154,6 +183,7 @@ constructor(private routerOutlet: IonRouterOutlet) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: this.routerOutlet.nativeEl
});
@ -171,6 +201,7 @@ constructor(private modalCtrl: ModalController) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: await this.modalCtrl.getTop() // Get the top-most ion-modal
});
@ -179,6 +210,11 @@ async presentModal() {
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Modal can be presented from within a page, the `ion-modal` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
### Javascript
```javascript
@ -205,6 +241,7 @@ function presentModal() {
// create the modal with the `modal-page` component
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
// present the modal
document.body.appendChild(modalElement);
@ -219,6 +256,7 @@ During creation of a modal, data can be passed in through the `componentProps`.
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.componentProps = {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -267,6 +305,7 @@ Modals in iOS mode have the ability to be presented in a card-style and swiped t
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.swipeToClose = true;
modalElement.presentingElement = document.querySelector('ion-nav');
```
@ -276,6 +315,7 @@ In most scenarios, using the `ion-nav` element as the `presentingElement` is fin
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.swipeToClose = true;
modalElement.presentingElement = await modalController.getTop(); // Get the top-most ion-modal
```
@ -292,7 +332,7 @@ export const ModalExample: React.FC = () => {
return (
<IonContent>
<IonModal isOpen={showModal}>
<IonModal isOpen={showModal} cssClass='my-custom-class'>
<p>This is modal content</p>
<IonButton onClick={() => setShowModal(false)}>Close Modal</IonButton>
</IonModal>
@ -309,6 +349,7 @@ Modals in iOS mode have the ability to be presented in a card-style and swiped t
```tsx
<IonModal
isOpen={showModal}
cssClass='my-custom-class'
swipeToClose={true}
presentingElement={pageRef.current}
onDidDismiss={() => setShowModal(false)}>
@ -323,6 +364,7 @@ In most scenarios, setting a ref on `IonPage` and passing that ref's `current` v
<IonModal
ref={firstModalRef}
isOpen={showModal}
cssClass='my-custom-class'
swipeToClose={true}
presentingElement={pageRef.current}
onDidDismiss={() => setShowModal(false)}>
@ -332,6 +374,7 @@ In most scenarios, setting a ref on `IonPage` and passing that ref's `current` v
</IonModal>
<IonModal
isOpen={show2ndModal}
cssClass='my-custom-class'
presentingElement={firstModalRef.current}
onDidDismiss={() => setShow2ndModal(false)}>
<p>This is more modal content</p>
@ -354,7 +397,8 @@ import { modalController } from '@ionic/core';
export class ModalExample {
async presentModal() {
const modal = await modalController.create({
component: 'page-modal'
component: 'page-modal',
cssClass: 'my-custom-class'
});
await modal.present();
}
@ -396,6 +440,7 @@ The previous example can be written to include data:
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
componentProps: {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -466,6 +511,7 @@ export class ModalExample {
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: this.el.closest('ion-router-outlet'),
});
@ -481,6 +527,7 @@ In most scenarios, using the `ion-router-outlet` element as the `presentingEleme
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: await modalController.getTop() // Get the top-most ion-modal
});
@ -538,6 +585,7 @@ export default {
return this.$ionic.modalController
.create({
component: Modal,
cssClass: 'my-custom-class',
componentProps: {
data: {
content: 'New Content',

11
core/src/components/modal/usage/angular.md
View File

@ -15,7 +15,8 @@ export class ModalExample {
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage
component: ModalPage,
cssClass: 'my-custom-class'
});
return await modal.present();
}
@ -44,6 +45,7 @@ The previous example can be written to include data:
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
componentProps: {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -138,6 +140,7 @@ constructor(private routerOutlet: IonRouterOutlet) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: this.routerOutlet.nativeEl
});
@ -155,9 +158,15 @@ constructor(private modalCtrl: ModalController) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: await this.modalCtrl.getTop() // Get the top-most ion-modal
});
return await modal.present();
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Modal can be presented from within a page, the `ion-modal` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

4
core/src/components/modal/usage/javascript.md
View File

@ -23,6 +23,7 @@ function presentModal() {
// create the modal with the `modal-page` component
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
// present the modal
document.body.appendChild(modalElement);
@ -37,6 +38,7 @@ During creation of a modal, data can be passed in through the `componentProps`.
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.componentProps = {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -85,6 +87,7 @@ Modals in iOS mode have the ability to be presented in a card-style and swiped t
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.swipeToClose = true;
modalElement.presentingElement = document.querySelector('ion-nav');
```
@ -94,6 +97,7 @@ In most scenarios, using the `ion-nav` element as the `presentingElement` is fin
```javascript
const modalElement = document.createElement('ion-modal');
modalElement.component = 'modal-page';
modalElement.cssClass = 'my-custom-class';
modalElement.swipeToClose = true;
modalElement.presentingElement = await modalController.getTop(); // Get the top-most ion-modal
```

5
core/src/components/modal/usage/react.md
View File

@ -7,7 +7,7 @@ export const ModalExample: React.FC = () => {
return (
<IonContent>
<IonModal isOpen={showModal}>
<IonModal isOpen={showModal} cssClass='my-custom-class'>
<p>This is modal content</p>
<IonButton onClick={() => setShowModal(false)}>Close Modal</IonButton>
</IonModal>
@ -24,6 +24,7 @@ Modals in iOS mode have the ability to be presented in a card-style and swiped t
```tsx
<IonModal
isOpen={showModal}
cssClass='my-custom-class'
swipeToClose={true}
presentingElement={pageRef.current}
onDidDismiss={() => setShowModal(false)}>
@ -38,6 +39,7 @@ In most scenarios, setting a ref on `IonPage` and passing that ref's `current` v
<IonModal
ref={firstModalRef}
isOpen={showModal}
cssClass='my-custom-class'
swipeToClose={true}
presentingElement={pageRef.current}
onDidDismiss={() => setShowModal(false)}>
@ -47,6 +49,7 @@ In most scenarios, setting a ref on `IonPage` and passing that ref's `current` v
</IonModal>
<IonModal
isOpen={show2ndModal}
cssClass='my-custom-class'
presentingElement={firstModalRef.current}
onDidDismiss={() => setShow2ndModal(false)}>
<p>This is more modal content</p>

6
core/src/components/modal/usage/stencil.md
View File

@ -10,7 +10,8 @@ import { modalController } from '@ionic/core';
export class ModalExample {
async presentModal() {
const modal = await modalController.create({
component: 'page-modal'
component: 'page-modal',
cssClass: 'my-custom-class'
});
await modal.present();
}
@ -52,6 +53,7 @@ The previous example can be written to include data:
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
componentProps: {
'firstName': 'Douglas',
'lastName': 'Adams',
@ -122,6 +124,7 @@ export class ModalExample {
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: this.el.closest('ion-router-outlet'),
});
@ -137,6 +140,7 @@ In most scenarios, using the `ion-router-outlet` element as the `presentingEleme
async presentModal() {
const modal = await modalController.create({
component: 'page-modal',
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: await modalController.getTop() // Get the top-most ion-modal
});

1
core/src/components/modal/usage/vue.md
View File

@ -45,6 +45,7 @@ export default {
return this.$ionic.modalController
.create({
component: Modal,
cssClass: 'my-custom-class',
componentProps: {
data: {
content: 'New Content',

37
core/src/components/popover/readme.md
View File

@ -6,6 +6,34 @@ A Popover is a dialog that appears on top of the current page. It can be used fo
To present a popover, call the `present` method on a popover instance. In order to position the popover relative to the element clicked, a click event needs to be passed into the options of the the `present` method. If the event is not passed, the popover will be positioned in the center of the viewport.
### Customization
Popover uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
```css
/* DOES NOT WORK - not specific enough */
.popover-content {
background: #222;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .popover-content {
background: #222;
}
```
Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Popover without needing to target individual elements:
```css
.my-custom-class {
--background: #222;
}
```
> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
<!-- Auto Generated Below -->
@ -30,6 +58,7 @@ export class PopoverExample {
async presentPopover(ev: any) {
const popover = await this.popoverController.create({
component: PopoverComponent,
cssClass: 'my-custom-class',
event: ev,
translucent: true
});
@ -39,12 +68,18 @@ export class PopoverExample {
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Popover can be presented from within a page, the `ion-popover` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
### Javascript
```javascript
function presentPopover(ev) {
const popover = Object.assign(document.createElement('ion-popover'), {
component: 'popover-example-page',
cssClass: 'my-custom-class',
event: ev,
translucent: true
});
@ -67,6 +102,7 @@ export const PopoverExample: React.FC = () => {
<>
<IonPopover
isOpen={showPopover}
cssClass='my-custom-class'
onDidDismiss={e => setShowPopover(false)}
>
<p>This is popover content</p>
@ -93,6 +129,7 @@ export class PopoverExample {
async presentPopover(ev: any) {
const popover = await popoverController.create({
component: 'page-popover',
cssClass: 'my-custom-class',
event: ev,
translucent: true
});

6
core/src/components/popover/usage/angular.md
View File

@ -14,6 +14,7 @@ export class PopoverExample {
async presentPopover(ev: any) {
const popover = await this.popoverController.create({
component: PopoverComponent,
cssClass: 'my-custom-class',
event: ev,
translucent: true
});
@ -21,3 +22,8 @@ export class PopoverExample {
}
}
```
### Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Popover can be presented from within a page, the `ion-popover` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

1
core/src/components/popover/usage/javascript.md
View File

@ -2,6 +2,7 @@
function presentPopover(ev) {
const popover = Object.assign(document.createElement('ion-popover'), {
component: 'popover-example-page',
cssClass: 'my-custom-class',
event: ev,
translucent: true
});

1
core/src/components/popover/usage/react.md
View File

@ -9,6 +9,7 @@ export const PopoverExample: React.FC = () => {
<>
<IonPopover
isOpen={showPopover}
cssClass='my-custom-class'
onDidDismiss={e => setShowPopover(false)}
>
<p>This is popover content</p>

1
core/src/components/popover/usage/stencil.md
View File

@ -11,6 +11,7 @@ export class PopoverExample {
async presentPopover(ev: any) {
const popover = await popoverController.create({
component: 'page-popover',
cssClass: 'my-custom-class',
event: ev,
translucent: true
});