Skip to content
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

Docs: Add Block Actions Readme #69408

Open
wants to merge 1 commit into
base: trunk
Choose a base branch
from
Open

Docs: Add Block Actions Readme #69408

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
71 changes: 71 additions & 0 deletions packages/block-editor/src/components/block-actions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
## Block Actions

The `BlockActions` component provides an interface for executing various actions on a set of blocks in the WordPress block editor. These actions include duplication, removal, insertion, grouping, ungrouping, and style copying.

### Usage

```jsx
import BlockActions from './block-actions';

<BlockActions clientIds={selectedBlockIds}>
{({ onDuplicate, onRemove }) => (
<>
<button onClick={onDuplicate}>Duplicate</button>
<button onClick={onRemove}>Remove</button>
</>
)}
</BlockActions>;
```

### Props

| Prop | Type | Description |
| ------------------------------- | ---------- | -------------------------------------------------------------------- |
| `clientIds` | `string[]` | Array of block client IDs to perform actions on. |
| `children` | `function` | A render prop function that receives available actions as an object. |
| `__experimentalUpdateSelection` | `function` | (Experimental) Function to update block selection after an action. |

### Provided Actions

The `children` function receives an object with the following properties, which can be used to trigger block actions:

| Action | Type | Description |
| ---------------- | --------------------- | ------------------------------------------------------ |
| `onDuplicate` | `() => void` | Duplicates the selected blocks. |
| `onRemove` | `() => void` | Removes the selected blocks. |
| `onInsertBefore` | `() => void` | Inserts a new block before the selected blocks. |
| `onInsertAfter` | `() => void` | Inserts a new block after the selected blocks. |
| `onGroup` | `() => void` | Groups the selected blocks into a container block. |
| `onUngroup` | `() => void` | Ungroups a grouped block, extracting its inner blocks. |
| `onCopy` | `() => void` | Copies the selected block(s) for later pasting. |
| `onPasteStyles` | `() => Promise<void>` | Pastes styles from copied blocks. |

### Features

- **Duplication**: Allows duplicating blocks that support multiple instances.
- **Removal**: Provides an option to remove selected blocks.
- **Insertion**: Supports inserting new blocks before or after the selected ones.
- **Grouping & Ungrouping**: Enables conversion of selected blocks into a group and extraction of inner blocks from a group.
- **Copy & Paste Styles**: Copies styles from a block and applies them to another.

### Dependencies

The component uses the following WordPress dependencies:

- `@wordpress/data` for interacting with the editor's state.
- `@wordpress/blocks` for block support checks and transformations.
- `@wordpress/block-editor` for modifying blocks within the editor.

### Related Components

- `usePasteStyles` – Used to handle copying and pasting block styles.
- `block-editor/store` – The primary store for managing block actions.

### Notes

This component does not render UI directly. Instead, it provides action handlers through a render prop pattern, allowing flexibility in implementation.

---

For more details, refer to the [WordPress Gutenberg repository](https://github.com/WordPress/gutenberg).

Loading