Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] form control & button documentation update (#544)
* [form-input] documentation update * [form-select] documentation update * [form-file] Documentation update * [form-radio] Documentation update * [form-checkbox] Documentation update * [form] Documentation * [form-fieldset] documentation update * [button] Documentation update
- Loading branch information
1 parent
acb13b2
commit 5fbc617
Showing
11 changed files
with
252 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,51 @@ | ||
# Buttons | ||
|
||
> Use Bootstrap’s custom button styles for actions in forms, dialogs, and more. | ||
> Use Bootstrap’s custom `b-button` component for actions in forms, dialogs, and more. | ||
Includes support for a handful of contextual variations, sizes, states, and more. | ||
|
||
The `b-buton` component generally renders a `<button>` element. However, you can also | ||
render a an `<a>` element by proding an `href` prop vale. You man also generate | ||
`vue-router` `<router-link>` when providing a value for the `to` prop (`vue-router` | ||
is required). | ||
|
||
### Button Sizes | ||
Fancy larger or smaller buttons? Specify `lg` or `sm` via the `size` prop. | ||
|
||
Create block level buttons — those that span the full width of a parent — by | ||
setting the `block` prop. | ||
|
||
### Button contextual variants | ||
Use the `variant` prop to generate the various bootstrap contextual button variants. | ||
|
||
By default `b-button` will render with the `secondary` variant. | ||
|
||
#### Solid color variants: | ||
`primary`, `secondary`, `success`, `warning`, and `danger`. | ||
|
||
#### Outline color variants: | ||
In need of a button, but not the hefty background colors they bring? Use the | ||
`outline-*` variants to remove all background images and colors on any `b-button` | ||
|
||
`outline-primary`, `outline-secondary`, `outline-success`, `outline-warning`, | ||
and `outline-danger`. | ||
|
||
#### Link variant: | ||
Variant `link` will reder a button with the appearance of a link while maintaning the | ||
default passing and size of a button. | ||
|
||
### Disabled state | ||
Set the `disabled` prop to disable button default funtionality. `disabled` also | ||
works with buttons rednered as `<a>` elements and `router-link` | ||
|
||
### Button type | ||
When neither `href` nor `to` props are provided, `b-button` renders an html `<button>` | ||
element. You cn specify the button's type by setting the prop `type` to `button`, | ||
`submit` or `reset`. The default type is `button`. | ||
|
||
### Router links | ||
Refer to [`vue-router`](https://router.vuejs.org/) docs for the various router-link related props. | ||
|
||
Note the `tag`attribute for `router-link` is refered to as `router-tag` in `bootstrap-vue` | ||
|
||
### Alias | ||
`<b-button>` can also be used by its shorter alias `<b-btn>` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,19 @@ | ||
# Forms Checkbox | ||
# Form Checkbox Input | ||
|
||
> For cross browser consistency, `b-form-checkbox` uses Bottstrap's custom | ||
checkbox input to replace the browser default checkbox input. It is built on top of | ||
semantic and accessible markup, so it is a solid replacement for the default checkbox input. | ||
|
||
### Value | ||
By default, the checkbox value will be `true` when checked and `false` when unchecked. | ||
You can customize the checked and unchecked values by specifying the `value` and `unchecked-value` | ||
properties. | ||
|
||
`v-model` binds to the `checked` property. When you have multiple checkboxes that bind to a | ||
single data state variable, provide an array reference `[]` to your `v-model`. | ||
|
||
### Control sizing | ||
Set heights using thw `size` prop to `sm` or `lg` for small or large respectively. | ||
|
||
### Non custom check inputs | ||
You can have `b-form-checkbox` render a browser native chechbox input by setting the `plain` prop. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,41 @@ | ||
# Form fieldsets | ||
# Form fieldset (Form group) | ||
|
||
> The `b-form=fieldset` component is the easiest way to add some structure to forms. Its | ||
purpose is to provide a label and control pairing, help text and feedback text, as well | ||
as contextual state visual feedback | ||
|
||
### Options | ||
|
||
#### Label: | ||
The content of the generted `<label>` element (html supported). | ||
You may optionally visually hide the label by setting the prop `label-sr-only`. | ||
|
||
By default, the label apepars above the input element, but you may optionallu set | ||
the prop `horizontal` to place the label on the same line and control the width | ||
of the label by setting `label-size` to the number of columns (default of `3`). | ||
`label-size` has no effect if the layout is not `horizontal` | ||
|
||
The label may also optionally be alligned `left`, `center` or `right` by setting | ||
the respective value via the prop `label-text-align`. Alignment has no effect if | ||
`label-sr-only` is set. | ||
|
||
#### Description: | ||
Optional descriptive text which is always shown with the `.text-muted` class (html supported). | ||
|
||
#### Feedback: | ||
Optional text to provide textual state feedback (html supported). | ||
|
||
#### Contextual visual state: | ||
Optional contextual visual feedback state of `danger`, `warning` or `success`. | ||
You should always provide `feedback` content to assit users using assistive technologies. | ||
|
||
### Accessibility | ||
To enable auto-generateion of `aria-*` attributes, you must supply a unique `id` | ||
prop to `b-form-fieldset`. | ||
|
||
To automatically associate the label to the first input element, you must provide | ||
a unique `id` prop on the input component. You may optionally specify which containing | ||
input component the label is for by setting the `b-form-fieldset` prop `for` to the | ||
id string of the input. | ||
|
||
It is highly recommended that you provide a unique `id` prop on your input element. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,9 +1,41 @@ | ||
# Forms Radio | ||
# Form Radio Input | ||
|
||
> For even more customization and cross browser consistency, | ||
use our completely custom form elements to replace the browser defaults. | ||
They’re built on top of semantic and accessible markup, so they’re solid replacements for any default form control. | ||
> For cross browser consistency, `b-form-radio` uses Bottstrap's custom | ||
radio input to replace the browser default radio input. It is built on top of | ||
semantic and accessible markup, so it is a solid replacement for the default radio input. | ||
|
||
**options** | ||
### Options | ||
|
||
Please see options in [`<b-form-select>`](./form-select) docs for details on passing options | ||
to `b-form-radio` | ||
|
||
### Control sizing | ||
Set heights using thw `size` prop to `sm` or `lg` for small or large respectively. | ||
|
||
### Contextual States | ||
Bootstrap includes validation styles for danger, warning, and success states on most form controls. | ||
|
||
Generally speaking, you’ll want to use a particular state for specific types of feedback: | ||
- `danger` is great for when there’s a blocking or required field. A user must fill in | ||
this field properly to submit the form. | ||
- `warning` works well for input values that are in progress, like password strength, or | ||
soft validation before a user attempts to submit a form. | ||
- `success` is ideal for situations when you have per-field validation throughout a form | ||
and want to encourage a user through the rest of the fields. | ||
|
||
To apply one of the contextual steates on `b-form-radio`, set the `state` prop | ||
to `danger`, `warning`, or `success`. | ||
|
||
#### Conveying contextual validation state to assistive technologies and colorblind users: | ||
Using these contextual states to denote the state of a form control only provides | ||
a visual, color-based indication, which will not be conveyed to users of assistive | ||
technologies - such as screen readers - or to colorblind users. | ||
|
||
Ensure that an alternative indication of state is also provided. For instance, you | ||
could include a hint about state in the form control's `<label>` text itself, or by | ||
providing an additional help text block. Specifically for assistive technologies, | ||
invalid form controls can also be assigned an `aria-invalid="true"` attribute. | ||
|
||
### Non custom radio inputs | ||
You can have `b-form-radio` render a browser native radio input by setting the `plain` prop. | ||
|
||
Please see options in [`<form-select>`](./form-select) docs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
# Form | ||
|
||
> Bootstrap form component that optionally supports inline form styles | ||
### Inline form | ||
Set the `inline` property to generate a Bootstrap inline form. | ||
|
||
### Related components | ||
See also: | ||
- [`<b-form-input>`](./form-input) Textual and text-like inputs | ||
- [`<b-form-select>`](./form-select) Select input | ||
- [`<b-form-radio>`](./form-radio) Radio Input groups | ||
- [`<b-form-checkbox>`](./form-checkbox) Checkbox Input | ||
- [`<b-form-file>`](./form-file) File Input | ||
- [`<b-form-fieldset>`](./form-fieldset) Form input wrapper to gernerate form-groups that support labels, help text and feedback | ||
- [`<b-button>`](./button) Buttons | ||
- [`<b-input-group>`](./inputgroup) Form inputs with add-ons | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
import meta from './meta.json'; | ||
import readme from './README.md'; | ||
|
||
export default {meta, readme}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
{ | ||
"title": "Form", | ||
"component": "bForm" | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters