Symbol Glyph (SymbolGlyph/SymbolSpan)

SymbolGlyph is a component designed for icon glyphs, making it easy to use sophisticated icons, including multi-colored and animated icons. You can add symbol glyphs in text through the use of the SymbolSpan component, a child of the Text component. For details, see SymbolGlyph and SymbolSpan.

Creating a Symbol Glyph

You create a symbol glyph by referencing a resource through $r. Currently, only the preset symbol resources are supported.

SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .fontSize(96)
  .renderingStrategy(SymbolRenderingStrategy.SINGLE)
  .fontColor([Color.Black, Color.Green, Color.White])

CreatSymbolGlyph.ets

symbol_folder_badge_plus

Adding to Text

To embed a symbol glyph within a text string, use SymbolSpan as a child of the Text component. You can nest multiple SymbolSpan components to display a series of symbol glyphs.

Create a SymbolSpan component.

A SymbolSpan component is only visible when embedded within a Text component. Using a SymbolSpan independently displays no content.
```
Text() {
  SymbolSpan($r('sys.symbol.ohos_trash'))
    .fontWeight(FontWeight.Normal)
    .fontSize(96)
}
```
SymbolAddToText.ets

Set the size of the SymbolSpan component through fontSize.

Row() {
  Column() {
    Text('48')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(48)
        .renderingStrategy(SymbolRenderingStrategy.SINGLE)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }

  Column() {
    Text('72')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(72)
        .renderingStrategy(SymbolRenderingStrategy.SINGLE)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }

  Column() {
    Text('96')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .renderingStrategy(SymbolRenderingStrategy.SINGLE)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }
}

SymbolAddToText.ets

symbolSpan_multi_fontSize

Set the weight of the SymbolSpan component through fontWeight.

Row() {
  Column() {
    Text('Light')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_trash'))
        .fontWeight(FontWeight.Lighter)
        .fontSize(96)
    }
  }

  Column() {
    Text('Normal')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_trash'))
        .fontWeight(FontWeight.Normal)
        .fontSize(96)
    }
  }

  Column() {
    Text('Bold')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_trash'))
        .fontWeight(FontWeight.Bold)
        .fontSize(96)
    }
  }
}

SymbolAddToText.ets

symbolSpan_multi_fontWeight_trash

Set the color of the SymbolSpan component through fontColor.

Row() {
  Column() {
    Text('Black')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .fontColor([Color.Black])
    }
  }

  Column() {
    Text('Green')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .fontColor([Color.Green])
    }
  }

  Column() {
    Text('Pink')
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .fontColor([Color.Pink])
    }
  }
}

SymbolAddToText.ets

symbolSpan_multi_fontColor

Set the rendering strategy of the SymbolSpan component through renderingStrategy.

