Use custom tags for presentations, slides, and shapes in PowerPoint
Article
An add-in can attach custom metadata, in the form of key-value pairs, called "tags", to presentations, specific slides, and specific shapes on a slide.
There are two main scenarios for using tags:
When applied to a slide or a shape, a tag enables the object to be categorized for batch processing. For example, suppose a presentation has some slides that should be included in presentations to the East region but not the West region. Similarly, there are alternative slides that should be shown only to the West. Your add-in can create a tag with the key REGION and the value East and apply it to the slides that should only be used in the East. The tag's value is set to West for the slides that should only be shown to the West region. Just before a presentation to the East, a button in the add-in runs code that loops through all the slides checking the value of the REGION tag. Slides where the region is West are deleted. The user then closes the add-in and starts the slide show.
When applied to a presentation, a tag is effectively a custom property in the presentation document (similar to a CustomProperty in Word).
Tag slides and shapes
A tag is a key-value pair, where the value is always of type string and is represented by a Tag object. Each type of parent object, such as a Presentation, Slide, or Shape object, has a tags property of type TagsCollection.
Add, update, and delete tags
To add a tag to an object, call the TagCollection.add method of the parent object's tags property. The following code adds two tags to the first slide of a presentation. About this code, note:
The first parameter of the add method is the key in the key-value pair.
The second parameter is the value.
The key is in uppercase letters. This isn't strictly mandatory for the add method; however, the key is always stored by PowerPoint as uppercase, and some tag-related methods do require that the key be expressed in uppercase, so we recommend as a best practice that you always use uppercase in your code for a tag key.
To delete a tag, call the delete method on it's parent TagsCollection object and pass the key of the tag as the parameter. For an example, see Set custom metadata on the presentation.
Use tags to selectively process slides and shapes
Consider the following scenario: Contoso Consulting has a presentation they show to all new customers. But some slides should only be shown to customers that have paid for "premium" status. Before showing the presentation to non-premium customers, they make a copy of it and delete the slides that only premium customers should see. An add-in enables Contoso to tag which slides are for premium customers and to delete these slides when needed. The following list outlines the major coding steps to create this functionality.
Create a function that tags the currently selected slide as intended for Premium customers. About this code, note:
The getSelectedSlideIndex function is defined in the next step. It returns the 1-based index of the currently selected slide.
The value returned by the getSelectedSlideIndex function has to be decremented because the SlideCollection.getItemAt method is 0-based.
getSelectedDataAsync returns an array because multiple slides can be selected. In this scenario, the user has selected just one, so the code gets the first (0th) slide, which is the only one selected.
The index value of the slide is the 1-based value the user sees beside the slide in the PowerPoint UI thumbnails pane.
The following code creates a function to delete slides that are tagged for premium customers. About this code, note:
Because the key and value properties of the tags are going to be read after the context.sync, they must be loaded first.
async function deleteSlidesByAudience() {
await PowerPoint.run(async function(context) {
const slides = context.presentation.slides;
slides.load("tags/key, tags/value");
await context.sync();
for (let i = 0; i < slides.items.length; i++) {
let currentSlide = slides.items[i];
for (let j = 0; j < currentSlide.tags.items.length; j++) {
let currentTag = currentSlide.tags.items[j];
if (currentTag.key === "CUSTOMER_TYPE" && currentTag.value === "Premium") {
currentSlide.delete();
}
}
}
await context.sync();
});
}
Set custom metadata on the presentation
Add-ins can also apply tags to the presentation as a whole. This enables you to use tags for document-level metadata similar to how the CustomPropertyclass is used in Word. But unlike the Word CustomProperty class, the value of a PowerPoint tag can only be of type string.
The following code is an example of adding a tag to a presentation.
async function addPresentationTag() {
await PowerPoint.run(async function (context) {
let presentationTags = context.presentation.tags;
presentationTags.add("SECURITY", "Internal-Audience-Only");
await context.sync();
});
}
The following code is an example of deleting a tag from a presentation. Note that the key of the tag is passed to the delete method of the parent TagsCollection object.
async function deletePresentationTag() {
await PowerPoint.run(async function (context) {
let presentationTags = context.presentation.tags;
presentationTags.delete("SECURITY");
await context.sync();
});
}
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Office Add-ins feedback
Office Add-ins is an open source project. Select a link to provide feedback:
Demonstrate that you have the skills needed to get the most out of PowerPoint (Microsoft 365 Apps) by earning a Microsoft Office Specialist (MOS) certification.