Skip to content

Heading: Migrate to text-align block support #74383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shimotmk merged 11 commits into from
Jan 12, 2026
Merged

Heading: Migrate to text-align block support #74383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b2573a6
Heading: Migrate to text-align block support
shimotmk Jan 6, 2026
28b4965
update attributes
shimotmk Jan 6, 2026
cfb8c4e
update transform
shimotmk Jan 7, 2026
bae9c34
update shortcut
shimotmk Jan 7, 2026
9805557
add level
shimotmk Jan 7, 2026
561dbbf
revert hook
shimotmk Jan 7, 2026
b6d9458
update deprecated
shimotmk Jan 9, 2026
47d7e07
Update test/e2e/specs/editor/blocks/heading.spec.js
shimotmk Jan 9, 2026
8789310
update-deprecated
shimotmk Jan 10, 2026
76f239d
update
shimotmk Jan 10, 2026
af6b4f2
revert transform attributes
shimotmk Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/reference-guides/core-blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,8 +408,8 @@ Introduce new sections and organize content to help visitors (and search engines

- **Name:** core/heading
- **Category:** text
- **Supports:** __unstablePasteTextInline, align (full, wide), anchor, className, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), splitting, typography (fitText, fontSize, lineHeight)
- **Attributes:** content, level, levelOptions, placeholder, textAlign
- **Supports:** __unstablePasteTextInline, align (full, wide), anchor, className, color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), splitting, typography (fitText, fontSize, lineHeight, textAlign)
- **Attributes:** content, level, levelOptions, placeholder

## Home Link

Expand Down
11 changes: 4 additions & 7 deletions packages/block-library/src/block-keyboard-shortcuts/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,12 @@ function BlockKeyboardShortcuts() {
const sourceTextAlign =
attributes.textAlign || attributes.style?.typography?.textAlign;

// When destination is heading, preserve heading format (textAlign attribute + level)
// When destination is paragraph, use block support format (style.typography.textAlign)
// When destination is heading, set the level
if ( destinationBlockName === 'core/heading' ) {
newAttributes.level = level;
if ( sourceTextAlign ) {
newAttributes.textAlign = sourceTextAlign;
}
} else if ( sourceTextAlign ) {
// Destination is paragraph
}

if ( sourceTextAlign ) {
newAttributes.style = {
typography: {
textAlign: sourceTextAlign,
Expand Down
4 changes: 1 addition & 3 deletions packages/block-library/src/heading/block.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,6 @@
"keywords": [ "title", "subtitle" ],
"textdomain": "default",
"attributes": {
"textAlign": {
"type": "string"
},
"content": {
"type": "rich-text",
"source": "rich-text",
Expand Down Expand Up @@ -58,6 +55,7 @@
"typography": {
"fontSize": true,
"lineHeight": true,
"textAlign": true,
"__experimentalFontFamily": true,
"__experimentalFontStyle": true,
"__experimentalFontWeight": true,
Expand Down
123 changes: 118 additions & 5 deletions packages/block-library/src/heading/deprecated.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,11 @@ import {
useBlockProps,
} from '@wordpress/block-editor';

/**
* Internal dependencies
*/
import migrateTextAlignAttributeToBlockSupport from '../utils/migrate-text-align';

const blockSupports = {
className: false,
anchor: true,
Expand Down Expand Up @@ -75,7 +80,9 @@ const v1 = {
},
},
migrate: ( attributes ) =>
migrateCustomColors( migrateTextAlign( attributes ) ),
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
Comment on lines +83 to +85

@Mamaduka Mamaduka Feb 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A bit late feedback, but do we need to call migrateTextAlignAttributeToBlockSupport for every deprecation? I think it should only be applied to v6.

@shimotmk shimotmk Feb 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I've understood is that if you change the deprecated v1 migrate as follows, the textAlign attributes in core__heading__deprecated-1.serialized.html will be lost.

--- a/packages/block-library/src/heading/deprecated.js
+++ b/packages/block-library/src/heading/deprecated.js
@@ -79,10 +79,8 @@ 
-	// migrate: ( attributes ) =>
-	// 	migrateTextAlignAttributeToBlockSupport(
-	// 		migrateCustomColors( migrateTextAlign( attributes ) )
-	// 	),
     migrate: ( attributes ) =>
         migrateCustomColors( migrateTextAlign( attributes ) ),
     save( { attributes } ) {
--- a/test/integration/fixtures/blocks/core__heading__deprecated-1.serialized.html
+++ b/test/integration/fixtures/blocks/core__heading__deprecated-1.serialized.html
@@ -1,3 +1,3 @@
-<!-- wp:heading {"level":3,"style":{"typography":{"textAlign":"right"}}} -->
-<h3 class="wp-block-heading has-text-align-right">A picture is worth a thousand words, or so the saying goes</h3>
+<!-- wp:heading {"level":3} -->
+<h3 class="wp-block-heading">A picture is worth a thousand words, or so the saying goes</h3>
 <!-- /wp:heading -->

PR #73116 is also seeing redevelopment of the deprecated functionality.

save( { attributes } ) {
const { align, level, content, textColor, customTextColor } =
attributes;
Expand Down Expand Up @@ -111,7 +118,9 @@ const v2 = {
},
},
migrate: ( attributes ) =>
migrateCustomColors( migrateTextAlign( attributes ) ),
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
save( { attributes } ) {
const { align, content, customTextColor, level, textColor } =
attributes;
Expand Down Expand Up @@ -149,7 +158,9 @@ const v3 = {
},
},
migrate: ( attributes ) =>
migrateCustomColors( migrateTextAlign( attributes ) ),
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
save( { attributes } ) {
const { align, content, customTextColor, level, textColor } =
attributes;
Expand Down Expand Up @@ -195,7 +206,10 @@ const v4 = {
},
attributes: blockAttributes,
isEligible: ( { align } ) => TEXT_ALIGN_OPTIONS.includes( align ),
migrate: migrateTextAlign,
migrate: ( attributes ) =>
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
save( { attributes } ) {
const { align, content, level } = attributes;
const TagName = 'h' + level;
Expand Down Expand Up @@ -283,8 +297,107 @@ const v5 = {
</TagName>
);
},
migrate: ( attributes ) =>
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
};

const v6 = {
supports: {
align: [ 'wide', 'full' ],
anchor: true,
className: true,
splitting: true,
__experimentalBorder: {
color: true,
radius: true,
style: true,
width: true,
},
color: {
gradients: true,
link: true,
__experimentalDefaultControls: {
background: true,
text: true,
},
},
spacing: {
margin: true,
padding: true,
},
typography: {
fontSize: true,
lineHeight: true,
__experimentalFontFamily: true,
__experimentalFontStyle: true,
__experimentalFontWeight: true,
__experimentalLetterSpacing: true,
__experimentalTextTransform: true,
__experimentalTextDecoration: true,
__experimentalWritingMode: true,
fitText: true,
__experimentalDefaultControls: {
fontSize: true,
},
},
__unstablePasteTextInline: true,
__experimentalSlashInserter: true,
interactivity: {
clientNavigation: true,
},
},
attributes: {
textAlign: {
type: 'string',
},
content: {
type: 'string',
source: 'html',
selector: 'h1,h2,h3,h4,h5,h6',
default: '',
role: 'content',
},
level: {
type: 'number',
default: 2,
},
levelOptions: {
type: 'array',
},
placeholder: {
type: 'string',
},
},
save( { attributes } ) {
const { textAlign, content, level } = attributes;
const TagName = 'h' + level;

const className = clsx( {
[ `has-text-align-${ textAlign }` ]: textAlign,
} );

return (
<TagName { ...useBlockProps.save( { className } ) }>
<RichText.Content value={ content } />
</TagName>
);
},
migrate: ( attributes ) =>
migrateTextAlignAttributeToBlockSupport(
migrateCustomColors( migrateTextAlign( attributes ) )
),
isEligible( attributes ) {
return (
!! attributes.textAlign ||
!! attributes.className?.match(
/\bhas-text-align-(left|center|right)\b/
)
);
},
};

const deprecated = [ v5, v4, v3, v2, v1 ];
const deprecated = [ v6, v5, v4, v3, v2, v1 ];

export default deprecated;
38 changes: 6 additions & 32 deletions packages/block-library/src/heading/edit.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,30 @@
/**
* External dependencies
*/
import clsx from 'clsx';

/**
* WordPress dependencies
*/
import { __ } from '@wordpress/i18n';
import { useEffect, Platform } from '@wordpress/element';
import { useDispatch, useSelect } from '@wordpress/data';
import {
AlignmentControl,
BlockControls,
RichText,
useBlockProps,
store as blockEditorStore,
useBlockEditingMode,
} from '@wordpress/block-editor';

/**
* Internal dependencies
*/
import { generateAnchor, setAnchor } from './autogenerate-anchors';
import useDeprecatedTextAlign from '../utils/deprecated-text-align-attributes';

function HeadingEdit( {
attributes,
setAttributes,
mergeBlocks,
onReplace,
style,
clientId,
} ) {
const { textAlign, content, level, placeholder, anchor } = attributes;
function HeadingEdit( props ) {
const { attributes, setAttributes, mergeBlocks, onReplace, clientId } =
props;
useDeprecatedTextAlign( props );
const { style, content, level, placeholder, anchor } = attributes;
const tagName = 'h' + level;
const blockProps = useBlockProps( {
className: clsx( {
[ `has-text-align-${ textAlign }` ]: textAlign,
} ),
style,
} );
const blockEditingMode = useBlockEditingMode();

const { canGenerateAnchors } = useSelect( ( select ) => {
const { getGlobalBlockCount, getSettings } = select( blockEditorStore );
Expand Down Expand Up @@ -90,16 +75,6 @@ function HeadingEdit( {

return (
<>
{ blockEditingMode === 'default' && (
<BlockControls group="block">
<AlignmentControl
value={ textAlign }
onChange={ ( nextAlign ) => {
setAttributes( { textAlign: nextAlign } );
} }
/>
</BlockControls>
) }
<RichText
identifier="content"
tagName={ tagName }
Expand All @@ -109,7 +84,6 @@ function HeadingEdit( {
onReplace={ onReplace }
onRemove={ () => onReplace( [] ) }
placeholder={ placeholder || __( 'Heading' ) }
textAlign={ textAlign }
{ ...( Platform.isNative && { deleteEnter: true } ) } // setup RichText on native mobile to delete the "Enter" key as it's handled by the JS/RN side
{ ...blockProps }
/>
Expand Down
19 changes: 17 additions & 2 deletions packages/block-library/src/heading/edit.native.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,14 @@ function HeadingEdit( {
style,
clientId,
} ) {
const { textAlign, content, level, placeholder, anchor } = attributes;
const {
content,
level,
placeholder,
anchor,
style: attributesStyle,
} = attributes;
const textAlign = attributesStyle?.typography?.textAlign;
const tagName = 'h' + level;
const blockProps = useBlockProps( {
className: clsx( {
Expand Down Expand Up @@ -100,7 +107,15 @@ function HeadingEdit( {
<AlignmentControl
value={ textAlign }
onChange={ ( nextAlign ) => {
setAttributes( { textAlign: nextAlign } );
setAttributes( {
style: {
...attributesStyle,
typography: {
...attributesStyle?.typography,
textAlign: nextAlign,
},
},
} );
} }
/>
</BlockControls>
Expand Down
13 changes: 2 additions & 11 deletions packages/block-library/src/heading/save.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,14 @@
/**
* External dependencies
*/
import clsx from 'clsx';

/**
* WordPress dependencies
*/
import { RichText, useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
const { textAlign, content, level } = attributes;
const { content, level } = attributes;
const TagName = 'h' + level;

const className = clsx( {
[ `has-text-align-${ textAlign }` ]: textAlign,
} );

return (
<TagName { ...useBlockProps.save( { className } ) }>
<TagName { ...useBlockProps.save() }>
<RichText.Content value={ content } />
</TagName>
);
Expand Down
19 changes: 16 additions & 3 deletions packages/block-library/src/heading/transforms.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,13 @@ const transforms = {
),
content,
anchor,
textAlign,
...( textAlign && {
style: {
typography: {
textAlign,
},
},
} ),
} );
} ),
},
Expand Down Expand Up @@ -64,7 +70,13 @@ const transforms = {
textAlign === 'center' ||
textAlign === 'right'
) {
attributes.align = textAlign;
attributes.style = {
...attributes.style,
typography: {
...attributes.style?.typography,
textAlign,
},
};
}

return createBlock( 'core/heading', attributes );
Expand Down Expand Up @@ -93,7 +105,8 @@ const transforms = {
blocks: [ 'core/paragraph' ],
transform: ( attributes ) =>
attributes.map( ( _attributes ) => {
const { content, textAlign } = _attributes;
const { content, style } = _attributes;
const textAlign = style?.typography?.textAlign;
return createBlock( 'core/paragraph', {
...getTransformedAttributes(
_attributes,
Expand Down
Loading
Loading