Row() {
  Column() {
    // Replace $r('app.string.single_color') with the actual resource file. In this example, the value in the resource file is "Single-color mode."
    Text($r('app.string.single_color'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .renderingStrategy(SymbolRenderingStrategy.SINGLE)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }

  Column() {
    // Replace $r('app.string.multi_color') with the actual resource file. In this example, the value in the resource file is "Multi-color mode."
    Text($r('app.string.multi_color'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }

  Column() {
    // Replace $r('app.string.hierarchical') with the actual resource file. In this example, the value in the resource file is "Layered mode."
    Text($r('app.string.hierarchical'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
        .fontSize(96)
        .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_OPACITY)
        .fontColor([Color.Black, Color.Green, Color.White])
    }
  }
}

SymbolAddToText.ets

symbolSpan_multi_renderingStrategy

Set the effect strategy of the SymbolSpan component through effectStrategy.

Row() {
  Column() {
    // Replace $r('app.string.no_action') with the actual resource file. In this example, the value in the resource file is "No effect."
    Text($r('app.string.no_action'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_wifi'))
        .fontSize(96)
        .effectStrategy(SymbolEffectStrategy.NONE)
    }
  }

  Column() {
    // Replace $r('app.string.overall_scaling_animation_effect') with the actual resource file. In this example, the value in the resource file is "Overall scale effect."
    Text($r('app.string.overall_scaling_animation_effect'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_wifi'))
        .fontSize(96)
        .effectStrategy(SymbolEffectStrategy.SCALE)
    }
  }

  Column() {
    // Replace $r('app.string.hierarchical_animation') with the actual resource file. In this example, the value in the resource file is "Hierarchical effect."
    Text($r('app.string.hierarchical_animation'));
    Text() {
      SymbolSpan($r('sys.symbol.ohos_wifi'))
        .fontSize(96)
        .effectStrategy(SymbolEffectStrategy.HIERARCHICAL)
    }
  }
}

SymbolAddToText.ets

symbolSpan_multi_effectStrategy

SymbolSpan does not support universal events.

Customizing Symbol Glyph Animations

In addition to using the effectStrategy attribute, which triggers an animation once it is activated, you can control the animation playback and choose from a variety of effect strategies using the following two methods.

For details about how effectStrategy works with symbolEffect, see SymbolGlyph.symbolEffect.

Use the symbolEffect attribute to set both the effect strategy and playback state of SymbolGlyph.

@State isActive: boolean = true;

SymbolCustomIconAnimation.ets

Column() {
  // Replace $r('app.string.variable_color_animation') with the actual resource file. In this example, the value in the resource file is "Variable color effect."
  Text($r('app.string.variable_color_animation'));
  SymbolGlyph($r('sys.symbol.ohos_wifi'))
    .fontSize(96)
    .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), this.isActive)
  // Replace $r('app.string.off') with the actual resource file. In this example, the value in the resource file is "Off."
  // Replace $r('app.string.on') with the actual resource file. In this example, the value in the resource file is "Play."
  Button(this.isActive ? $r('app.string.off') : $r('app.string.on')).onClick(() => {
    this.isActive = !this.isActive;
  })
}

SymbolCustomIconAnimation.ets

symbolGlyph_symbolEffect_isActive

Use the symbolEffect attribute to set both the effect strategy and the trigger for playback of SymbolGlyph.

@State triggerValueReplace: number = 0;

SymbolCustomIconAnimation.ets

Column() {
  // Replace $r('app.string.bounce_animation') with the actual resource file. In this example, the value in the resource file is "Bounce effect."
  Text($r('app.string.bounce_animation'));
  SymbolGlyph($r('sys.symbol.ellipsis_message_1'))
    .fontSize(96)
    .fontColor([Color.Gray])
    .symbolEffect(new BounceSymbolEffect(EffectScope.WHOLE, EffectDirection.UP),
                  this.triggerValueReplace)
  Button('trigger').onClick(() => {
    this.triggerValueReplace = this.triggerValueReplace + 1;
  })
}

SymbolCustomIconAnimation.ets

BounceSymbolEffect

Since API version 20, you can configure the slash overlay effect of SymbolGlyph and its trigger conditions by setting SymbolEffect to ReplaceSymbolEffect and specifying ReplaceEffectType as ReplaceEffectType.SLASH_OVERLAY.

@State triggerValueReplace: number = 0;
replaceFlag: boolean = true;
@State renderMode: number = 1;

SymbolCustomIconAnimation.ets

Column() {
  // Replace $r('app.string.disable_animation') with the actual resource file. In this example, the value in the resource file is "Slash overlay."
  Text($r('app.string.disable_animation'));
  SymbolGlyph(this.replaceFlag ? $r('sys.symbol.eye_slash') : $r('sys.symbol.eye'))
    .fontSize(96)
    .renderingStrategy(this.renderMode)
    .symbolEffect(new ReplaceSymbolEffect(EffectScope.LAYER, ReplaceEffectType.SLASH_OVERLAY),
                  this.triggerValueReplace)
  Button('trigger').onClick(() => {
    this.replaceFlag = !this.replaceFlag;
    this.triggerValueReplace = this.triggerValueReplace + 1;
  })
}

SymbolCustomIconAnimation.ets

symbolGlyph_symbolEffect_disable

Since API version 20, you can configure the cross-fade transition effect of SymbolGlyph and its trigger conditions by setting SymbolEffect to ReplaceSymbolEffect and specifying ReplaceEffectType as ReplaceEffectType.CROSS_FADE.

@State triggerValueReplace: number = 0;
replaceFlag: boolean = true;

SymbolCustomIconAnimation.ets

Column() {
  // Replace $r('app.string.quick_replacement_animation') with the actual resource file. In this example, the value in the resource file is "Cross-fade transition."
  Text($r('app.string.quick_replacement_animation'));
  SymbolGlyph(this.replaceFlag ? $r('sys.symbol.checkmark_circle') : $r('sys.symbol.repeat_1'))
    .fontSize(96)
    .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE, ReplaceEffectType.CROSS_FADE),
                  this.triggerValueReplace)
  Button('trigger').onClick(() => {
    this.replaceFlag = !this.replaceFlag;
    this.triggerValueReplace = this.triggerValueReplace + 1;
  })
}

SymbolCustomIconAnimation.ets

symbolGlyph_symbolEffect_quick_replace

Setting Shadow and Gradient Color Effects

Since API version 20, you can apply shadow effects to the SymbolGlyph component using the symbolShadow API.

@State isActive: boolean = true;

options: ShadowOptions = {
  radius: 10.0,
  color: Color.Blue,
  offsetX: 10,
  offsetY: 10,
};

SymbolShadowAndColor.ets

Column() {
  // Replace $r('app.string.shadow_ability') with the actual resource file. In this example, the value in the resource file is "Shadow effect."
  Text($r('app.string.shadow_ability'));
  SymbolGlyph($r('sys.symbol.ohos_wifi'))
    .fontSize(96)
    .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), !this.isActive)
    .symbolShadow(this.options)
  // Replace $r('app.string.off') with the actual resource file. In this example, the value in the resource file is "Off."
  // Replace $r('app.string.on') with the actual resource file. In this example, the value in the resource file is "Play."
  Button(!this.isActive ? $r('app.string.off') : $r('app.string.on')).onClick(() => {
    this.isActive = !this.isActive;
  })
}

