docs-bug(button): `iconPositionEnd` directive is not documented

[hakimio]

Documentation Feedback

New iconPositionEnd directive is mentioned in the migration guide but I did not find any mention of it in mat-button or mat-icon documentation.

Affected documentation page

https://material.angular.io/components/button/overview

[crisbeto]

Also worth noting that we should mention a similar matMenuItemIcon from mat-menu.

[DmitryEfimenko]

by the way, this was a breaking change since in the previous version the directive was not needed in order for the icon to be at the end:

<button mat-raised-button>
  <mat-icon>favorite</mat-icon>
  Primary
  <mat-icon>favorite</mat-icon>
</button>

Not sure what the purpose of this code:

<ng-content select=".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])">
</ng-content>

<span class="mdc-button__label"><ng-content></ng-content></span>

<ng-content select=".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]">
</ng-content>

I can see that it separates icons from the rest of the label, but not sure why.

[rb-mwindh]

I know this thread is ~3 years old, but since it’s still open, I thought some additional input might be welcome.

Both [iconPositionEnd] and [matButtonIcon] aren’t Angular directives in the traditional sense — they’re simply CSS Attribute Selectors used to designate content for Multi-slot content projection.

@DmitryEfimenko:

You mentioned you weren’t sure why the icons have been separated from the labels. I believe the reason is to avoid having unwrapped text nodes alongside elements — a situation known as XML mixed content.

The issue with XML mixed content is that CSS cannot select unwrapped text nodes (though there’s ongoing discussion about this limitation). Mixed content can be very challenging when it comes to applying styles to an element.

There are two straightforward solutions to this problem:

• Wrap unwrapped text nodes in a <span>
• Use dedicated content projection selectors

That being said, I should note that both selectors ([matButtonIcon] and [iconPositionEnd]) remain undocumented features as of Angular Material v19.