0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-12 00:08:59 +01:00
Bootstrap/site/docs/4.3/components/buttons.md

164 lines
7.8 KiB
Markdown
Raw Normal View History

2014-07-12 07:34:47 +02:00
---
layout: docs
2014-07-12 07:34:47 +02:00
title: Buttons
description: Use Bootstrap's custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more.
group: components
2017-05-28 08:01:14 +02:00
toc: true
2014-07-12 07:34:47 +02:00
---
2014-07-10 06:17:10 +02:00
## Examples
Bootstrap includes several predefined button styles, each serving its own semantic purpose, with a few extras thrown in for more control.
2014-07-10 06:17:10 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
{% for color in site.data.theme-colors %}
<button type="button" class="btn btn-{{ color.name }}">{{ color.name | capitalize }}</button>{% endfor %}
2014-03-17 03:03:53 +01:00
<button type="button" class="btn btn-link">Link</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
{% include callout-warning-color-assistive-technologies.md %}
Merge branch 'master' into v4 Conflicts: Gruntfile.js _config.yml dist/css/bootstrap-theme.css dist/css/bootstrap-theme.min.css dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/fonts/glyphicons-halflings-regular.eot dist/fonts/glyphicons-halflings-regular.svg dist/fonts/glyphicons-halflings-regular.ttf dist/fonts/glyphicons-halflings-regular.woff docs/_data/glyphicons.yml docs/_includes/components/alerts.html docs/_includes/components/badges.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/input-groups.html docs/_includes/components/labels.html docs/_includes/components/media.html docs/_includes/components/navbar.html docs/_includes/components/navs.html docs/_includes/components/pagination.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/css/buttons.html docs/_includes/css/forms.html docs/_includes/css/grid.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/css/responsive-utilities.html docs/_includes/css/sass.html docs/_includes/css/tables.html docs/_includes/css/type.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/browser-device-support.html docs/_includes/getting-started/community.html docs/_includes/getting-started/download.html docs/_includes/getting-started/examples.html docs/_includes/getting-started/whats-included.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/dropdowns.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/tabs.html docs/_includes/nav/components.html docs/_includes/nav/css.html docs/_includes/nav/javascript.html docs/_includes/nav/main.html docs/about.html docs/assets/css/docs.min.css docs/assets/js/customize.min.js docs/assets/js/raw-files.min.js docs/dist/css/bootstrap-theme.css docs/dist/css/bootstrap-theme.min.css docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/dist/fonts/glyphicons-halflings-regular.eot docs/dist/fonts/glyphicons-halflings-regular.svg docs/dist/fonts/glyphicons-halflings-regular.ttf docs/dist/fonts/glyphicons-halflings-regular.woff docs/examples/carousel/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/non-responsive/non-responsive.css docs/examples/sticky-footer-navbar/index.html docs/examples/theme/index.html fonts/glyphicons-halflings-regular.eot fonts/glyphicons-halflings-regular.svg fonts/glyphicons-halflings-regular.ttf fonts/glyphicons-halflings-regular.woff less/_carousel.less less/_forms.less less/glyphicons.less
2014-12-01 05:17:45 +01:00
## Button tags
2015-04-30 23:39:57 +02:00
The `.btn` classes are designed to be used with the `<button>` element. However, you can also use these classes on `<a>` or `<input>` elements (though some browsers may apply a slightly different rendering).
2015-04-30 23:39:57 +02:00
When using button classes on `<a>` elements that are used to trigger in-page functionality (like collapsing content), rather than linking to new pages or sections within the current page, these links should be given a `role="button"` to appropriately convey their purpose to assistive technologies such as screen readers.
Merge branch 'master' into v4 Conflicts: Gruntfile.js _config.yml dist/css/bootstrap-theme.css dist/css/bootstrap-theme.min.css dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/fonts/glyphicons-halflings-regular.eot dist/fonts/glyphicons-halflings-regular.svg dist/fonts/glyphicons-halflings-regular.ttf dist/fonts/glyphicons-halflings-regular.woff docs/_data/glyphicons.yml docs/_includes/components/alerts.html docs/_includes/components/badges.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/input-groups.html docs/_includes/components/labels.html docs/_includes/components/media.html docs/_includes/components/navbar.html docs/_includes/components/navs.html docs/_includes/components/pagination.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/css/buttons.html docs/_includes/css/forms.html docs/_includes/css/grid.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/css/responsive-utilities.html docs/_includes/css/sass.html docs/_includes/css/tables.html docs/_includes/css/type.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/browser-device-support.html docs/_includes/getting-started/community.html docs/_includes/getting-started/download.html docs/_includes/getting-started/examples.html docs/_includes/getting-started/whats-included.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/dropdowns.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/tabs.html docs/_includes/nav/components.html docs/_includes/nav/css.html docs/_includes/nav/javascript.html docs/_includes/nav/main.html docs/about.html docs/assets/css/docs.min.css docs/assets/js/customize.min.js docs/assets/js/raw-files.min.js docs/dist/css/bootstrap-theme.css docs/dist/css/bootstrap-theme.min.css docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/dist/fonts/glyphicons-halflings-regular.eot docs/dist/fonts/glyphicons-halflings-regular.svg docs/dist/fonts/glyphicons-halflings-regular.ttf docs/dist/fonts/glyphicons-halflings-regular.woff docs/examples/carousel/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/non-responsive/non-responsive.css docs/examples/sticky-footer-navbar/index.html docs/examples/theme/index.html fonts/glyphicons-halflings-regular.eot fonts/glyphicons-halflings-regular.svg fonts/glyphicons-halflings-regular.ttf fonts/glyphicons-halflings-regular.woff less/_carousel.less less/_forms.less less/glyphicons.less
2014-12-01 05:17:45 +01:00
2018-03-14 16:44:38 +01:00
{% capture example %}
2015-08-06 08:14:53 +02:00
<a class="btn btn-primary" href="#" role="button">Link</a>
<button class="btn btn-primary" type="submit">Button</button>
<input class="btn btn-primary" type="button" value="Input">
<input class="btn btn-primary" type="submit" value="Submit">
<input class="btn btn-primary" type="reset" value="Reset">
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
Merge branch 'master' into v4 Conflicts: Gruntfile.js _config.yml dist/css/bootstrap-theme.css dist/css/bootstrap-theme.min.css dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/fonts/glyphicons-halflings-regular.eot dist/fonts/glyphicons-halflings-regular.svg dist/fonts/glyphicons-halflings-regular.ttf dist/fonts/glyphicons-halflings-regular.woff docs/_data/glyphicons.yml docs/_includes/components/alerts.html docs/_includes/components/badges.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/input-groups.html docs/_includes/components/labels.html docs/_includes/components/media.html docs/_includes/components/navbar.html docs/_includes/components/navs.html docs/_includes/components/pagination.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/css/buttons.html docs/_includes/css/forms.html docs/_includes/css/grid.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/css/responsive-utilities.html docs/_includes/css/sass.html docs/_includes/css/tables.html docs/_includes/css/type.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/browser-device-support.html docs/_includes/getting-started/community.html docs/_includes/getting-started/download.html docs/_includes/getting-started/examples.html docs/_includes/getting-started/whats-included.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/dropdowns.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/tabs.html docs/_includes/nav/components.html docs/_includes/nav/css.html docs/_includes/nav/javascript.html docs/_includes/nav/main.html docs/about.html docs/assets/css/docs.min.css docs/assets/js/customize.min.js docs/assets/js/raw-files.min.js docs/dist/css/bootstrap-theme.css docs/dist/css/bootstrap-theme.min.css docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/dist/fonts/glyphicons-halflings-regular.eot docs/dist/fonts/glyphicons-halflings-regular.svg docs/dist/fonts/glyphicons-halflings-regular.ttf docs/dist/fonts/glyphicons-halflings-regular.woff docs/examples/carousel/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/non-responsive/non-responsive.css docs/examples/sticky-footer-navbar/index.html docs/examples/theme/index.html fonts/glyphicons-halflings-regular.eot fonts/glyphicons-halflings-regular.svg fonts/glyphicons-halflings-regular.ttf fonts/glyphicons-halflings-regular.woff less/_carousel.less less/_forms.less less/glyphicons.less
2014-12-01 05:17:45 +01:00
2015-08-10 07:48:48 +02:00
## Outline buttons
In need of a button, but not the hefty background colors they bring? Replace the default modifier classes with the `.btn-outline-*` ones to remove all background images and colors on any button.
2015-08-10 07:48:48 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
{% for color in site.data.theme-colors %}
<button type="button" class="btn btn-outline-{{ color.name }}">{{ color.name | capitalize }}</button>{% endfor %}
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2015-08-10 07:48:48 +02:00
2014-07-10 06:17:10 +02:00
## Sizes
2015-08-19 19:38:22 +02:00
Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes.
2014-07-10 06:17:10 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
2014-07-10 06:17:10 +02:00
<button type="button" class="btn btn-primary btn-lg">Large button</button>
<button type="button" class="btn btn-secondary btn-lg">Large button</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
2014-07-10 06:17:10 +02:00
<button type="button" class="btn btn-primary btn-sm">Small button</button>
<button type="button" class="btn btn-secondary btn-sm">Small button</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
Create block level buttons—those that span the full width of a parent—by adding `.btn-block`.
2018-03-14 16:44:38 +01:00
{% capture example %}
2014-03-17 03:03:53 +01:00
<button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button>
2014-07-09 02:14:14 +02:00
<button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
## Active state
Merge branch 'master' into v4 Conflicts: Gruntfile.js _config.yml dist/css/bootstrap-theme.css dist/css/bootstrap-theme.min.css dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/fonts/glyphicons-halflings-regular.eot dist/fonts/glyphicons-halflings-regular.svg dist/fonts/glyphicons-halflings-regular.ttf dist/fonts/glyphicons-halflings-regular.woff docs/_data/glyphicons.yml docs/_includes/components/alerts.html docs/_includes/components/badges.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/input-groups.html docs/_includes/components/labels.html docs/_includes/components/media.html docs/_includes/components/navbar.html docs/_includes/components/navs.html docs/_includes/components/pagination.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/css/buttons.html docs/_includes/css/forms.html docs/_includes/css/grid.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/css/responsive-utilities.html docs/_includes/css/sass.html docs/_includes/css/tables.html docs/_includes/css/type.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/browser-device-support.html docs/_includes/getting-started/community.html docs/_includes/getting-started/download.html docs/_includes/getting-started/examples.html docs/_includes/getting-started/whats-included.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/dropdowns.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/tabs.html docs/_includes/nav/components.html docs/_includes/nav/css.html docs/_includes/nav/javascript.html docs/_includes/nav/main.html docs/about.html docs/assets/css/docs.min.css docs/assets/js/customize.min.js docs/assets/js/raw-files.min.js docs/dist/css/bootstrap-theme.css docs/dist/css/bootstrap-theme.min.css docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/dist/fonts/glyphicons-halflings-regular.eot docs/dist/fonts/glyphicons-halflings-regular.svg docs/dist/fonts/glyphicons-halflings-regular.ttf docs/dist/fonts/glyphicons-halflings-regular.woff docs/examples/carousel/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/non-responsive/non-responsive.css docs/examples/sticky-footer-navbar/index.html docs/examples/theme/index.html fonts/glyphicons-halflings-regular.eot fonts/glyphicons-halflings-regular.svg fonts/glyphicons-halflings-regular.ttf fonts/glyphicons-halflings-regular.woff less/_carousel.less less/_forms.less less/glyphicons.less
2014-12-01 05:17:45 +01:00
Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. **There's no need to add a class to `<button>`s as they use a pseudo-class**. However, you can still force the same active appearance with `.active` (and include the <code>aria-pressed="true"</code> attribute) should you need to replicate the state programmatically.
2014-07-10 06:17:10 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
<a href="#" class="btn btn-primary btn-lg active" role="button" aria-pressed="true">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg active" role="button" aria-pressed="true">Link</a>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
## Disabled state
2015-08-11 01:11:44 +02:00
Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element.
2018-03-14 16:44:38 +01:00
{% capture example %}
2014-07-10 06:17:10 +02:00
<button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button>
<button type="button" class="btn btn-secondary btn-lg" disabled>Button</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
Disabled buttons using the `<a>` element behave a bit different:
- `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled.
- Some future-friendly styles are included to disable all `pointer-events` on anchor buttons. In browsers which support that property, you won't see the disabled cursor at all.
- Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
2014-07-10 06:17:10 +02:00
2018-03-14 16:44:38 +01:00
{% capture example %}
<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2014-07-10 06:17:10 +02:00
{% capture callout %}
##### Link functionality caveat
The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a `tabindex="-1"` attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality.
{% endcapture %}
{% include callout.html content=callout type="warning" %}
2014-07-10 06:17:10 +02:00
2015-08-10 09:05:40 +02:00
## Button plugin
Do more with buttons. Control button states or create groups of buttons for more components like toolbars.
2015-08-10 09:05:40 +02:00
### Toggle states
Add `data-toggle="button"` to toggle a button's `active` state. If you're pre-toggling a button, you must manually add the `.active` class **and** `aria-pressed="true"` to the `<button>`.
2018-03-14 16:44:38 +01:00
{% capture example %}
<button type="button" class="btn btn-primary" data-toggle="button" aria-pressed="false" autocomplete="off">
Single toggle
</button>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2015-08-10 09:05:40 +02:00
### Checkbox and radio buttons
2017-12-24 23:26:52 +01:00
Bootstrap's `.button` styles can be applied to other elements, such as `<label>`s, to provide checkbox or radio style button toggling. Add `data-toggle="buttons"` to a `.btn-group` containing those modified buttons to enable their toggling behavior via JavaScript and add `.btn-group-toggle` to style the `<input>`s within your buttons. **Note that you can create single input-powered buttons or groups of them.**
The checked state for these buttons is **only updated via `click` event** on the button. If you use another method to update the input—e.g., with `<input type="reset">` or by manually applying the input's `checked` property—you'll need to toggle `.active` on the `<label>` manually.
Note that pre-checked buttons require you to manually add the `.active` class to the input's `<label>`.
2018-03-14 16:44:38 +01:00
{% capture example %}
<div class="btn-group-toggle" data-toggle="buttons">
<label class="btn btn-secondary active">
<input type="checkbox" checked autocomplete="off"> Checked
2015-04-17 23:24:11 +02:00
</label>
</div>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
2018-03-14 16:44:38 +01:00
{% capture example %}
<div class="btn-group btn-group-toggle" data-toggle="buttons">
<label class="btn btn-secondary active">
<input type="radio" name="options" id="option1" autocomplete="off" checked> Active
</label>
<label class="btn btn-secondary">
<input type="radio" name="options" id="option2" autocomplete="off"> Radio
</label>
<label class="btn btn-secondary">
<input type="radio" name="options" id="option3" autocomplete="off"> Radio
</label>
</div>
2018-03-14 16:44:38 +01:00
{% endcapture %}
{% include example.html content=example %}
### Methods
2015-08-10 09:05:40 +02:00
| Method | Description |
| --- | --- |
| `$().button('toggle')` | Toggles push state. Gives the button the appearance that it has been activated. |
| `$().button('dispose')` | Destroys an element's button. |