-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
206 lines (148 loc) · 6.63 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
---
title: "<kbd>: The Keyboard Input element"
slug: Web/HTML/Element/kbd
page-type: html-element
browser-compat: html.elements.kbd
---
{{HTMLSidebar}}
The **`<kbd>`** [HTML](/en-US/docs/Web/HTML) element represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device. By convention, the {{Glossary("user agent")}} defaults to rendering the contents of a `<kbd>` element using its default monospace font, although this is not mandated by the HTML standard.
{{EmbedInteractiveExample("pages/tabbed/kbd.html", "tabbed-shorter")}}
`<kbd>` may be nested in various combinations with the {{HTMLElement("samp")}} (Sample Output) element to represent various forms of input or output based on visual cues.
## Attributes
This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes).
## Usage notes
Other elements can be used in tandem with `<kbd>` to represent more specific scenarios:
- Nesting a `<kbd>` element within another `<kbd>` element represents an actual key or other unit of input as a portion of a larger input. See [Representing keystrokes within an input](#representing_keystrokes_within_an_input) below.
- Nesting a `<kbd>` element inside a {{HTMLElement("samp")}} element represents input that has been echoed back to the user by the system. See [Echoed input](#echoed_input), below, for an example.
- Nesting a `<samp>` element inside a `<kbd>` element, on the other hand, represents input which is based on text presented by the system, such as the names of menus and menu items, or the names of buttons displayed on the screen. See the example under [Representing onscreen input options](#representing_onscreen_input_options) below.
> **Note:** You can define a custom style to override the browser's default font selection for the `<kbd>` element, although the user's preferences may potentially override your CSS.
## Examples
### Basic example
```html
<p>
Use the command <kbd>help mycommand</kbd> to view documentation for the
command "mycommand".
</p>
```
#### Result
{{ EmbedLiveSample('Basic_example', 350, 80) }}
### Representing keystrokes within an input
To describe an input comprised of multiple keystrokes, you can nest multiple `<kbd>` elements, with an outer `<kbd>` element representing the overall input and each individual keystroke or component of the input enclosed within its own `<kbd>`.
#### Unstyled
First, let's look at what this looks like as just plain HTML.
##### HTML
```html
<p>
You can also create a new document using the
<kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> keyboard shortcut.
</p>
```
This wraps the entire key sequence in an outer `<kbd>` element, then each individual key within its own, in order to denote the components of the sequence.
> **Note:** You don't need to do all this wrapping; you can choose to simplify it by leaving out the external `<kbd>` element. In other words, simplifying this to just `<kbd>Ctrl</kbd>+<kbd>N</kbd>` would be perfectly valid.
>
> **Note:** Depending on your style sheet, though, you may find it useful to do this kind of nesting.
##### Result
The output looks like this without a style sheet applied:
{{EmbedLiveSample("Unstyled", 650, 80)}}
#### With custom styles
We can make more sense of this by adding some CSS:
##### CSS
We add a new selector for nested `<kbd>` elements, `kbd>kbd`, which we can apply when rendering keyboard keys:
```css
kbd > kbd {
border-radius: 3px;
padding: 1px 2px 0;
border: 1px solid black;
}
```
##### HTML
Then we update the HTML to use this class on the keys in the output to be presented:
```html
<p>
You can also create a new document by pressing the
<kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut.
</p>
```
##### Result
The result is just what we want!
{{EmbedLiveSample("With_custom_styles", 650, 80)}}
### Echoed input
Nesting a `<kbd>` element inside a {{HTMLElement("samp")}} element represents input that has been echoed back to the user by the system.
```html
<p>
If a syntax error occurs, the tool will output the initial command you typed
for your review:
</p>
<blockquote>
<samp><kbd>custom-git ad my-new-file.cpp</kbd></samp>
</blockquote>
```
#### Result
{{EmbedLiveSample("Echoed_input", 650, 100)}}
### Representing onscreen input options
Nesting a `<samp>` element inside a `<kbd>` element represents input which is based on text presented by the system, such as the names of menus and menu items, or the names of buttons displayed on the screen.
For example, you can explain how to choose the "New Document" option in the "File" menu using HTML that looks like this:
```html-nolint
<p>
To create a new file, choose the <kbd><kbd><samp>File</samp></kbd>
⇒<kbd><samp>New Document</samp></kbd></kbd> menu option.
</p>
<p>
Don't forget to click the <kbd><samp>OK</samp></kbd> button to confirm once
you've entered the name of the new file.
</p>
```
This does some interesting nesting. For the menu option description, the entire input is enclosed in a `<kbd>` element. Then, inside that, both the menu and menu item names are contained within both `<kbd>` and `<samp>`, indicating an input which is selected from a screen widget.
#### Result
{{EmbedLiveSample("Representing_onscreen_input_options", 650, 120)}}
## Technical summary
<table class="properties">
<tbody>
<tr>
<th scope="row">
<a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a>
</th>
<td>
<a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>,
<a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>, palpable content.
</td>
</tr>
<tr>
<th scope="row">Permitted content</th>
<td>
<a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">Phrasing content</a>.
</td>
</tr>
<tr>
<th scope="row">Tag omission</th>
<td>None, both the starting and ending tag are mandatory.</td>
</tr>
<tr>
<th scope="row">Permitted parents</th>
<td>
Any element that accepts
<a href="/en-US/docs/Web/HTML/Content_categories#phrasing_content">phrasing content</a>.
</td>
</tr>
<tr>
<th scope="row">Implicit ARIA role</th>
<td>
<a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role">No corresponding role</a>
</td>
</tr>
<tr>
<th scope="row">Permitted ARIA roles</th>
<td>Any</td>
</tr>
<tr>
<th scope="row">DOM interface</th>
<td>{{domxref("HTMLElement")}}</td>
</tr>
</tbody>
</table>
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- {{htmlelement("code")}}