Typography field type

The Typography field type allows you to output the common typography fields in one field output. It reduces the amount of setup necessary to manage typography styles for an element.

Like the other theme editor fields, the border field is set up in the theme-styles.json or theme-settings.json file.

Below is a minimal configuration example.

{
    "name": "elementTypography"
    "label": "Typography",
    "type": "typography"
}

Field types in the typography field

The typography field isn't an actual field in itself. Rather, is made up of the following fields:

Color
Font family
Font size
Font style
Font weight
Letter spacing
Line height
Text align
Text decoration
Text shadow
Text transform

Each of those fields can be individually configured or toggled off so that they don't display.

You can also include the Margin and Padding fields. By default they are configured not to display.

The following fields can optionally have a hover version of it's value.

Color
Font size
Font style
Text decoration

The hover value is used for the :hover style when the element is hovered.

Configuration

You configure the typography field with the field properties in the theme JSON. Below is a list of available properties.

No results could be found. Please try a different search.

Property	Description
collapsable	By default the field is displayed fully visible. You can optionally have the fields hidden under an accordion. This property configures whether that will happen. If you want to display the field as an accordion then set this to true or yes. Allowed values are true, false, yes, and no.
color	The configuration for the color field. For example, if you want to set the default color value you could do this: color: { default: '#ff0000' }
colorRender	How the color field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
colorHover	The configuration for the color field when it's used to set the hover style.
colorHoverRender	How the hover version of the color field value will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
defaultValue	Set the default value for one or more of the child fields. This is different from the defaultValue for almost all other field types. The typography field doesn't have it's own value so the defaultValue property is instead used to set the value of a child field. The value is an object where the object key is the field type and the value is the default value for that field type. For example: "defaultValue": {"color": '#fff', "fontSize": "3rem"} The following field types are available to set a default value for: color colorHover fontFamily fontSize fontStyle fontStyleHover fontWeight letterSpacing lineHeight margin padding textAlign textDecoration textDecorationHover textShadow textTransform
description	A brief description for the field. This will show below the field label and above the field. It can contain HTML.
fontFamily	The configuration for the font family field.
fontFamilyRender	How the font family field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
fontSize	The configuration for the font size field. For example, if you want to set the default font size value and limit the available units you could do this: fontSize: { default: '2.8rem', "allowedUnits": ["px", "rem"] }
fontSizeRender	How the font size field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
fontSizeHover	The configuration for the font size field when it's used to set the hover style.
fontSizeHoverRender	How the hover version of the font size field value will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
fontStyle	The configuration for the font style field.
fontStyleRender	How the font style field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
fontStyleHover	The configuration for the font style field when it's used to set the hover style.
fontStyleHoverRender	How the hover version of the font style field value will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
fontWeight	The configuration for the font weight field. For example, if you want to set the default font weight value you could do this: fontWeight: { default: 600 }
fontWeightRender	How the font weight field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
label	Required The field label text. The label treatment for the typography field is different from other fields. It is only used in one of two circumstances. The field is collapsable and in that case it's used as the accordion heading text. The prependLabel property is set to true.
letterSpacing	The configuration for the letter spacing field. For example, if you want to set the default letter spacing value you could do this: letterSpacing: { default: 1.2 }
letterSpacingRender	How the letter spacing field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
lineHeight	The configuration for the line height field. For example, if you want to set the default line height value you could do this: lineHeight: { default: 1.5 }
lineHeightRender	How the line height field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
name	Required The name of the field.
prependLabel	Whether to prepend the child field label with the label of this field. The default value is false. For example, if the label for this field was "Primary heading" then the color field label will be "Primary heading color" instead of "Color". And the font style label will be "Primary heading font style" instead of "Font style". Allowed values are true, false, yes, and no.
render	How the field will be previewed in the theme editor and how it will be output in templates. See Previewing theme editor changes for more information. By default all of the field types will use the typography field render configuration for their own render configuration. You can override some or all of the render configuration for individual field types. For example, to override the render configuration for the color field you can use the colorRender property.
textAlign	The configuration for the text align field.
textAlignRender	How the text align field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
textDecoration	The configuration for the text decoration field.
textDecorationRender	How the text decoration field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
textDecorationHover	The configuration for the text decoration field when it's used to set the hover style.
textDecorationHoverRender	How the hover version of the text decoration field value will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
textShadow	The configuration for the text shadow field.
textShadowRender	How the text shadow field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
textTransform	The configuration for the text transform field.
textTransformRender	How the text transform field will be previewed in the theme editor and how it will be output in templates. This can override the configuration in the render property. See Previewing theme editor changes for more information.
type	Required The field type. It's value should be typography. This is what tells the system to output the field as a typography field.
useColor	Whether the color field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useColorHover	Whether the hover version color field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useFontFamily	Whether the font family field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useFontSize	Whether the font size field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useFontSizeHover	Whether the hover version font size field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useFontStyle	Whether the font style field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useFontStyleHover	Whether the hover version font style field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useFontWeight	Whether the font style field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useHover	Convenience property to set whether the show all of the hover variants of the fields. By default it is false. This is the same as setting useColorHover, useFontSizeHover, useFontStyleHover, and useTextDecorationHover to true. Allowed values are true, false, yes, and no.
useLetterSpacing	Whether the letter spacing field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useLineHeight	Whether the line height field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useMargin	Whether the margin field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
usePadding	Whether the padding field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useSpacing	Convenience property to set whether the show the margin and padding fields. By default it is false. This is the same as setting margin and padding to true. Allowed values are true, false, yes, and no.
useTextAlign	Whether the text align field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useTextDecoration	Whether the text decoration field will be displayed. By default it is true. Allowed values are true, false, yes, and no.
useTextDecorationHover	Whether the hover version text decoration field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useTextShadow	Whether the text shadow field will be displayed. By default it is false. Allowed values are true, false, yes, and no.
useTextTransform	Whether the text transform field will be displayed. By default it is true. Allowed values are true, false, yes, and no.

