Skip to content

B
bootstrap
Commit 3ec4ca17 authored by Mark Otto's avatar Mark Otto
Browse files
Options

rewrite helpers in markdown

parent cfc16c94
Hide whitespace changes
Inline Side-by-side
Showing with 217 additions and 226 deletions
docs/_includes/css/buttons.md
View file @ 3ec4ca17
<div class="bs-docs-section">
<h1 id="buttons" class="page-header">Buttons</h1>
<p>Use any of the available button classes to quickly create a styled button.</p>
<div class="bs-example">
<p>
<button type="button" class="btn btn-primary">Primary</button>
<button type="button" class="btn btn-secondary">Secondary</button>
<button type="button" class="btn btn-success">Success</button>
<button type="button" class="btn btn-warning">Warning</button>
<button type="button" class="btn btn-danger">Danger</button>
<button type="button" class="btn btn-link">Link</button>
</p>
</div>
{% highlight html %}
<a id="buttons"></a>
# Buttons
Use any of the available button classes to quickly create a styled button.
{% example html %}
<!-- Provides extra visual weight and identifies the primary action in a set of buttons -->
<button type="button" class="btn btn-primary">Primary</button>
......@@ -29,146 +22,104 @@
<!-- Deemphasize a button by making it look like a link while maintaining button behavior -->
<button type="button" class="btn btn-link">Link</button>
{% endhighlight %}
<h2 id="buttons-sizes">Sizes</h2>
<p>Fancy larger or smaller buttons? Add <code>.btn-lg</code>, <code>.btn-sm</code>, or <code>.btn-xs</code> for additional sizes.</p>
<div class="bs-example">
<p>
<button type="button" class="btn btn-primary btn-lg">Large button</button>
<button type="button" class="btn btn-secondary btn-lg">Large button</button>
</p>
<p>
<button type="button" class="btn btn-primary">Default button</button>
<button type="button" class="btn btn-secondary">Default button</button>
</p>
<p>
<button type="button" class="btn btn-primary btn-sm">Small button</button>
<button type="button" class="btn btn-secondary btn-sm">Small button</button>
</p>
<p>
<button type="button" class="btn btn-primary btn-xs">Extra small button</button>
<button type="button" class="btn btn-secondary btn-xs">Extra small button</button>
</p>
</div>
{% highlight html %}
<p>
<button type="button" class="btn btn-primary btn-lg">Large button</button>
<button type="button" class="btn btn-secondary btn-lg">Large button</button>
</p>
<p>
<button type="button" class="btn btn-primary">Default button</button>
<button type="button" class="btn btn-secondary">Default button</button>
</p>
<p>
<button type="button" class="btn btn-primary btn-sm">Small button</button>
<button type="button" class="btn btn-secondary btn-sm">Small button</button>
</p>
<p>
<button type="button" class="btn btn-primary btn-xs">Extra small button</button>
<button type="button" class="btn btn-secondary btn-xs">Extra small button</button>
</p>
{% endhighlight %}
<p>Create block level buttons&mdash;those that span the full width of a parent&mdash; by adding <code>.btn-block</code>.</p>
<div class="bs-example">
<div class="well" style="max-width: 400px; margin: 0 auto 10px;">
<button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button>
<button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button>
</div>
</div>
{% highlight html %}
{% endexample %}
<a id="buttons-sizes"></a>
## Sizes
Fancy larger or smaller buttons? Add `.btn-lg`, `.btn-sm`, or `.btn-xs` for additional sizes.
{% example html %}
<button type="button" class="btn btn-primary btn-lg">Large button</button>
<button type="button" class="btn btn-secondary btn-lg">Large button</button>
{% endexample %}
{% example html %}
<button type="button" class="btn btn-primary btn-sm">Small button</button>
<button type="button" class="btn btn-secondary btn-sm">Small button</button>
{% endexample %}
{% example html %}
<button type="button" class="btn btn-primary btn-xs">Extra small button</button>
<button type="button" class="btn btn-secondary btn-xs">Extra small button</button>
{% endexample %}
Create block level buttons—those that span the full width of a parent—by adding `.btn-block`.
{% example html %}
<button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button>
<button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button>
{% endhighlight %}
<h2 id="buttons-active">Active state</h2>
<p>Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. For <code>&lt;button&gt;</code> elements, this is done via <code>:active</code>. For <code>&lt;a&gt;</code> elements, it's done with <code>.active</code>. However, you may use <code>.active</code> on <code>&lt;button&gt;</code>s should you need to replicate the active state programmatically.</p>
<h3>Button element</h3>
<p>No need to add <code>:active</code> as it's a pseudo-class, but if you need to force the same appearance, go ahead and add <code>.active</code>.</p>
<p class="bs-example">
<button type="button" class="btn btn-primary btn-lg active">Primary button</button>
<button type="button" class="btn btn-secondary btn-lg active">Button</button>
</p>
{% highlight html %}
<button type="button" class="btn btn-primary btn-lg active">Primary button</button>
<button type="button" class="btn btn-secondary btn-lg active">Button</button>
{% endhighlight %}
<h3>Anchor element</h3>
<p>Add the <code>.active</code> class to <code>&lt;a&gt;</code> buttons.</p>
<p class="bs-example">
<a href="#" class="btn btn-primary btn-lg active" role="button">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg active" role="button">Link</a>
</p>
{% highlight html %}
{% endexample %}
<a id="buttons-active"></a>
## Active state
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` should you need to replicate the state programmatically.
{% example html %}
<a href="#" class="btn btn-primary btn-lg active" role="button">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg active" role="button">Link</a>
{% endhighlight %}
<h2 id="buttons-disabled">Disabled state</h2>
<p>Make buttons look unclickable by fading them back 50%.</p>
<h3>Button element</h3>
<p>Add the <code>disabled</code> attribute to <code>&lt;button&gt;</code> buttons.</p>
<p class="bs-example">
<button type="button" class="btn btn-primary btn-lg" disabled="disabled">Primary button</button>
<button type="button" class="btn btn-secondary btn-lg" disabled="disabled">Button</button>
</p>
{% highlight html %}
<button type="button" class="btn btn-lg btn-primary" disabled="disabled">Primary button</button>
<button type="button" class="btn btn-secondary btn-lg" disabled="disabled">Button</button>
{% endhighlight %}
<div class="bs-callout bs-callout-danger">
<h4>Cross-browser compatibility</h4>
<p>If you add the <code>disabled</code> attribute to a <code>&lt;button&gt;</code>, Internet Explorer 9 and below will render text gray with a nasty text-shadow that we cannot fix.</p>
</div>
<h3>Anchor element</h3>
<p>Add the <code>.disabled</code> class to <code>&lt;a&gt;</code> buttons.</p>
<p class="bs-example">
<a href="#" class="btn btn-primary btn-lg disabled" role="button">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" role="button">Link</a>
</p>
{% highlight html %}
{% endexample %}
<a id="buttons-disabled"></a>
## Disabled state
Make buttons look unclickable by adding the `disabled` boolean attribute to any `<button>` element.
{% example html %}
<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>
{% endexample %}
As `<a>` elements don't support the `disabled` attribute, you must add the `.disabled` class to fake it.
{% example html %}
<a href="#" class="btn btn-primary btn-lg disabled" role="button">Primary link</a>
<a href="#" class="btn btn-secondary btn-lg disabled" role="button">Link</a>
{% endhighlight %}
<p>
We use <code>.disabled</code> as a utility class here, similar to the common <code>.active</code> class, so no prefix is required.
</p>
<div class="bs-callout bs-callout-warning">
<h4>Link functionality caveat</h4>
<p>This class uses <code>pointer-events: none</code> to try to disable the link functionality of <code>&lt;a&gt;</code>s, but that CSS property is not yet standardized and isn't fully supported in Opera 18 and below, or in Internet Explorer 11. So to be safe, use custom JavaScript to disable such links.</p>
</div>
<div class="bs-callout bs-callout-warning">
<h4>Context-specific usage</h4>
<p>While button classes can be used on <code>&lt;a&gt;</code> and <code>&lt;button&gt;</code> elements, only <code>&lt;button&gt;</code> elements are supported within our nav and navbar components.</p>
</div>
<h2 id="buttons-tags">Button tags</h2>
<p>Use the button classes on an <code>&lt;a&gt;</code>, <code>&lt;button&gt;</code>, or <code>&lt;input&gt;</code> element.</p>
<form class="bs-example">
<a class="btn btn-secondary" href="#" role="button">Link</a>
<button class="btn btn-secondary" type="submit">Button</button>
<input class="btn btn-secondary" type="button" value="Input">
<input class="btn btn-secondary" type="submit" value="Submit">
</form>
{% highlight html %}
{% endexample %}
<div class="bs-callout bs-callout-warning">
<h4>Cross-browser compatibility</h4>
<p>If you add the <code>disabled</code> attribute to a <code>&lt;button&gt;</code>, Internet Explorer 9 and below will render text gray with a nasty text-shadow that we cannot fix.</p>
</div>
<div class="bs-callout bs-callout-warning">
<h4>Link functionality caveat</h4>
<p>This class uses <code>pointer-events: none</code> to try to disable the link functionality of <code>&lt;a&gt;</code>s, but that CSS property is not yet standardized and isn't fully supported in Opera 18 and below, or in Internet Explorer 11. So to be safe, use custom JavaScript to disable such links.</p>
</div>
<div class="bs-callout bs-callout-warning">
<h4>Context-specific usage</h4>
<p>While button classes can be used on <code>&lt;a&gt;</code> and <code>&lt;button&gt;</code> elements, only <code>&lt;button&gt;</code> elements are supported within our nav and navbar components.</p>
</div>
<a id="buttons-tags"></a>
## Button tags
Use the button classes on an `<a>`, `<button>`, or `<input>` element.
{% example html %}
<a class="btn btn-secondary" href="#" role="button">Link</a>
<button class="btn btn-secondary" type="submit">Button</button>
<input class="btn btn-secondary" type="button" value="Input">
<input class="btn btn-secondary" type="submit" value="Submit">
{% endhighlight %}
{% endexample %}
<div class="bs-callout bs-callout-warning">
<h4>Cross-browser rendering</h4>
<p>As a best practice, <strong>we highly recommend using the <code>&lt;button&gt;</code> element whenever possible</strong> to ensure matching cross-browser rendering.</p>
<p>Among other things, there's <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=697451">a bug in Firefox &lt;30</a> that prevents us from setting the <code>line-height</code> of <code>&lt;input&gt;</code>-based buttons, causing them to not exactly match the height of other buttons on Firefox.</p>
</div>
<div class="bs-callout bs-callout-warning">
<h4>Cross-browser rendering</h4>
<p>As a best practice, <strong>we highly recommend using the <code>&lt;button&gt;</code> element whenever possible</strong> to ensure matching cross-browser rendering.</p>
<p>Among other things, there's <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=697451">a bug in Firefox &lt;30</a> that prevents us from setting the <code>line-height</code> of <code>&lt;input&gt;</code>-based buttons, causing them to not exactly match the height of other buttons on Firefox.</p>
</div>
docs/_includes/css/helpers.md
View file @ 3ec4ca17
<div class="bs-docs-section">
<h1 id="helper-classes" class="page-header">Helper classes</h1>
<h3 id="helper-classes-colors">Contextual colors</h3>
<p>Convey meaning through color with a handful of emphasis utility classes. These may also be applied to links and will darken on hover just like our default link styles.</p>
<div class="bs-example">
<p class="text-muted">Fusce dapibus, tellus ac cursus commodo, tortor mauris nibh.</p>
<p class="text-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</p>
<p class="text-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
<p class="text-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
<p class="text-warning">Etiam porta sem malesuada magna mollis euismod.</p>
<p class="text-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
</div>
{% highlight html %}
<p class="text-muted">...</p>
<p class="text-primary">...</p>
<p class="text-success">...</p>
<p class="text-info">...</p>
<p class="text-warning">...</p>
<p class="text-danger">...</p>
{% endhighlight %}
<div class="bs-callout bs-callout-info">
<h4>Dealing with specificity</h4>
<p>Sometimes emphasis classes cannot be applied due to the specificity of another selector. In most cases, a sufficient workaround is to wrap your text in a <code>&lt;span&gt;</code> with the class.</p>
</div>
<h3 id="helper-classes-backgrounds">Contextual backgrounds</h3>
<p>Similar to the contextual text color classes, easily set the background of an element to any contextual class. Anchor components will darken on hover, just like the text classes.</p>
<div class="bs-example bs-example-bg-classes">
<p class="bg-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</p>
<p class="bg-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
<p class="bg-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
<p class="bg-warning">Etiam porta sem malesuada magna mollis euismod.</p>
<p class="bg-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
</div>
{% highlight html %}
<p class="bg-primary">...</p>
<p class="bg-success">...</p>
<p class="bg-info">...</p>
<p class="bg-warning">...</p>
<p class="bg-danger">...</p>
{% endhighlight %}
<div class="bs-callout bs-callout-info">
<h4>Dealing with specificity</h4>
<p>Sometimes contextual background classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a <code>&lt;div&gt;</code> with the class.</p>
</div>
<h3 id="helper-classes-close">Close icon</h3>
<p>Use the generic close icon for dismissing content like modals and alerts.</p>
<div class="bs-example">
<p><button type="button" class="close"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button></p>
</div>
{% highlight html %}
<button type="button" class="close"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
{% endhighlight %}
<a id="helpers"></a>
<h3 id="helper-classes-floats">Quick floats</h3>
<p>Float an element to the left or right with a class. <code>!important</code> is included to avoid specificity issues. Classes can also be used as mixins.</p>
{% highlight html %}
# Helper classes
<a id="helpers-colors"></a>
### Contextual colors
Convey meaning through color with a handful of emphasis utility classes. These may also be applied to links and will darken on hover just like our default link styles.
{% example html %}
<p class="text-muted">Fusce dapibus, tellus ac cursus commodo, tortor mauris nibh.</p>
<p class="text-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</p>
<p class="text-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</p>
<p class="text-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</p>
<p class="text-warning">Etiam porta sem malesuada magna mollis euismod.</p>
<p class="text-danger">Donec ullamcorper nulla non metus auctor fringilla.</p>
{% endexample %}
<div class="bs-callout bs-callout-info">
<h4>Dealing with specificity</h4>
<p>Sometimes emphasis classes cannot be applied due to the specificity of another selector. In most cases, a sufficient workaround is to wrap your text in a <code>&lt;span&gt;</code> with the class.</p>
</div>
<a id="helpers-bgs"></a>
### Contextual backgrounds
Similar to the contextual text color classes, easily set the background of an element to any contextual class. Anchor components will darken on hover, just like the text classes.
{% example html %}
<div class="bg-primary">Nullam id dolor id nibh ultricies vehicula ut id elit.</div>
<div class="bg-success">Duis mollis, est non commodo luctus, nisi erat porttitor ligula.</div>
<div class="bg-info">Maecenas sed diam eget risus varius blandit sit amet non magna.</div>
<div class="bg-warning">Etiam porta sem malesuada magna mollis euismod.</div>
<div class="bg-danger">Donec ullamcorper nulla non metus auctor fringilla.</div>
{% endexample %}
<div class="bs-callout bs-callout-info">
<h4>Dealing with specificity</h4>
<p>Sometimes contextual background classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a <code>&lt;div&gt;</code> with the class.</p>
</div>
<a id="helpers-close"></a>
### Close icon
Use a generic close icon for dismissing content like modals and alerts. **Be sure to include screen reader text when you can** as we've done with `.sr-only`.
{% example html %}
<button type="button" class="close">
<span aria-hidden="true">&times;</span>
<span class="sr-only">Close</span>
</button>
{% endexample %}
<a id="helpers-floats"></a>
### Quick floats
Float an element to the left or right with a class. `!important` is included to avoid specificity issues. Classes can also be used as mixins.
{% example html %}
<div class="pull-left">...</div>
<div class="pull-right">...</div>
{% endhighlight %}
{% endexample %}
{% highlight scss %}
// Classes
.pull-left {
......@@ -78,17 +91,23 @@
}
{% endhighlight %}
<div class="bs-callout bs-callout-warning">
<h4>Not for use in navbars</h4>
<p>To align components in navbars with utility classes, use <code>.navbar-left</code> or <code>.navbar-right</code> instead. <a href="../components/#navbar-component-alignment">See the navbar docs</a> for details.</p>
</div>
<div class="bs-callout bs-callout-warning">
<h4>Not for use in navbars</h4>
<p>To align components in navbars with utility classes, use <code>.navbar-left</code> or <code>.navbar-right</code> instead. <a href="../components/#navbar-component-alignment">See the navbar docs</a> for details.</p>
</div>
<h3 id="helper-classes-center">Center content blocks</h3>
<p>Set an element to <code>display: block</code> and center via <code>margin</code>. Available as a mixin and class.</p>
{% highlight html %}
<a id="helpers-center"></a>
### Center content blocks
Set an element to `display: block;` and center via `margin`. Available as a mixin and class.
{% example html %}
<div class="center-block">...</div>
{% endhighlight %}
{% endexample %}
{% highlight scss %}
// Classes
.center-block {
......@@ -104,12 +123,15 @@
{% endhighlight %}
<h3 id="helper-classes-clearfix">Clearfix</h3>
<p>Easily clear <code>float</code>s by adding <code>.clearfix</code> <strong>to the parent element</strong>. Utilizes <a href="http://nicolasgallagher.com/micro-clearfix-hack/">the micro clearfix</a> as popularized by Nicolas Gallagher. Can also be used as a mixin.</p>
<a id="helpers-clearfix"></a>
Easily clear `float`s by adding `.clearfix` **to the parent element**. Utilizes [the micro clearfix](http://nicolasgallagher.com/micro-clearfix-hack/) as popularized by Nicolas Gallagher. Can also be used as a mixin.
{% highlight html %}
<!-- Usage as a class -->
<div class="clearfix">...</div>
{% endhighlight %}
{% highlight scss %}
// Mixin itself
.clearfix() {
......@@ -130,13 +152,20 @@
{% endhighlight %}
<h3 id="helper-classes-show-hide">Showing and hiding content</h3>
<p>Force an element to be shown or hidden (<strong>including for screen readers</strong>) with the use of <code>.show</code> and <code>.hidden</code> classes. These classes use <code>!important</code> to avoid specificity conflicts, just like the <a href="#helper-classes-floats">quick floats</a>. They are only available for block level toggling. They can also be used as mixins.</p>
<p>Furthermore, <code>.invisible</code> can be used to toggle only the visibility of an element, meaning its <code>display</code> is not modified and the element can still affect the flow of the document.</p>
<a id="helpers-toggles"></a>
### Showing and hiding content
Force an element to be shown or hidden (**including for screen readers**) with the use of `.show` and `.hidden` classes. These classes use `!important` to avoid specificity conflicts, just like the [quick floats](#helper-floats). They are only available for block level toggling. They can also be used as mixins.
Furthermore, `.invisible` can be used to toggle only the visibility of an element, meaning its `display` is not modified and the element can still affect the flow of the document.
{% highlight html %}
<div class="show">...</div>
<div class="hidden">...</div>
{% endhighlight %}
{% highlight scss %}
// Classes
.show {
......@@ -160,11 +189,17 @@
{% endhighlight %}
<h3 id="helper-classes-screen-readers">Screen reader and keyboard navigation content</h3>
<p>Hide an element to all devices <strong>except screen readers</strong> with <code>.sr-only</code>. Combine <code>.sr-only</code> with <code>.sr-only-focusable</code> to show the element again when it's focused (e.g. by a keyboard-only user). Necessary for following <a href="../getting-started/#accessibility">accessibility best practices</a>. Can also be used as mixins.</p>
<a id="helpers-screen-readers"></a>
### Screen readers and keyboard navigation
Hide an element to all devices **except screen readers** with `.sr-only`. Combine `.sr-only` with `.sr-only-focusable` to show the element again when it's focused (e.g. by a keyboard-only user). Necessary for following [accessibility best practices](../getting-started/#accessibility). Can also be used as mixins.
{% highlight html %}
<a class="sr-only sr-only-focusable" href="#content">Skip to main content</a>
{% endhighlight %}
{% highlight scss %}
// Usage as a Mixin
.skip-navigation {
......@@ -174,15 +209,20 @@
{% endhighlight %}
<h3 id="helper-classes-image-replacement">Image replacement</h3>
<p>Utilize the <code>.text-hide</code> class or mixin to help replace an element's text content with a background image.</p>
{% highlight html %}
<a id="helpers-image-replacement"></a>
### Image replacement
Utilize the `.text-hide` class or mixin to help replace an element's text content with a background image.
{% example html %}
<h1 class="text-hide">Custom heading</h1>
{% endhighlight %}
{% highlight scss %}
{% endexample %}
{% highlight scss %}
// Usage as a Mixin
.heading {
.text-hide();
}
{% endhighlight %}
</div>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment