We recommend using Visual Studio 2017
This documentation is archived and is not being maintained.

How to: Add Icons to Commands on Toolbars

Commands can appear on both menus and toolbars. On toolbars, it is common for a command to be displayed with just an icon (to save space) while on menus a command typically appears with both an icon and text.

Icons are 16 pixels wide by 16 pixels high and can be either 8-bit color depth (256 colors) or 32-bit color depth (true color). 32-bit color icons are preferred. Icons are typically arranged in a single horizontal row in a single bitmap, although multiple bitmaps are allowed. This bitmap is declared in the .vsct file along with the individual icons available in the bitmap. See the reference for the Bitmaps Element for more details.

To add an icon to a command

  1. Create a bitmap with a color depth of 32-bits. An icon is always 16 x 16 so this bitmap must be 16 pixels high and a multiple of 16 pixels wide.

    Each icon is placed on the bitmap next to each other in a single row. Use the alpha channel to indicate places of transparency in each icon.

    If you use an 8-bit color depth, use magenta, RGB(255,0,255), as the transparency. However, 32-bit color icons are preferred.

  2. Open the .vsct file in the editor.

  3. In the Symbols Element, find the GuidSymbol Element that contains your existing bitmap entries. By default, it is named guidImages.

    The following example shows the default <GuidSymbol> element generated by the Visual Studio Package Template.

    <GuidSymbol name="guidImages" value="{7f2b0178-a581-424f-933f-f6da41774269}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
  4. Add an IDSymbol Element for each icon in your bitmap. The name attribute is the icon's ID, and the value indicates its position on the strip.

  5. Create a Bitmap Element in the <Bitmaps> section of the .vsct file to represent the bitmap containing the icons.

    • Set the guid value to the name of the <GuidSymbol> element that contains your bitmap declarations.

    • Set the href attribute to the relative path of the bitmap file, or set the resID attribute to an integer resource, set elsewhere in the package, that refers to the desired bitmaps.

    • You can improve performance by setting the usedList attribute to a comma-delimited list of the icons to be used in the VSPackage. Icons not on the list will be excluded form compilation. You must specify a usedList if using a resID instead of an href.

    The following example shows the default entry created by the package template.

    <Bitmap guid="guidImages" 
            usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
  6. Create a Button Element in the Buttons Element or use an existing entry.

    • Inside the <Button> element, add an Icon Element and set its guid and id attributes the GUID:ID of one of the icons in your bitmap.

    • If desired, add one of the following flags to the button definition as a Command Flag Element:

      IconAndText: Both the icon and the button text are displayed in the menu and toolbar.

      Pict: Only the icon of the command is shown on a toolbar while only the text of the command is shown on a menu. If an icon is not specified, a blank space is shown on a toolbar.

      TextOnly: only the text of the command is shown on a toolbar or a menu. The <Icon> element is ignored.

      For more information on command flags, see the <CommandFlag> Element documentation.