Taxonomy picker component in the Microsoft Graph Toolkit
The taxonomy picker is a component that can query the Microsoft Graph API for Taxonomy and render a dropdown control with terms, allowing selection of a single term based on the specified term set id or a combination of the specified term set id and the specified term id.
The component retrieves the first level terms that are present under a specified term set or term. If only the term set ID is provided, it returns the first level terms under that term set. If both the term set ID and term ID are provided, it returns the first-level terms under the specified term.
Note This capability currently supports a single selection of terms coming from the term store.
Example
The following example shows the use of the mgt-taxonomy-picker component to select a term from a term set.
Properties and attributes
You can use several attributes to change the behavior of the component. The required attribute is term-set-id.
| Attribute | Property | Description | Type |
|---|---|---|---|
| term-set-id | termsetId | Mandatory. The ID of the term set to retrieve first level terms from. | String |
| term-id | termId | Optional. The ID of the term to retrieve first level terms from. If not provided, the function retrieves the first level terms under the term set specified by term-set-id. Note that this term must be one of the terms under the term set with ID term-set-id. |
String |
| site-id | siteId | Optional. The id of the site where the term set is present. If not specified, the term set is assumed to be at the tenant level. | String |
| version | version | Optional. API version to use when making the GET request. Default is beta. |
String |
| placeholder | placeholder | Optional. The placeholder to use in the combobox. Default value is Select a term. |
string |
| locale | locale | Optional. The locale of the terms that need to be displayed. This is useful only when terms have multiple labels in different languages. | String |
| default-selected-term-id | defaultSelectedTermId | Optional. The id of the term that should be selected by default. | String |
| position | position | Optional. The position of the dropdown. Can be 'above' or 'below'. Default is below |
String |
| disabled | disabled | Optional. Sets whether the taxonomy picker is disabled. When disabled, the user isn't able to search or select terms. | NA |
| cache-enabled | cacheEnabled | Optional. When set, it indicates that the response from the resource will be cached. Default is false. |
Boolean |
| cache-invalidation-period | cacheInvalidationPeriod | Optional. (Number of milliseconds) When set in combination with cacheEnabled, the delay before the cache reaches its invalidation period will be modified by this value. Default is 0 and will use the default invalidation period. |
Number |
The following example changes the behavior of the component to fetch first level child terms of specified term set.
<mgt-taxonomy-picker
term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>
The following example changes the behavior of the component to fetch first level child terms of specified term.
<mgt-taxonomy-picker
term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
></mgt-taxonomy-picker>
The following example changes the behavior of the component to fetch the French labels of the first level child terms of specified term.
<mgt-taxonomy-picker
term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
locale="fr-FR"
></mgt-taxonomy-picker>
The following example changes the behavior of the component to fetch first level child terms of specified term set that is present in a specified site.
<mgt-taxonomy-picker
term-set-id="7889007a-fb0e-449f-b629-dedf63ae53de"
site-id="contoso.sharepoint.com,0962bcef-48f1-4460-baa8-b7286dcb249b,ba412b3c-951a-4322-ac37-0fe6307b5987"
></mgt-taxonomy-picker>
The following example changes the behavior of the component to fetch first level child terms of specified term set and sets a specified term to be selected by default.
<mgt-taxonomy-picker
term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
default-selected-term-id="7ab1d163-f691-4676-88b3-c2d8921b73eb"
></mgt-taxonomy-picker>
CSS custom properties
The mgt-taxonomy-picker component defines the following CSS custom properties for you to provide overrides with.
<mgt-taxonomy-picker
class="taxonomy-picker"
term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>
.taxonomy-picker {
--taxonomy-picker-background-color: grey;
--taxonomy-picker-list-max-height: 200px;
--taxonomy-picker-background-color: black;
--taxonomy-picker-placeholder-color: white;
}
To learn more, see styling components.
Methods
| Method | Description |
|---|---|
| refresh(force?:boolean) | Call the method to refresh the data. By default, the UI will only update if the data changes. Pass true to force the component to update. |
Events
| Event | When is it emitted | Custom data | Cancelable | Bubbles | Works with custom template |
|---|---|---|---|---|---|
selectionChanged |
Fired when the user makes a change in selection in the dropdown. | The selected term that will of the type TermStore.Term |
No | Yes | Yes |
For more information about handling events, see events.
Templates
The mgt-taxonomy-picker component supports several templates that you can use to define the look and feel. To specify a template, include a <template> element inside a component and set the data-type to one of the following values.
| Data type | Data context | Description |
|---|---|---|
| error | The error from Microsoft Graph. | This template is used if there's an error making the request. |
| loading | N/A | This template is used while the request is being made. |
| no-data | N/A | This template is used when the request returned no data. |
Example template usage
<mgt-taxonomy-picker term-set-id="138a652e-7f23-46f6-b480-13da2308c235">
<div>Loading template</div>
<template data-type="loading">
Loading
</template>
<template data-type="no-data">
<div>No data</div>
</template>
<template data-type="error">
<div>Error</div>
</template>
</div>
</mgt-taxonomy-picker>
Microsoft Graph permissions
This component uses the following Microsoft Graph APIs and permissions. For each API called, the user must have at least one of the permissions listed.
| Configuration | Permission | API |
|---|---|---|
| default | TermStore.Read.All, TermStore.ReadWrite.All | /termStore/sets/{setId}/children |
| default | TermStore.Read.All, TermStore.ReadWrite.All | /termStore/sets/{setId}/terms/{termId}/children |
site-id is set |
TermStore.Read.All, TermStore.ReadWrite.All | /sites/{site-id}/termStore/sets/{set-id}/children |
site-id is set |
TermStore.Read.All, TermStore.ReadWrite.All | /sites/{site-id}/termStore/sets/{set-id}/terms/{term-id}/children |
For more information about permissions, see the Microsoft Graph permissions reference.
Authentication
The control uses the global authentication provider described in the authentication documentation to fetch the required data.
Cache
To enable and configure the cache, use the cacheEnabled and cacheInvalidationPeriod properties. By default, the mgt-taxonomy-picker component doesn't cache any responses.
| Object store | Cached data | Remarks |
|---|---|---|
response |
Complete response retrieved from Microsoft Graph for the terms. |
For details, see Caching.
Localization
The control exposes the following variables that can be localized. For details about how to set up localization, see Localizing components.
| String name | Default value |
|---|---|
| comboboxPlaceholder | Select a term |
| loadingMessage | Loading... |
| noTermsFound | No terms found |
| termsetIdRequired | The termsetId property or termset-id attribute is required |