Skip to content

Revise README for FocalPointPicker component to use object-position #77722

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

Open
andreawetzel wants to merge 1 commit into
base: trunk
Choose a base branch
from
+5 −6
Open

Revise README for FocalPointPicker component to use object-position #77722

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
11 changes: 5 additions & 6 deletions packages/components/src/focal-point-picker/README.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@ciampo ciampo Apr 28, 2026

Choose a reason for hiding this comment

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

Whatever changes we end up making to the README, we should always keep them in sync with the JSDoc in index.tsx

Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# FocalPointPicker

Focal Point Picker is a component which creates a UI for identifying the most important visual point of an image. This component addresses a specific problem: with large background images it is common to see undesirable crops, especially when viewing on smaller viewports such as mobile phones. This component allows the selection of the point with the most important visual information and returns it as a pair of numbers between 0 and 1. This value can be easily converted into the CSS `background-position` attribute, and will ensure that the focal point is never cropped out, regardless of viewport.
Focal Point Picker is a component which creates a UI for identifying the most important visual point of an image. It addresses two common issues in responsive image rendering. First, large background images are often cropped in undesirable ways, especially on smaller viewports such as mobile devices. Second, the CSS aspect-ratio property can inadvertently crop out the area of highest visual interest. This component allows the selection of the point with the most important visual information and returns it as a pair of numbers between 0 and 1. This value can be easily converted into the CSS `object-position` attribute, and will ensure that the focal point is never cropped out, regardless of viewport.

- Example focal point picker value: `{ x: 0.5, y: 0.1 }`
- Corresponding CSS: `background-position: 50% 10%;`
- Corresponding CSS: `object-position: 50% 10%`
Comment on lines 5 to +6
Copy link
Copy Markdown
Contributor

@ciampo ciampo Apr 28, 2026

Choose a reason for hiding this comment

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

Let's add trailing semi-columns for both bullet points.


## Usage

Expand All @@ -14,15 +14,14 @@ import { FocalPointPicker } from '@wordpress/components';
const Example = () => {
const [ focalPoint, setFocalPoint ] = useState( {
x: 0.5,
y: 0.5,
y: 0.1,
} );

const url = '/path/to/image';

/* Example function to render the CSS styles based on Focal Point Picker value */
const style = {
backgroundImage: `url(${ url })`,
backgroundPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
objectPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
};

return (
Expand All @@ -34,7 +33,7 @@ const Example = () => {
onDrag={ setFocalPoint }
onChange={ setFocalPoint }
/>
<div style={ style } />
<img src={ url } style={ style } />
Copy link
Copy Markdown
Contributor

@ciampo ciampo Apr 28, 2026

Choose a reason for hiding this comment

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

I don't think the current example snippet will work as expected, we need to set object-fit and also ideally a target ratio (see https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position)

const style = {
	width: '100%',
	aspectRatio: '16 / 9',
	objectFit: 'cover',
	objectPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
};

return (
	<>
		<FocalPointPicker
			url={ url }
			value={ focalPoint }
			onDragStart={ setFocalPoint }
			onDrag={ setFocalPoint }
			onChange={ setFocalPoint }
		/>
		<img src={ url } alt="" style={ style } />
	</>
);

</>
);
};
Expand Down
Loading