From c747f1e2940cbf61bbb0e3deb8d0cb7231c7becb Mon Sep 17 00:00:00 2001
From: Brandy Carney <brandy@ionic.io>
Date: Fri, 22 Dec 2017 11:44:55 -0500
Subject: [PATCH] docs(select): add docs for select and add to breaking changes

---
 BREAKING.md                                   | 36 +++++++++
 .../src/components/select-popover/readme.md   | 30 ++++++++
 packages/core/src/components/select/readme.md | 75 +++++++++++++++++++
 3 files changed, 141 insertions(+)

diff --git a/BREAKING.md b/BREAKING.md
index 0061211fbe..ed7fbaa684 100644
--- a/BREAKING.md
+++ b/BREAKING.md
@@ -18,6 +18,7 @@ A list of the breaking changes introduced in Ionic Angular v4.
 - [Radio](#radio)
 - [Range](#range)
 - [Segment](#segment)
+- [Select](#select)
 - [Toolbar](#toolbar)
 - [Sass](#sass)
 
@@ -553,6 +554,41 @@ These have been renamed to the following:
 The markup hasn't changed for Segments, but now writing `<ion-segment-button>` will render a native button element inside of it.
 
 
+## Select
+
+The `selectOptions` property was renamed to `interfaceOptions` since it directly correlates with the `interface` property.
+
+**Old Usage Example:**
+
+```html
+<ion-select [selectOptions]="customOptions">
+  ...
+</ion-select>
+```
+
+```ts
+this.customOptions = {
+  title: 'Pizza Toppings',
+  subTitle: 'Select your toppings'
+};
+```
+
+**New Usage Example:**
+
+```html
+<ion-select [interfaceOptions]="customOptions">
+  ...
+</ion-select>
+```
+
+```ts
+this.customOptions = {
+  title: 'Pizza Toppings',
+  subTitle: 'Select your toppings'
+};
+```
+
+
 ## Toolbar
 
 ### Attributes Renamed
diff --git a/packages/core/src/components/select-popover/readme.md b/packages/core/src/components/select-popover/readme.md
index 70950226c9..823e09e0c4 100644
--- a/packages/core/src/components/select-popover/readme.md
+++ b/packages/core/src/components/select-popover/readme.md
@@ -7,18 +7,48 @@
 
 ## Properties
 
+#### message
+
+string
+
+
 #### options
 
 any
 
 
+#### subTitle
+
+string
+
+
+#### title
+
+string
+
+
 ## Attributes
 
+#### message
+
+string
+
+
 #### options
 
 any
 
 
+#### subTitle
+
+string
+
+
+#### title
+
+string
+
+
 
 ----------------------------------------------
 
diff --git a/packages/core/src/components/select/readme.md b/packages/core/src/components/select/readme.md
index 9644671989..a5e61cdb4e 100644
--- a/packages/core/src/components/select/readme.md
+++ b/packages/core/src/components/select/readme.md
@@ -1,5 +1,80 @@
 # ion-select
 
+The `<ion-select>` element is similar to a native `<select>` element, however, it is easier for users to sort through and select the preferred option or options. When a user taps the select component, a dialog appears with all of the options in a large, easy to select list.
+
+It should be used with child `ion-select-option` elements. If the child option is not given a `value` attribute then it will use its text as the value.
+
+If `value` is set on the `ion-select`, the selected option will be based on that value. Otherwise, the `selected` attribute can be used on the `ion-select-option` elements.
+
+## Interfaces
+
+By default, the `ion-select` uses the [AlertController API](../../alert/AlertController) to open up the overlay of options in an alert. The interface can be changed to use the [ActionSheetController API](../../action-sheet/ActionSheetController) or [PopoverController API](../../popover/PopoverController) by passing `action-sheet` or `popover`, respectively, to the `interface` property. Read on to the other sections for the limitations of the different interfaces.
+
+## Single Value: Radio Buttons
+
+The standard `ion-select` component allows the user to select only one option. When selecting only one option the alert interface presents users with a radio button styled list of options. The action sheet interface can only be used with a single value select. The `ion-select` component's value receives the value of the selected option's value.
+
+```html
+<ion-item>
+  <ion-label>Gender</ion-label>
+  <ion-select id="gender">
+    <ion-select-option value="f">Female</ion-select-option>
+    <ion-select-option value="m">Male</ion-select-option>
+  </ion-select>
+</ion-item>
+```
+
+### Multiple Value: Checkboxes
+
+By adding the `multiple="true"` attribute to `ion-select`, users are able to select multiple options. When multiple options can be selected, the alert overlay presents users with a checkbox styled list of options. The `ion-select` component's value receives an array of all the selected option values. In the example below, because each option is not given a `value`, it will use the option's text as the value.
+
+Note: the `action-sheet` and `popover` interfaces will not work with a multiple-value select.
+
+```html
+<ion-item>
+  <ion-label>Toppings</ion-label>
+  <ion-select id="toppings" multiple="true">
+    <ion-select-option>Bacon</ion-select-option>
+    <ion-select-option>Black Olives</ion-select-option>
+    <ion-select-option>Extra Cheese</ion-select-option>
+    <ion-select-option>Mushrooms</ion-select-option>
+    <ion-select-option>Pepperoni</ion-select-option>
+    <ion-select-option>Sausage</ion-select-option>
+  </ion-select>
+</ion-item>
+```
+
+## Select Buttons
+
+By default, the two buttons read `Cancel` and `OK`. Each button's text can be customized using the `cancelText` and `okText` attributes:
+
+```html
+<ion-select ok-text="Okay" cancel-text="Dismiss">
+  ...
+</ion-select>
+```
+
+The `action-sheet` and `popover` interfaces do not have an `OK` button, clicking on any of the options will automatically close the overlay and select that value. The `popover` interface does not have a `Cancel` button, clicking on the backdrop will close the overlay.
+
+## Interface Options
+
+Since `ion-select` uses the `Alert`, `Action Sheet` and `Popover` interfaces, options can be passed to these components through the `interfaceOptions` property. This can be used to pass a custom title, subTitle, css class, and more. See the [AlertController API docs](../../alert/AlertController/#create), [ActionSheetController API docs](../../action-sheet/ActionSheetController/#create), and [PopoverController API docs](../../popover/PopoverController/#create) for the properties that each interface accepts.
+
+For example, to change the `title` and `subTitle` of the overlay, pass it into `interfaceOptions`.
+
+```html
+<ion-select id="customSelect">
+  ...
+</ion-select>
+```
+
+```javascript
+var customSelect = document.getElementById('customSelect');
+customSelect.interfaceOptions = {
+  title: 'Pizza Toppings',
+  subTitle: 'Select your toppings'
+};
+```
 
 
 <!-- Auto Generated Below -->