Examples

Below are some example JSON configurations.

This is a simple example that sets up a typography field whose values will output as CSS variables and be prefixed with "--Heading".

{
    "name": "headingTypography",
    "label": "Heading typography",
    "description": "Styles for the heading of a page",
    "type": "typography",
    "render": {
        "type": "css-head",
        "cssVariable": "--Heading"
    }
},

This example enables the margin and text shadow fields and it sets some default values. It also configures the font size field to only allow pixels, but output as rems.

{
    "label": "H1",
    "name": "baseTypographyH1",
    "type": "typography",
    "collapsable": false,
    "useMargin": true,
    "useTextShadow": true,
    "render": {
        "type": "css-head",
        "cssVariable": "--base-typography-h1"
    },
    "color": {
        "defaultValue": "#333333"
    },
    "fontSize": {
        "defaultValue": "32px",
        "allowedUnits": ["px"]
    },
    "fontSizePreview": {
        "template": "{% if value.size %}{{ value.size / 10 }}rem{% endif %}"
    },
    "fontWeight": {
        "defaultValue": "700"
    },
    "lineHeight": {
        "defaultValue": "1.58"
    },
    "margin": {
        "defaultValue": {
            "top": "2.5rem",
            "bottom": "1.25rem"
        }
    }
}

This example disables some of the default fields and sets some default values.

{
    "label": "Base",
    "name": "baseTypography",
    "type": "typography",
    "collapsable": false,
    "useFontStyle": false,
    "useTextAlign": false,
    "useTextDecoration": false,
    "useTextTransform": false,
    "render": {
        "type": "css-head",
        "cssVariable": "--base-typography"
    },
    "color": {
        "defaultValue": "#333333"
    },
    "fontSize": {
        "defaultValue": "18rem"
    },
    "lineHeight": {
        "defaultValue": "1.58"
    }
}

This is an example of styling links. It enables the hover fields and sets some default values.

{
    "label": "Links",
    "name": "baseTypographyLink",
    "type": "typography",
    "useHover": true,
    "collapsable": false,
    "render": {
        "type": "css-head",
        "cssVariable": "--base-typography-link"
    },
    "fontSizePreview": {
        "template": "{% if value.size %}{{ value.size / 10 }}rem{% endif %}"
    },
    "color": {
        "defaultValue": "#0000EE"
    },
    "colorHover": {
        "defaultValue": "#0000CD"
    },
    "textDecoration": {
        "defaultValue": "underline"
    },
    "textDecorationHover": {
        "defaultValue": "underline"
    }
}