SymbolShadowAndColor.ets

SymbolShadowSymbolEffect

Since API version 20, you can implement gradient color effects for the SymbolGlyph component using the shaderStyle API.

radialGradientOptions: RadialGradientOptions = {
  center: ['50%', '50%'],
  radius: '20%',
  colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]],
  repeating: true,
};

SymbolShadowAndColor.ets

Column() {
  // Replace $r('app.string.radial_gradient') with the actual resource file. In this example, the value in the resource file is "Radial gradient."
  Text($r('app.string.radial_gradient'))
    .fontSize(18)
    .fontColor(0xCCCCCC)
    .textAlign(TextAlign.Center)
  SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
    .fontSize(96)
    .shaderStyle([new RadialGradientStyle(this.radialGradientOptions)])
}

SymbolShadowAndColor.ets

ShaderStyleSymbolEffect

Adding Events

You can add universal events, such as onClick and onTouch, to the SymbolGlyph component to handle user interactions.

@State wifiColor: ResourceColor = Color.Black;

SymbolAddEvent.ets

SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .fontSize(96)
  .fontColor([this.wifiColor])
  .onClick(() => {
    this.wifiColor = Color.Gray;
  })

SymbolAddEvent.ets

symbolGlyph_onClick

Example

This example shows how to implement a playlist with the use of symbolEffect, fontSize, and fontColor.

// resourceGetString is a utility function for retrieving string resources from the application's resource directory.
import resourceGetString from '../../common/resource';

