creating-a-custom-form-field-control.html

<div class="docs-markdown"><h1>Creating a custom form field control</h1><p>It is possible to create custom form field controls that can be used inside <code>&lt;mat-form-field&gt;</code>. This
can be useful if you need to create a component that shares a lot of common behavior with a form
field, but adds some additional logic.</p>
<p>For example in this guide we&#39;ll learn how to create a custom input for inputting US telephone
numbers and hook it up to work with <code>&lt;mat-form-field&gt;</code>. Here is what we&#39;ll build by the end of this
guide:</p>
<div material-docs-example="form-field-custom-control"></div>

<p>In order to learn how to build custom form field controls, let&#39;s start with a simple input component
that we want to work inside the form field. For example, a phone number input that segments the
parts of the number into their own inputs. (Note: this is not intended to be a robust component,
just a starting point for us to learn.)</p>
<pre><code class="language-ts"><span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyTel</span> </span>{
  <span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params"><span class="hljs-keyword">public</span> area: <span class="hljs-built_in">string</span>, <span class="hljs-keyword">public</span> exchange: <span class="hljs-built_in">string</span>, <span class="hljs-keyword">public</span> subscriber: <span class="hljs-built_in">string</span></span>)</span> {}
}

<span class="hljs-meta">@Component</span>({
  <span class="hljs-attr">selector</span>: <span class="hljs-string">&#x27;example-tel-input&#x27;</span>,
  <span class="hljs-attr">template</span>: <span class="hljs-string">`
    &lt;div role=&quot;group&quot; [formGroup]=&quot;parts&quot;&gt;
      &lt;input class=&quot;area&quot; formControlName=&quot;area&quot; maxlength=&quot;3&quot;&gt;
      &lt;span&gt;&amp;ndash;&lt;/span&gt;
      &lt;input class=&quot;exchange&quot; formControlName=&quot;exchange&quot; maxlength=&quot;3&quot;&gt;
      &lt;span&gt;&amp;ndash;&lt;/span&gt;
      &lt;input class=&quot;subscriber&quot; formControlName=&quot;subscriber&quot; maxlength=&quot;4&quot;&gt;
    &lt;/div&gt;
  `</span>,
  <span class="hljs-attr">styles</span>: [<span class="hljs-string">`
    div {
      display: flex;
    }
    input {
      border: none;
      background: none;
      padding: 0;
      outline: none;
      font: inherit;
      text-align: center;
      color: currentColor;
    }
  `</span>],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyTelInput</span> </span>{
  <span class="hljs-attr">parts</span>: FormGroup;

  <span class="hljs-meta">@Input</span>()
  <span class="hljs-keyword">get</span> <span class="hljs-title">value</span>(): <span class="hljs-title">MyTel</span> | <span class="hljs-title">null</span> {
    <span class="hljs-keyword">let</span> n = <span class="hljs-built_in">this</span>.parts.value;
    <span class="hljs-keyword">if</span> (n.area.length == <span class="hljs-number">3</span> &amp;&amp; n.exchange.length == <span class="hljs-number">3</span> &amp;&amp; n.subscriber.length == <span class="hljs-number">4</span>) {
      <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> MyTel(n.area, n.exchange, n.subscriber);
    }
    <span class="hljs-keyword">return</span> <span class="hljs-literal">null</span>;
  }
  <span class="hljs-keyword">set</span> <span class="hljs-title">value</span>(<span class="hljs-params">tel: MyTel | <span class="hljs-literal">null</span></span>) {
    tel = tel || <span class="hljs-keyword">new</span> MyTel(<span class="hljs-string">&#x27;&#x27;</span>, <span class="hljs-string">&#x27;&#x27;</span>, <span class="hljs-string">&#x27;&#x27;</span>);
    <span class="hljs-built_in">this</span>.parts.setValue({<span class="hljs-attr">area</span>: tel.area, <span class="hljs-attr">exchange</span>: tel.exchange, <span class="hljs-attr">subscriber</span>: tel.subscriber});
  }

  <span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params">fb: FormBuilder</span>)</span> {
    <span class="hljs-built_in">this</span>.parts =  fb.group({
      <span class="hljs-string">&#x27;area&#x27;</span>: <span class="hljs-string">&#x27;&#x27;</span>,
      <span class="hljs-string">&#x27;exchange&#x27;</span>: <span class="hljs-string">&#x27;&#x27;</span>,
      <span class="hljs-string">&#x27;subscriber&#x27;</span>: <span class="hljs-string">&#x27;&#x27;</span>,
    });
  }
}
</code></pre>

        <h2 id="providing-our-component-as-a-matformfieldcontrol" class="docs-header-link">
          <span header-link="providing-our-component-as-a-matformfieldcontrol"></span>
          Providing our component as a MatFormFieldControl
        </h2>
      <p>The first step is to provide our new component as an implementation of the <code>MatFormFieldControl</code>
interface that the <code>&lt;mat-form-field&gt;</code> knows how to work with. To do this, we will have our class
implement <code>MatFormFieldControl</code>. Since this is a generic interface, we&#39;ll need to include a type
parameter indicating the type of data our control will work with, in this case <code>MyTel</code>. We then add
a provider to our component so that the form field will be able to inject it as a
<code>MatFormFieldControl</code>.</p>
<pre><code class="language-ts"><span class="hljs-meta">@Component</span>({
  ...
  <span class="hljs-attr">providers</span>: [{<span class="hljs-attr">provide</span>: MatFormFieldControl, <span class="hljs-attr">useExisting</span>: MyTelInput}],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyTelInput</span> <span class="hljs-title">implements</span> <span class="hljs-title">MatFormFieldControl</span>&lt;<span class="hljs-title">MyTel</span>&gt; </span>{
  ...
}
</code></pre>
<p>This sets up our component, so it can work with <code>&lt;mat-form-field&gt;</code>, but now we need to implement the
various methods and properties declared by the interface we just implemented. To learn more about
the <code>MatFormFieldControl</code> interface, see the
<a href="https://material.angular.io/components/form-field/api">form field API documentation</a>.</p>

        <h3 id="implementing-the-methods-and-properties-of-matformfieldcontrol" class="docs-header-link">
          <span header-link="implementing-the-methods-and-properties-of-matformfieldcontrol"></span>
          Implementing the methods and properties of MatFormFieldControl
        </h3>
      
        <h4 id="value" class="docs-header-link">
          <span header-link="value"></span>
          <code>value</code>
        </h4>
      <p>This property allows someone to set or get the value of our control. Its type should be the same
type we used for the type parameter when we implemented <code>MatFormFieldControl</code>. Since our component
already has a value property, we don&#39;t need to do anything for this one.</p>

        <h4 id="statechanges" class="docs-header-link">
          <span header-link="statechanges"></span>
          <code>stateChanges</code>
        </h4>
      <p>Because the <code>&lt;mat-form-field&gt;</code> uses the <code>OnPush</code> change detection strategy, we need to let it know
when something happens in the form field control that may require the form field to run change
detection. We do this via the <code>stateChanges</code> property. So far the only thing the form field needs to
know about is when the value changes. We&#39;ll need to emit on the stateChanges stream when that
happens, and as we continue flushing out these properties we&#39;ll likely find more places we need to
emit. We should also make sure to complete <code>stateChanges</code> when our component is destroyed.</p>
<pre><code class="language-ts">stateChanges = <span class="hljs-keyword">new</span> Subject&lt;<span class="hljs-built_in">void</span>&gt;();

<span class="hljs-keyword">set</span> <span class="hljs-title">value</span>(<span class="hljs-params">tel: MyTel | <span class="hljs-literal">null</span></span>) {
  ...
  <span class="hljs-built_in">this</span>.stateChanges.next();
}

<span class="hljs-function"><span class="hljs-title">ngOnDestroy</span>(<span class="hljs-params"></span>)</span> {
  <span class="hljs-built_in">this</span>.stateChanges.complete();
}
</code></pre>

        <h4 id="id" class="docs-header-link">
          <span header-link="id"></span>
          <code>id</code>
        </h4>
      <p>This property should return the ID of an element in the component&#39;s template that we want the
<code>&lt;mat-form-field&gt;</code> to associate all of its labels and hints with. In this case, we&#39;ll use the host
element and just generate a unique ID for it.</p>
<pre><code class="language-ts"><span class="hljs-keyword">static</span> nextId = <span class="hljs-number">0</span>;

<span class="hljs-meta">@HostBinding</span>() id = <span class="hljs-string">`example-tel-input-<span class="hljs-subst">${MyTelInput.nextId++}</span>`</span>;
</code></pre>

        <h4 id="placeholder" class="docs-header-link">
          <span header-link="placeholder"></span>
          <code>placeholder</code>
        </h4>
      <p>This property allows us to tell the <code>&lt;mat-form-field&gt;</code> what to use as a placeholder. In this
example, we&#39;ll do the same thing as <code>matInput</code> and <code>&lt;mat-select&gt;</code> and allow the user to specify it
via an <code>@Input()</code>. Since the value of the placeholder may change over time, we need to make sure to
trigger change detection in the parent form field by emitting on the <code>stateChanges</code> stream when the
placeholder changes.</p>
<pre><code class="language-ts"><span class="hljs-meta">@Input</span>()
<span class="hljs-keyword">get</span> <span class="hljs-title">placeholder</span>() {
  <span class="hljs-keyword">return</span> <span class="hljs-built_in">this</span>._placeholder;
}
<span class="hljs-keyword">set</span> <span class="hljs-title">placeholder</span>(<span class="hljs-params">plh</span>) {
  <span class="hljs-built_in">this</span>._placeholder = plh;
  <span class="hljs-built_in">this</span>.stateChanges.next();
}
<span class="hljs-keyword">private</span> _placeholder: <span class="hljs-built_in">string</span>;
</code></pre>

        <h4 id="ngcontrol" class="docs-header-link">
          <span header-link="ngcontrol"></span>
          <code>ngControl</code>
        </h4>
      <p>This property allows the form field control to specify the <code>@angular/forms</code> control that is bound
to this component. Since we haven&#39;t set up our component to act as a <code>ControlValueAccessor</code>, we&#39;ll
just set this to <code>null</code> in our component.</p>
<pre><code class="language-ts">ngControl: NgControl = <span class="hljs-literal">null</span>;
</code></pre>
<p>It is likely you will want to implement <code>ControlValueAccessor</code> so that your component can work with
<code>formControl</code> and <code>ngModel</code>. If you do implement <code>ControlValueAccessor</code> you will need to get a
reference to the <code>NgControl</code> associated with your control and make it publicly available.</p>
<p>The easy way is to add it as a public property to your constructor and let dependency injection
handle it:</p>
<pre><code class="language-ts"><span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params">
  ...,
  <span class="hljs-meta">@Optional</span>() <span class="hljs-meta">@Self</span>() <span class="hljs-keyword">public</span> ngControl: NgControl,
  ...,
</span>)</span> { }
</code></pre>
<p>Note that if your component implements <code>ControlValueAccessor</code>, it may already be set up to provide
<code>NG_VALUE_ACCESSOR</code> (in the <code>providers</code> part of the component&#39;s decorator, or possibly in a module
declaration). If so, you may get a <em>cannot instantiate cyclic dependency</em> error.</p>
<p>To resolve this, remove the <code>NG_VALUE_ACCESSOR</code> provider and instead set the value accessor directly:</p>
<pre><code class="language-ts"><span class="hljs-meta">@Component</span>({
  ...,
  <span class="hljs-attr">providers</span>: [
    ...,
    <span class="hljs-comment">// Remove this.</span>
    <span class="hljs-comment">// {</span>
    <span class="hljs-comment">//   provide: NG_VALUE_ACCESSOR,</span>
    <span class="hljs-comment">//   useExisting: forwardRef(() =&gt; MatFormFieldControl),</span>
    <span class="hljs-comment">//   multi: true,</span>
    <span class="hljs-comment">// },</span>
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyTelInput</span> <span class="hljs-title">implements</span> <span class="hljs-title">MatFormFieldControl</span>&lt;<span class="hljs-title">MyTel</span>&gt;, <span class="hljs-title">ControlValueAccessor</span> </span>{
  <span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params">
    ...,
    <span class="hljs-meta">@Optional</span>() <span class="hljs-meta">@Self</span>() <span class="hljs-keyword">public</span> ngControl: NgControl,
    ...,
  </span>)</span> {

    <span class="hljs-comment">// Replace the provider from above with this.</span>
    <span class="hljs-keyword">if</span> (<span class="hljs-built_in">this</span>.ngControl != <span class="hljs-literal">null</span>) {
      <span class="hljs-comment">// Setting the value accessor directly (instead of using</span>
      <span class="hljs-comment">// the providers) to avoid running into a circular import.</span>
      <span class="hljs-built_in">this</span>.ngControl.valueAccessor = <span class="hljs-built_in">this</span>;
    }
  }
}
</code></pre>
<p>For additional information about <code>ControlValueAccessor</code> see the <a href="https://angular.io/api/forms/ControlValueAccessor">API docs</a>.</p>

        <h4 id="focused" class="docs-header-link">
          <span header-link="focused"></span>
          <code>focused</code>
        </h4>
      <p>This property indicates whether the form field control should be considered to be in a
focused state. When it is in a focused state, the form field is displayed with a solid color
underline. For the purposes of our component, we want to consider it focused if any of the part
inputs are focused. We can use the <code>focusin</code> and <code>focusout</code> events to easily check this. We also
need to remember to emit on the <code>stateChanges</code> when the focused stated changes stream so change
detection can happen.</p>
<p>In addition to updating the focused state, we use the <code>focusin</code> and <code>focusout</code> methods to update the
internal touched state of our component, which we&#39;ll use to determine the error state.</p>
<pre><code class="language-ts">focused = <span class="hljs-literal">false</span>;

<span class="hljs-function"><span class="hljs-title">onFocusIn</span>(<span class="hljs-params">event: FocusEvent</span>)</span> {
  <span class="hljs-keyword">if</span> (!<span class="hljs-built_in">this</span>.focused) {
    <span class="hljs-built_in">this</span>.focused = <span class="hljs-literal">true</span>;
    <span class="hljs-built_in">this</span>.stateChanges.next();
  }
}

<span class="hljs-function"><span class="hljs-title">onFocusOut</span>(<span class="hljs-params">event: FocusEvent</span>)</span> {
  <span class="hljs-keyword">if</span> (!<span class="hljs-built_in">this</span>._elementRef.nativeElement.contains(event.relatedTarget <span class="hljs-keyword">as</span> Element)) {
    <span class="hljs-built_in">this</span>.touched = <span class="hljs-literal">true</span>;
    <span class="hljs-built_in">this</span>.focused = <span class="hljs-literal">false</span>;
    <span class="hljs-built_in">this</span>.onTouched();
    <span class="hljs-built_in">this</span>.stateChanges.next();
  }
}
</code></pre>

        <h4 id="empty" class="docs-header-link">
          <span header-link="empty"></span>
          <code>empty</code>
        </h4>
      <p>This property indicates whether the form field control is empty. For our control, we&#39;ll consider it
empty if all the parts are empty.</p>
<pre><code class="language-ts"><span class="hljs-keyword">get</span> <span class="hljs-title">empty</span>() {
  <span class="hljs-keyword">let</span> n = <span class="hljs-built_in">this</span>.parts.value;
  <span class="hljs-keyword">return</span> !n.area &amp;&amp; !n.exchange &amp;&amp; !n.subscriber;
}
</code></pre>

        <h4 id="shouldlabelfloat" class="docs-header-link">
          <span header-link="shouldlabelfloat"></span>
          <code>shouldLabelFloat</code>
        </h4>
      <p>This property is used to indicate whether the label should be in the floating position. We&#39;ll
use the same logic as <code>matInput</code> and float the placeholder when the input is focused or non-empty.
Since the placeholder will be overlapping our control when it&#39;s not floating, we should hide
the <code>–</code> characters when it&#39;s not floating.</p>
<pre><code class="language-ts"><span class="hljs-meta">@HostBinding</span>(<span class="hljs-string">&#x27;class.floating&#x27;</span>)
<span class="hljs-keyword">get</span> <span class="hljs-title">shouldLabelFloat</span>() {
  <span class="hljs-keyword">return</span> <span class="hljs-built_in">this</span>.focused || !<span class="hljs-built_in">this</span>.empty;
}
</code></pre>
<pre><code class="language-css"><span class="hljs-selector-tag">span</span> {
  <span class="hljs-attribute">opacity</span>: <span class="hljs-number">0</span>;
  <span class="hljs-attribute">transition</span>: opacity <span class="hljs-number">200ms</span>;
}
<span class="hljs-selector-pseudo">:host</span><span class="hljs-selector-class">.floating</span> <span class="hljs-selector-tag">span</span> {
  <span class="hljs-attribute">opacity</span>: <span class="hljs-number">1</span>;
}
</code></pre>

        <h4 id="required" class="docs-header-link">
          <span header-link="required"></span>
          <code>required</code>
        </h4>
      <p>This property is used to indicate whether the input is required. <code>&lt;mat-form-field&gt;</code> uses this
information to add a required indicator to the placeholder. Again, we&#39;ll want to make sure we run
change detection if the required state changes.</p>
<pre><code class="language-ts"><span class="hljs-meta">@Input</span>()
<span class="hljs-keyword">get</span> <span class="hljs-title">required</span>() {
  <span class="hljs-keyword">return</span> <span class="hljs-built_in">this</span>._required;
}
<span class="hljs-keyword">set</span> <span class="hljs-title">required</span>(<span class="hljs-params">req: BooleanInput</span>) {
  <span class="hljs-built_in">this</span>._required = coerceBooleanProperty(req);
  <span class="hljs-built_in">this</span>.stateChanges.next();
}
<span class="hljs-keyword">private</span> _required = <span class="hljs-literal">false</span>;
</code></pre>

        <h4 id="disabled" class="docs-header-link">
          <span header-link="disabled"></span>
          <code>disabled</code>
        </h4>
      <p>This property tells the form field when it should be in the disabled state. In addition to reporting
the right state to the form field, we need to set the disabled state on the individual inputs that
make up our component.</p>
<pre><code class="language-ts"><span class="hljs-meta">@Input</span>()
<span class="hljs-keyword">get</span> <span class="hljs-title">disabled</span>(): <span class="hljs-title">boolean</span> { <span class="hljs-keyword">return</span> <span class="hljs-built_in">this</span>._disabled; }
<span class="hljs-keyword">set</span> <span class="hljs-title">disabled</span>(<span class="hljs-params">value: BooleanInput</span>) {
  <span class="hljs-built_in">this</span>._disabled = coerceBooleanProperty(value);
  <span class="hljs-built_in">this</span>._disabled ? <span class="hljs-built_in">this</span>.parts.disable() : <span class="hljs-built_in">this</span>.parts.enable();
  <span class="hljs-built_in">this</span>.stateChanges.next();
}
<span class="hljs-keyword">private</span> _disabled = <span class="hljs-literal">false</span>;
</code></pre>

        <h4 id="errorstate" class="docs-header-link">
          <span header-link="errorstate"></span>
          <code>errorState</code>
        </h4>
      <p>This property indicates whether the associated <code>NgControl</code> is in an error state. For example,
we can show an error if the input is invalid and our component has been touched.</p>
<pre><code class="language-ts"><span class="hljs-keyword">get</span> <span class="hljs-title">errorState</span>(): <span class="hljs-title">boolean</span> {
  <span class="hljs-keyword">return</span> <span class="hljs-built_in">this</span>.parts.invalid &amp;&amp; <span class="hljs-built_in">this</span>.touched;
}
</code></pre>
<p>However, there are some error triggers that we can&#39;t subscribe to (e.g. parent form submissions),
to handle such cases we should re-evaluate <code>errorState</code> on every change detection cycle.</p>
<pre><code class="language-ts"><span class="hljs-comment">/** Whether the component is in an error state. */</span>
<span class="hljs-attr">errorState</span>: <span class="hljs-built_in">boolean</span> = <span class="hljs-literal">false</span>;

<span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params">
  ...,
  <span class="hljs-meta">@Optional</span>() <span class="hljs-keyword">private</span> _parentForm: NgForm,
  <span class="hljs-meta">@Optional</span>() <span class="hljs-keyword">private</span> _parentFormGroup: FormGroupDirective
</span>)</span> {
...
}

<span class="hljs-function"><span class="hljs-title">ngDoCheck</span>(<span class="hljs-params"></span>)</span> {
  <span class="hljs-keyword">if</span> (<span class="hljs-built_in">this</span>.ngControl) {
    <span class="hljs-built_in">this</span>.updateErrorState();
  }
}

<span class="hljs-keyword">private</span> <span class="hljs-function"><span class="hljs-title">updateErrorState</span>(<span class="hljs-params"></span>)</span> {
  <span class="hljs-keyword">const</span> parent = <span class="hljs-built_in">this</span>._parentFormGroup || <span class="hljs-built_in">this</span>.parentForm;

  <span class="hljs-keyword">const</span> oldState = <span class="hljs-built_in">this</span>.errorState;
  <span class="hljs-keyword">const</span> newState = (<span class="hljs-built_in">this</span>.ngControl?.invalid || <span class="hljs-built_in">this</span>.parts.invalid) &amp;&amp; (<span class="hljs-built_in">this</span>.touched || parent.submitted);

  <span class="hljs-keyword">if</span> (oldState !== newState) {
    <span class="hljs-built_in">this</span>.errorState = newState;
    <span class="hljs-built_in">this</span>.stateChanges.next();
  }
}
</code></pre>
<p>Keep in mind that <code>updateErrorState()</code> must have minimal logic to avoid performance issues.</p>

        <h4 id="controltype" class="docs-header-link">
          <span header-link="controltype"></span>
          <code>controlType</code>
        </h4>
      <p>This property allows us to specify a unique string for the type of control in form field. The
<code>&lt;mat-form-field&gt;</code> will add a class based on this type that can be used to easily apply
special styles to a <code>&lt;mat-form-field&gt;</code> that contains a specific type of control. In this example
we&#39;ll use <code>example-tel-input</code> as our control type which will result in the form field adding the
class <code>mat-form-field-type-example-tel-input</code>.</p>
<pre><code class="language-ts">controlType = <span class="hljs-string">&#x27;example-tel-input&#x27;</span>;
</code></pre>
          <h4 id="autofilled" class="docs-header-link">
    <span header-link="autofilled"></span>
    <code>autofilled</code>
  </h4>
  <p>This property allows us to specify Whether the input is currently in an autofilled state.
    If set true it will add <code>mat-form-field-autofilled</code> class to the <code>&lt;mat-form-field&gt;</code>,
     If property is not present on the control it is assumed to be false.
  <pre><code class="language-ts">autofilled = <span class="hljs-string">true | false</span>;
  </code></pre>

          <h4 id="userAriaDescribedBy" class="docs-header-link">
    <span header-link="userAriaDescribedBy"></span>
    <code>userAriaDescribedBy</code>
  </h4>
  <p>This property allows us to specify the Value 
    of <code>aria-describedby</code> that should be merged with the described-by ids which are set by the form-field.
  <pre><code class="language-ts">userAriaDescribedBy = <span class="hljs-string">&#x27;id&#x27 | &#x27space-separated list of element ids&#x27;</span>;
  </code></pre>
  
        <h4 id="setdescribedbyidsids-string" class="docs-header-link">
          <span header-link="setdescribedbyidsids-string"></span>
          <code>setDescribedByIds(ids: string[])</code>
        </h4>
      <p>This method is used by the <code>&lt;mat-form-field&gt;</code> to set element ids that should be used for the
<code>aria-describedby</code> attribute of your control. The ids are controlled through the form field
as hints or errors are conditionally displayed and should be reflected in the control&#39;s
<code>aria-describedby</code> attribute for an improved accessibility experience. </p>
<p>The <code>setDescribedByIds</code> method is invoked whenever the control&#39;s state changes. Custom controls
need to implement this method and update the <code>aria-describedby</code> attribute based on the specified
element ids. Below is an example that shows how this can be achieved.</p>
<p>Note that the method by default will not respect element ids that have been set manually on the
control element through the <code>aria-describedby</code> attribute. To ensure that your control does not
accidentally override existing element ids specified by consumers of your control, create an
input called <code>userAriaDescribedby</code>  like followed:</p>
<pre><code class="language-ts"><span class="hljs-meta">@Input</span>(<span class="hljs-string">&#x27;aria-describedby&#x27;</span>) userAriaDescribedBy: <span class="hljs-built_in">string</span>;
</code></pre>
<p>The form field will then pick up the user specified <code>aria-describedby</code> ids and merge
them with ids for hints or errors whenever <code>setDescribedByIds</code> is invoked.</p>
<pre><code class="language-ts"><span class="hljs-function"><span class="hljs-title">setDescribedByIds</span>(<span class="hljs-params">ids: <span class="hljs-built_in">string</span>[]</span>)</span> {
  <span class="hljs-keyword">const</span> controlElement = <span class="hljs-built_in">this</span>._elementRef.nativeElement
    .querySelector(<span class="hljs-string">&#x27;.example-tel-input-container&#x27;</span>)!;
  controlElement.setAttribute(<span class="hljs-string">&#x27;aria-describedby&#x27;</span>, ids.join(<span class="hljs-string">&#x27; &#x27;</span>));
}
</code></pre>

        <h4 id="oncontainerclickevent-mouseevent" class="docs-header-link">
          <span header-link="oncontainerclickevent-mouseevent"></span>
          <code>onContainerClick(event: MouseEvent)</code>
        </h4>
      <p>This method will be called when the form field is clicked on. It allows your component to hook in
and handle that click however it wants. The method has one parameter, the <code>MouseEvent</code> for the
click. In our case we&#39;ll just focus the first <code>&lt;input&gt;</code> if the user isn&#39;t about to click an
<code>&lt;input&gt;</code> anyways.</p>
<pre><code class="language-ts"><span class="hljs-function"><span class="hljs-title">onContainerClick</span>(<span class="hljs-params">event: MouseEvent</span>)</span> {
  <span class="hljs-keyword">if</span> ((event.target <span class="hljs-keyword">as</span> Element).tagName.toLowerCase() != <span class="hljs-string">&#x27;input&#x27;</span>) {
    <span class="hljs-built_in">this</span>._elementRef.nativeElement.querySelector(<span class="hljs-string">&#x27;input&#x27;</span>).focus();
  }
}
</code></pre>

        <h3 id="improving-accessibility" class="docs-header-link">
          <span header-link="improving-accessibility"></span>
          Improving accessibility
        </h3>
      <p>Our custom form field control consists of multiple inputs that describe segments of a phone
number. For accessibility purposes, we put those inputs as part of a <code>div</code> element with
<code>role=&quot;group&quot;</code>. This ensures that screen reader users can tell that all those inputs belong
together.</p>
<p>One significant piece of information is missing for screen reader users though. They won&#39;t be able
to tell what this input group represents. To improve this, we should add a label for the group
element using either <code>aria-label</code> or <code>aria-labelledby</code>.</p>
<p>It&#39;s recommended to link the group to the label that is displayed as part of the parent
<code>&lt;mat-form-field&gt;</code>. This ensures that explicitly specified labels (using <code>&lt;mat-label&gt;</code>) are
actually used for labelling the control.</p>
<p>In our concrete example, we add an attribute binding for <code>aria-labelledby</code> and bind it
to the label element id provided by the parent <code>&lt;mat-form-field&gt;</code>.</p>
<pre><code class="language-typescript"><span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyTelInput</span> <span class="hljs-title">implements</span> <span class="hljs-title">MatFormFieldControl</span>&lt;<span class="hljs-title">MyTel</span>&gt; </span>{
  ...

  <span class="hljs-function"><span class="hljs-title">constructor</span>(<span class="hljs-params">...
              <span class="hljs-meta">@Optional</span>() <span class="hljs-keyword">public</span> parentFormField: MatFormField</span>)</span> {
</code></pre>
<pre><code class="language-html">@Component({
  selector: &#x27;example-tel-input&#x27;,
  template: `
    <span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">role</span>=<span class="hljs-string">&quot;group&quot;</span> [<span class="hljs-attr">formGroup</span>]=<span class="hljs-string">&quot;parts&quot;</span>
         [<span class="hljs-attr">attr.aria-describedby</span>]=<span class="hljs-string">&quot;describedBy&quot;</span>
         [<span class="hljs-attr">attr.aria-labelledby</span>]=<span class="hljs-string">&quot;parentFormField?.getLabelId()&quot;</span>&gt;</span>
</code></pre>

        <h3 id="trying-it-out" class="docs-header-link">
          <span header-link="trying-it-out"></span>
          Trying it out
        </h3>
      <p>Now that we&#39;ve fully implemented the interface, we&#39;re ready to try our component out! All we need to
do is place it inside a <code>&lt;mat-form-field&gt;</code></p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">mat-form-field</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">example-tel-input</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">example-tel-input</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">mat-form-field</span>&gt;</span>
</code></pre>
<p>We also get all the features that come with <code>&lt;mat-form-field&gt;</code> such as floating placeholder,
prefix, suffix, hints, and errors (if we&#39;ve given the form field an <code>NgControl</code> and correctly report
the error state).</p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">mat-form-field</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">example-tel-input</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;Phone number&quot;</span> <span class="hljs-attr">required</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">example-tel-input</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">mat-icon</span> <span class="hljs-attr">matPrefix</span>&gt;</span>phone<span class="hljs-tag">&lt;/<span class="hljs-name">mat-icon</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">mat-hint</span>&gt;</span>Include area code<span class="hljs-tag">&lt;/<span class="hljs-name">mat-hint</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">mat-form-field</span>&gt;</span>
</code></pre>
</div>