@material/notched-outline

What is @material/notched-outline?

@material/notched-outline is a package from Material Design Components (MDC) that provides a notched outline component. This component is typically used to create a visual effect around form fields, such as text fields, to indicate focus or selection. The notched outline is a key part of the Material Design guidelines for text fields.

What are @material/notched-outline's main functionalities?

Basic Notched Outline

This code sample demonstrates the basic structure of a notched outline with a floating label. The HTML structure includes the leading, notch, and trailing elements, while the CSS provides basic styling to visualize the notched outline.

{
  "html": "<div class='mdc-notched-outline'><div class='mdc-notched-outline__leading'></div><div class='mdc-notched-outline__notch'><span class='mdc-floating-label'>Label</span></div><div class='mdc-notched-outline__trailing'></div></div>",
  "css": ".mdc-notched-outline { position: relative; border: 1px solid; } .mdc-notched-outline__leading, .mdc-notched-outline__trailing { display: inline-block; } .mdc-notched-outline__notch { display: inline-block; padding: 0 8px; } .mdc-floating-label { position: absolute; top: -8px; left: 8px; }"
}

Notched Outline with Focus

This code sample shows a notched outline in a focused state. The `mdc-notched-outline--upgraded` and `mdc-notched-outline--notched` classes are used to apply styles that indicate focus, such as changing the border color to blue and floating the label above the notch.

{
  "html": "<div class='mdc-notched-outline mdc-notched-outline--upgraded mdc-notched-outline--notched'><div class='mdc-notched-outline__leading'></div><div class='mdc-notched-outline__notch'><span class='mdc-floating-label mdc-floating-label--float-above'>Label</span></div><div class='mdc-notched-outline__trailing'></div></div>",
  "css": ".mdc-notched-outline { position: relative; border: 1px solid; } .mdc-notched-outline--upgraded { border-color: blue; } .mdc-notched-outline--notched .mdc-notched-outline__notch { border-color: blue; } .mdc-floating-label--float-above { color: blue; }"
}

Other packages similar to @material/notched-outline

react-material-ui

React Material-UI is a popular library that implements Material Design components for React applications. It includes a TextField component with a notched outline feature, similar to @material/notched-outline. However, it is more comprehensive, offering a wide range of Material Design components beyond just the notched outline.

vuetify

Vuetify is a Material Design component framework for Vue.js. It provides a variety of components, including form inputs with notched outlines. Vuetify is similar to @material/notched-outline in that it adheres to Material Design guidelines, but it is tailored specifically for Vue.js applications.

angular-material

Angular Material is a UI component library for Angular developers that follows Material Design principles. It includes form field components with notched outlines, similar to @material/notched-outline. Angular Material is designed to integrate seamlessly with Angular applications, providing a consistent look and feel.

README

Notched Outline

The 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.

Design & API Documentation

• Material Design guidelines: Text Field Variations
• Demo with Notched Outline on Text Field

Installation

npm install @material/notched-outline

Basic Usage

HTML Structure

<div class="mdc-notched-outline">
  <svg>
    <path class="mdc-notched-outline__path"/>
  </svg>
</div>
<div class="mdc-notched-outline__idle"></div>

For usage within a text field see here.

Styles

@import "@material/notched-outline/mdc-notched-outline";

JavaScript Instantiation

import {MDCNotchedOutline} from '@material/notched-outline';

const notchedOutline = new MDCNotchedOutline(document.querySelector('.mdc-notched-outline'));

See Importing the JS component for more information on how to import JavaScript.

Style Customization

CSS Classes

CSS Class	Description
mdc-notched-outline	Mandatory. Container for the SVG of the notched outline path.
mdc-notched-outline--notched	Class to open notch outline.
mdc-notched-outline__path	Mandatory. The path of the SVG of the notched outline.
mdc-notched-outline__idle	Mandatory. The full outline when the notch is hidden.

Sass Mixins

Mixin	Description
mdc-notched-outline-color($color)	Customizes the border color of the notched outlined.
mdc-notched-outline-idle-color($color)	Customizes the border color of the idle outline.
mdc-notched-outline-stroke-width($width)	Changes notched outline width to a specified pixel value.
mdc-notched-outline-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.
mdc-notched-outline-idle-shape-radius($radius, $rtl-reflexive)	Sets the rounded shape to notched outline element in idle state with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.

Calling Mixins with Parent Selectors

Because notched-outline has sibling elements, you need to call the "idle" Sass mixins with parent selectors. Consider the following example HTML:

<div class="foo__parent">
  <div class="mdc-notched-outline foo__child">
    <svg>
      <path class="mdc-notched-outline__path"/>
    </svg>
  </div>
  <div class="mdc-notched-outline__idle"></div>
</div>

In order to customize any "non-idle" part of notched-outline, use the .foo__child CSS selector:

.foo__child {
  @include mdc-notched-outline-color($fooColor);
}

But in order to customize any "idle" part of the notched-outline, you must use the .foo__parent CSS selector:

.foo__parent {
  @include mdc-notched-outline-idle-color($fooColor);
}

MDCNotchedOutline Properties and Methods

Method Signature	Description
notch(notchWidth: number, isRtl: boolean) => void	Updates notched outline to open notch in outline path.
closeNotch() => void	Updates the notched outline to close notch in outline path.

Usage Within Frameworks

If 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.

MDCNotchedOutlineAdapter

Method Signature	Description
getWidth() => number	Returns the width of the notched outline element.
getHeight() => number	Returns the height of the notched outline element.
addClass(className: string) => void	Adds a class to the notched outline element.
removeClass(className: string) => void	Removes a class from the notched outline element.
setOutlinePathAttr(value: string) => void	Sets the "d" attribute of the notched outline element's SVG path.
getIdleOutlineStyleValue(propertyName: string) => string	Returns the idle outline element's computed style value of a given css propertyName.

MDCNotchedOutlineFoundation

Method Signature	Description
notch(notchWidth: number, isRtl: boolean) => void	Adds the mdc-notched-outline--notched selector and updates the notched outline path based off notchWidth and isRtl.
closeNotch() => void	Removes the outline notched selector.
updateSvgPath(notchWidth: number, isRtl: boolean) => void	Updates the SVG path of the focus outline element calculated based off of the notchWidth. The notch will appear left justified, unless isRtl is true.