@Entry
@Component
struct SymbolMusicDemo {
  @State triggerValueReplace: number = 0;
  @State symbolSources: Resource[] =
    [$r('sys.symbol.repeat'), $r('sys.symbol.repeat_1'), $r('sys.symbol.arrow_left_arrow_right')];
  @State symbolSourcesIndex: number = 0;
  @State symbolText: string[] = [
    // Replace $r('app.string.play_in_order') with the actual resource file. In this example, the value in the resource file is "Play in order."
    this.getUIContext()
      .getHostContext()!.resourceManager.getStringSync($r('app.string.play_in_order').id),
    // Replace $r('app.string.play_in_single_repeat') with the actual resource file. In this example, the value in the resource file is "Loop song."
    this.getUIContext()
      .getHostContext()!.resourceManager.getStringSync($r('app.string.play_in_single_repeat').id),
    // Replace $r('app.string.shuffle_play') with the actual resource file. In this example, the value in the resource file is "Shuffle."
    this.getUIContext()
      .getHostContext()!.resourceManager.getStringSync($r('app.string.shuffle_play').id),
  ];
  @State symbolTextIndex: number = 0;
  @State fontColorValue: ResourceColor = Color.Grey;
  @State fontColorValue1: ResourceColor = '#E8E8E8';

  build() {
    Column({ space: 10 }) {
      Row() {
        Text() {
          // Replace $r('app.string.current_playlist') with the actual resource file. In this example, the value in the resource file is "Playlist."
          Span(this.getUIContext()
            .getHostContext()!.resourceManager.getStringSync($r('app.string.current_playlist').id))
            .fontSize(20)
            .fontWeight(FontWeight.Bolder)
          Span('(101)')
        }
      }

      Row() {
        Row({ space: 5 }) {
          SymbolGlyph(this.symbolSources[this.symbolSourcesIndex])
            .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE), this.triggerValueReplace)
            .fontSize(20)
            .fontColor([this.fontColorValue])
          Text(this.symbolText[this.symbolTextIndex])
            .fontColor(this.fontColorValue)
        }
        .onClick(() => {
          this.symbolTextIndex++;
          this.symbolSourcesIndex++;
          this.triggerValueReplace++;
          if (this.symbolSourcesIndex > (this.symbolSources.length - 1)) {
            this.symbolSourcesIndex = 0;
            this.triggerValueReplace = 0;
          }
          if (this.symbolTextIndex > (this.symbolText.length - 1)) {
            this.symbolTextIndex = 0;
          }
        })
        .width('75%')

        Row({ space: 5 }) {
          Text() {
            SymbolSpan($r('sys.symbol.arrow_down_circle_badge_vip_circle_filled'))
              .fontColor([this.fontColorValue])
              .fontSize(20)
          }

          Text() {
            SymbolSpan($r('sys.symbol.heart_badge_plus'))
              .fontColor([this.fontColorValue])
              .fontSize(20)
          }

          Text() {
            SymbolSpan($r('sys.symbol.ohos_trash'))
              .fontColor([this.fontColorValue])
              .fontSize(20)
          }
        }
        .width('25%')
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.song') with the actual resource file. In this example, the value in the resource file is "Song 1."
          Text($r('app.string.song'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.song_again') with the actual resource file. In this example, the value in the resource file is "Song 2."
          Text($r('app.string.song_again'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.again_song') with the actual resource file. In this example, the value in the resource file is "Song 3."
          Text($r('app.string.again_song'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.song_repeat') with the actual resource file. In this example, the value in the resource file is "Song 4."
          Text($r('app.string.song_repeat'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.repeat_song') with the actual resource file. In this example, the value in the resource file is "Song 5."
          Text($r('app.string.repeat_song'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.song_play') with the actual resource file. In this example, the value in the resource file is "Song 6."
          Text($r('app.string.song_play'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Row() {
        Row() {
          // Replace $r('app.string.play_song') with the actual resource file. In this example, the value in the resource file is "Song 7."
          Text($r('app.string.play_song'))
        }.width('82%')

        Row({ space: 5 }) {
          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
          SymbolGlyph($r('sys.symbol.trash'))
            .fontColor([this.fontColorValue])
            .fontSize(20)
        }
      }

      Divider().width(5).color(this.fontColorValue1).width('98%')
      Column() {
        // Replace $r('app.string.off') with the actual resource file. In this example, the value in the resource file is "Close."
        Text($r('app.string.off'))
      }
      .alignItems(HorizontalAlign.Center)
      .width('98%')
    }
    .alignItems(HorizontalAlign.Start)
    .width('100%')
    .height(400)
    .padding({
      left: 10,
      top: 10
    })
  }
}

SymbolSceneExample.ets

symbol_scene_demo