UNPKG

4.58 kBMarkdownView Raw
1<!--docs:
2title: "Notched Outline"
3layout: detail
4section: components
5excerpt: "The notched outline is a border around either a Text Field or Select element"
6iconId: text_field
7path: /catalog/input-controls/notched-outline/
8-->
9
10# Notched Outline
11
12The notched outline is a border around all sides of either a Text Field or Select component. This is used for the Outlined variant of either a Text Field or Select.
13
14## Design & API Documentation
15
16<ul class="icon-list">
17 <li class="icon-list-item icon-list-item--spec">
18 <a href="https://material.io/go/design-text-fields#text-fields-field-variations">Material Design guidelines: Text Field Variations</a>
19 </li>
20 <li class="icon-list-item icon-list-item--spec">
21 <a href="https://material-components.github.io/material-components-web-catalog/#/component/text-field">Demo with Notched Outline on Text Field</a>
22 </li>
23</ul>
24
25## Installation
26
27```
28npm install @material/notched-outline
29```
30
31## Basic Usage
32
33### HTML Structure
34
35```html
36<span class="mdc-notched-outline">
37 <span class="mdc-notched-outline__leading"></span>
38 <span class="mdc-notched-outline__notch">
39 <span class="mdc-floating-label">Label</span>
40 </span>
41 <span class="mdc-notched-outline__trailing"></span>
42</span>
43```
44
45> Note that the [MDC Floating Label](../mdc-floating-label/README.md) component is placed inside the notch element when
46> used together with MDC Notched Outline.
47
48> See the [MDC Text Field](../mdc-textfield/README.md#outlined) and
49> [MDC Select](../mdc-select/README.md#outlined-select) documentation for
50> information on using Notched Outline in the context of those components.
51
52### Styles
53
54```scss
55@use "@material/notched-outline/mdc-notched-outline";
56```
57
58### JavaScript Instantiation
59
60```js
61import {MDCNotchedOutline} from '@material/notched-outline';
62
63const notchedOutline = new MDCNotchedOutline(document.querySelector('.mdc-notched-outline'));
64```
65
66> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
67
68## Style Customization
69
70### CSS Classes
71
72CSS Class | Description
73--- | ---
74`mdc-notched-outline` | Mandatory. Container for the outline's sides and notch.
75`mdc-notched-outline--notched` | Modifier class to open the notched outline.
76`mdc-notched-outline--no-label` | Modifier class to use when the floating label is empty or not used.
77`mdc-notched-outline__leading` | Mandatory. Element representing the leading side of the notched outline (before the notch).
78`mdc-notched-outline__notch` | Mandatory. Element representing the notch.
79`mdc-notched-outline__trailing` | Mandatory. Element representing the trailing side of the notched outline (after the notch).
80
81### Sass Mixins
82
83Mixin | Description
84--- | ---
85`color($color)` | Customizes the border color of the notched outline.
86`stroke-width($width)` | Changes notched outline width to a specified pixel value.
87`shape-radius($radius, $rtl-reflexive)` | Sets the rounded shape to notched outline element with given radius size. Set `$rtl-reflexive` to true to flip radius values in RTL context, defaults to false.
88`floating-label-float-position($positionY, $positionX, $scale)` | Sets the position and scale of the floating label inside the notched outline.
89
90## `MDCNotchedOutline` Properties and Methods
91
92Method Signature | Description
93--- | ---
94`notch(notchWidth: number) => void` | Opens the notch with the specified width.
95`closeNotch() => void` | Closes the notch, rendering a full outline.
96
97## Usage Within Frameworks
98
99If you are using a JavaScript framework, such as React or Angular, you can create a Notched Outline for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).
100
101### `MDCNotchedOutlineAdapter`
102
103Method Signature | Description
104--- | ---
105`addClass(className: string) => void` | Adds a class to the notched outline element.
106`removeClass(className: string) => void` | Removes a class from the notched outline element.
107`setNotchWidthProperty(width: number) => void` | Sets the width of the notch in pixels.
108`removeNotchWidthProperty() => void` | Removes the width property from the notch element.
109
110### `MDCNotchedOutlineFoundation`
111
112Method Signature | Description
113--- | ---
114`notch(notchWidth: number) => void` | Adds the `mdc-notched-outline--notched` class and updates the notch element's style based on `notchWidth`.
115`closeNotch() => void` | Removes the `mdc-notched-outline--notched` class.