Icon

Material Symbols icon wrapper with variant, size, color, and font variation controls. Not intended to replace text labels for critical actions without accessible naming.

Basic Usage

Render an outlined icon using the icon name. The wrapper standardizes symbol style and sizing with MD3 tokens. 

<ds-icon name="favorite"></ds-icon>

Initial Value

Set icon style and accessibility label through attributes.

<ds-icon
  name="settings"
  variant="rounded"
  size="large"
  label="Settings">
</ds-icon>

Variants

Switch icon glyph style using the variant attribute. 

<ds-icon name="star" variant="outlined"></ds-icon>
<ds-icon name="star" variant="filled"></ds-icon>
<ds-icon name="star" variant="rounded"></ds-icon>
<ds-icon name="star" variant="sharp"></ds-icon>

Sizes

<ds-icon name="favorite" size="small"></ds-icon>
<ds-icon name="favorite" size="medium"></ds-icon>
<ds-icon name="favorite" size="large"></ds-icon>
<ds-icon name="favorite" size="xlarge"></ds-icon>

States

Use animation host attributes and color overrides as needed.

<ds-icon name="sync" spin label="Syncing"></ds-icon>
<ds-icon name="notifications" pulse color="var(--md-sys-color-error)"></ds-icon>

Interactive Example

Change icon name, variant, and size to preview configuration.

API

Attributes

Attribute Type Default Description
name string "" Material Symbol icon name.
variant string outlined outlined, filled, rounded, sharp.
size string | number medium small, medium, large, xlarge, or custom pixel number.
color string currentColor Icon color value.
weight number 400 Font weight from 100-700.
grade number 0 Grade from -25 to 200.
fill number 0 Fill state: 0 or 1.
optical-size number size-based Optical size from 20-48.
label string "" Accessible label for meaningful icons.

Properties

Property Type Description
name string Icon name.
variant string Icon variant.
size string Icon size token or numeric string.
color string Icon color.
weight number Font weight.
grade number Font grade.
fill number Fill setting.
opticalSize number Optical size.
label string Accessible label.

Events

Event Detail Description
None N/A This component does not emit custom events.

Methods

Method Description
getSizeConfig() Returns computed CSS/px size mapping.
getVariantClass() Returns Material Symbols class for current variant.
getFontVariationSettings() Builds font variation settings string.

CSS Parts

Part Description
icon Inner span containing glyph text.

CSS Custom Properties

Property Description
--ds-icon-size-small Small icon size token mapping.
--ds-icon-size-medium Medium icon size token mapping.
--ds-icon-size-large Large icon size token mapping.
--ds-icon-size-xlarge Extra-large icon size token mapping.
--icon-font-family Material Symbols font family override.

Accessibility

  • Decorative icons are hidden with aria-hidden="true".
  • Meaningful icons should provide label to expose role="img" and aria-label.
  • Color inherits from currentColor by default to support contrast themes.

Usage Guidelines

  • Prefer commonly recognized symbols for faster comprehension.
  • Always pair critical actions with visible text labels.
  • Use animation attributes (`spin`, `pulse`) sparingly for state emphasis.
  • Use consistent icon size tokens within a given layout area.