|
| 1 | +# PropertyFieldBrandFontPicker control |
| 2 | + |
| 3 | +This control generates a font picker that reads from SharePoint Brand Center and allows users to select corporate-approved fonts for their web parts. It supports both Brand Center fonts, system fonts, and custom font tokens with preview capabilities. |
| 4 | + |
| 5 | +**PropertyFieldBrandFontPicker** |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +**PropertyFieldBrandFontPicker with font preview** |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +## How to use this control in your solutions |
| 14 | + |
| 15 | +1. Check that you installed the `@pnp/spfx-property-controls` dependency. Check out The [getting started](../../#getting-started) page for more information about installing the dependency. |
| 16 | +2. Import the following modules to your component: |
| 17 | + |
| 18 | +```TypeScript |
| 19 | +import { PropertyFieldBrandFontPicker } from '@pnp/spfx-property-controls/lib/PropertyFieldBrandFontPicker'; |
| 20 | +``` |
| 21 | + |
| 22 | +3. Create a new property for your web part, for example: |
| 23 | + |
| 24 | +```TypeScript |
| 25 | +export interface IPropertyControlsTestWebPartProps { |
| 26 | + brandFont: string; |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +4. Add the custom property control to the `groupFields` of the web part property pane configuration: |
| 31 | + |
| 32 | +```TypeScript |
| 33 | +PropertyFieldBrandFontPicker('brandFont', { |
| 34 | + label: 'Brand Font', |
| 35 | + initialValue: this.properties.brandFont, |
| 36 | + onSelectionChanged: (fontToken) => { |
| 37 | + this.properties.brandFont = fontToken.value; |
| 38 | + this.onPropertyPaneFieldChanged('brandFont', fontToken.value); |
| 39 | + }, |
| 40 | + context: this.context, |
| 41 | + showPreview: true, |
| 42 | + key: 'brandFontFieldId' |
| 43 | +}) |
| 44 | +``` |
| 45 | + |
| 46 | +## Using Custom Font Tokens |
| 47 | + |
| 48 | +You can provide your own list of font tokens instead of relying on Brand Center: |
| 49 | + |
| 50 | +```TypeScript |
| 51 | +import { IBrandFontToken } from '@pnp/spfx-property-controls/lib/PropertyFieldBrandFontPicker'; |
| 52 | + |
| 53 | +const customFontTokens: IBrandFontToken[] = [ |
| 54 | + { |
| 55 | + name: 'corporateHeading', |
| 56 | + displayName: 'Corporate Heading Font', |
| 57 | + value: '"Montserrat", sans-serif', |
| 58 | + category: 'custom' |
| 59 | + }, |
| 60 | + { |
| 61 | + name: 'corporateBody', |
| 62 | + displayName: 'Corporate Body Font', |
| 63 | + value: '"Open Sans", sans-serif', |
| 64 | + category: 'custom' |
| 65 | + } |
| 66 | +]; |
| 67 | + |
| 68 | +PropertyFieldBrandFontPicker('brandFont', { |
| 69 | + label: 'Custom Brand Font', |
| 70 | + initialValue: this.properties.brandFont, |
| 71 | + onSelectionChanged: (fontToken) => { |
| 72 | + this.properties.brandFont = fontToken.value; |
| 73 | + this.onPropertyPaneFieldChanged('brandFont', fontToken.value); |
| 74 | + }, |
| 75 | + context: this.context, |
| 76 | + customFontTokens: customFontTokens, |
| 77 | + showPreview: true, |
| 78 | + key: 'brandFontFieldId' |
| 79 | +}) |
| 80 | +``` |
| 81 | + |
| 82 | +## Implementation |
| 83 | + |
| 84 | +The `PropertyFieldBrandFontPicker` control can be configured with the following properties: |
| 85 | + |
| 86 | +| Property | Type | Required | Description | |
| 87 | +| ---- | ---- | ---- | ---- | |
| 88 | +| label | string | no | Property field label displayed on top. | |
| 89 | +| initialValue | string | no | Initial font value to be selected. | |
| 90 | +| onSelectionChanged | function | yes | Callback function when a font is selected. Returns the selected IBrandFontToken. | |
| 91 | +| context | BaseComponentContext | yes | The SPFx component context. | |
| 92 | +| customFontTokens | IBrandFontToken[] | no | Array of custom font tokens to display instead of Brand Center fonts. | |
| 93 | +| showPreview | boolean | no | Whether to display font preview text in the dropdown. Default is true. | |
| 94 | +| disabled | boolean | no | Whether the control is disabled. Default is false. | |
| 95 | +| onFontTokensLoaded | function | no | Callback function called when font tokens are loaded. | |
| 96 | +| loadingErrorMessage | string | no | Custom error message to display when font loading fails. | |
| 97 | +| key | string | yes | An UNIQUE key indicates the identity of this control. | |
| 98 | + |
| 99 | +Interface `IBrandFontToken`: |
| 100 | + |
| 101 | +| Property | Type | Required | Description | |
| 102 | +| ---- | ---- | ---- | ---- | |
| 103 | +| name | string | yes | Unique identifier for the font token. | |
| 104 | +| displayName | string | yes | Display name shown in the dropdown. | |
| 105 | +| value | string | yes | CSS font-family value (e.g., '"Lato", sans-serif'). | |
| 106 | +| preview | string | no | Optional preview text. | |
| 107 | +| category | string | no | Category for grouping (e.g., 'site', 'microsoft', 'custom'). | |
| 108 | +| fileUrl | string | no | Optional URL to font file or CSS. | |
| 109 | + |
| 110 | +## Example |
| 111 | + |
| 112 | +```TypeScript |
| 113 | +import * as React from 'react'; |
| 114 | +import * as ReactDom from 'react-dom'; |
| 115 | +import { Version } from '@microsoft/sp-core-library'; |
| 116 | +import { |
| 117 | + BaseClientSideWebPart, |
| 118 | + IPropertyPaneConfiguration, |
| 119 | + PropertyPaneTextField |
| 120 | +} from '@microsoft/sp-webpart-base'; |
| 121 | + |
| 122 | +import { PropertyFieldBrandFontPicker } from '@pnp/spfx-property-controls/lib/PropertyFieldBrandFontPicker'; |
| 123 | + |
| 124 | +export interface IPropertyControlsTestWebPartProps { |
| 125 | + brandFont: string; |
| 126 | +} |
| 127 | + |
| 128 | +export default class PropertyControlsTestWebPart extends BaseClientSideWebPart<IPropertyControlsTestWebPartProps> { |
| 129 | + |
| 130 | + public render(): void { |
| 131 | + const element: React.ReactElement<IPropertyControlsTestWebPartProps> = React.createElement( |
| 132 | + PropertyControlsTest, |
| 133 | + { |
| 134 | + brandFont: this.properties.brandFont |
| 135 | + } |
| 136 | + ); |
| 137 | + |
| 138 | + ReactDom.render(element, this.domElement); |
| 139 | + } |
| 140 | + |
| 141 | + protected get propertyPaneConfiguration(): IPropertyPaneConfiguration { |
| 142 | + return { |
| 143 | + pages: [ |
| 144 | + { |
| 145 | + header: { |
| 146 | + description: strings.PropertyPaneDescription |
| 147 | + }, |
| 148 | + groups: [ |
| 149 | + { |
| 150 | + groupName: strings.BasicGroupName, |
| 151 | + groupFields: [ |
| 152 | + PropertyFieldBrandFontPicker('brandFont', { |
| 153 | + label: 'Brand Font', |
| 154 | + initialValue: this.properties.brandFont, |
| 155 | + onSelectionChanged: (fontToken) => { |
| 156 | + this.properties.brandFont = fontToken.value; |
| 157 | + this.onPropertyPaneFieldChanged('brandFont', fontToken.value); |
| 158 | + }, |
| 159 | + context: this.context, |
| 160 | + showPreview: true, |
| 161 | + key: 'brandFontFieldId' |
| 162 | + }) |
| 163 | + ] |
| 164 | + } |
| 165 | + ] |
| 166 | + } |
| 167 | + ] |
| 168 | + }; |
| 169 | + } |
| 170 | +} |
| 171 | +``` |
| 172 | + |
| 173 | + |
0 commit comments