repository·master·Indexed 21 days ago
https://github.com/advanced-cropper/react-advanced-cropperA highly customizable React library for creating image croppers. It supports various cropper types, mobile and desktop interaction, and deep customization of appearance and behavior. Key features include support for Rectangle and Circle stencils, image restrictions (fitArea, fillArea, stencil, none), and the ability to override core operations via custom algorithms. Version 0.20.2.
To customize default stencils (like RectangleStencil or CircleStencil), pass configuration to the stencilProps prop. This object allows you to control handlers, lines, overlays, and previews.
<Cropper
src={img}
stencilProps={{
// configuration goes here
}}
/>The library categorizes croppers into three distinct behavioral groups. Choosing the right group depends on whether you want the user to manipulate the stencil (the selection area) or the image itself:
To use state modifiers in react-advanced-cropper, you must define a settings object containing all required fields. This object allows you to control initial states, restrictions on the visible area, and restrictions on the stencil (coordinates) size, position, and aspect ratio.
{
defaultCoordinates,
defaultVisibleArea,
areaPositionRestrictions,
areaSizeRestrictions,
sizeRestrictions,
positionRestrictions,
aspectRatio,
}react-advanced-cropper is the cropper state. All components and hooks provided by the library are essentially tools to modify this state and render it to the user. While the state can be used to display results, it is the central source of truth for the cropper's current configuration and position.By default, the Cropper prevents all default mouse and touch events on its background wrapper to ensure that user interactions (like dragging the image) don't accidentally scroll the page.
If you want to allow the user to scroll the page even when their cursor is over the cropper, you must replace the default CropperBackgroundWrapper with a custom implementation that does not prevent default events.
To customize the behavior of state modifiers (like position and size restrictions), you must define a settings object. While you can manually define all fields of the settings object, the recommended approach is to use the createDefaultSettings function.
createDefaultSettings simplifies the process by providing a set of flexible default functions. You can pass an object to createDefaultSettings to override specific defaults or provide additional constraints like minWidth, minHeight, maxWidth, or maxHeight.
const state = createState({
boundaries: {
width: 100,
height: 100
},
imageSize: {
width: 50,
height: 100,
},
settings: createDefaultSettings()
})The core concept of react-advanced-cropper is the cropper state. All components and hooks provided by the library are essentially tools to modify this state or display it.
The state is represented by a CropperState object. Note that the state can be null if it has not been initialized yet.
The state is composed of five main parts: boundary, imageSize, transforms, visibleArea, and coordinates.
interface CropperState {
boundary: Boundary;
imageSize: ImageSize;
transforms: Transforms;
visibleArea: VisibleArea | null;
coordinates: Coordinates | null;
}To apply real-time image adjustments (like brightness or saturation) without resetting the cropper state or sacrificing performance, you should replace the default CropperBackgroundImage with a custom background component.
Your custom component must:
getBackgroundStyle from react-advanced-cropper to calculate the correct transform/scale styles.ref to either an HTMLImageElement or an HTMLCanvasElement. Using an HTMLCanvasElement is recommended if you want to draw adjusted images (e.g., using ctx.filter) so that the cropper can retrieve the final processed content.image, state, and transitions as props provided by the Cropper via the backgroundComponent mechanism.import { CropperTransitions, CropperImage, CropperState, getBackgroundStyle } from 'react-advanced-cropper';
// Example of a component structure that satisfies the requirements
export const MyCustomBackground = forwardRef<HTMLCanvasElement, Props>((
{ className, image, state, transitions, ...props
}, ref) => {
const style = image && state ? getBackgroundStyle(image, state, transitions) : {};
// ... implementation using a canvas to apply filters ...
return <canvas ref={ref} style={style} />;
});state and the cropper settings as arguments and returns a new state object. This pattern allows for predictable state transitions and the creation of custom manipulation logic.Settings are parameters used by state modifiers and helpers to perform operations on the cropper state. They act as a context or a set of global variables for the cropper's logic.
The CoreSettings interface contains the minimal set of parameters required for most operations:
It is recommended to extend CoreSettings to allow your custom modifiers and helpers to access additional parameters. For example, the transformImage modifier requires extended settings:
function transformImage(state: CropperState, settings: CoreSettings & ModifiersSettings, ...otherArguments): CropperStateTip: If a parameter needs to be shared across different modifiers or if you cannot easily pass it as a direct argument to a specific modifier call, include it in the settings object.
To make a custom stencil interactive, connect the onMove and onMoveEnd callbacks of DraggableElement or DraggableArea to the cropper's API.
DraggableElementDraggableElement provides an onMove callback with a shift object of type MoveDirections ({ left: number; top: number; }). This represents the pixel delta of the movement.
To resize, call cropper.resizeCoordinates. You can use the compensate: true option to allow the stencil to resize in other directions if it hits the cropper boundary.
DraggableAreaTo move the stencil, call cropper.moveCoordinates(directions) where directions is a MoveDirections object.
To finalize the interaction, call cropper.resizeCoordinatesEnd or cropper.moveCoordinatesEnd in the onMoveEnd callback.
const onResize = (shift: MoveDirections) => {
// Example: resizing from center
cropper.resizeCoordinates('center', {
left: shift.left,
top: shift.left,
}, {
compensate: true,
});
};
const onMove = (directions: MoveDirections) => {
cropper.moveCoordinates(directions);
};State modifiers are functions used to change the cropper state, preferably by returning a clone of the state. A standard state modifier follows this signature:
function stateModifier(state: CropperState, settings: CoreSettings, ...otherArguments): CropperStateThey accept the current state, the settings (which act as context), and optional additional arguments, returning the updated CropperState.