# BorderBoxControl

<div class="callout callout-alert">
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
</div>
<br />

This component provides users with the ability to configure a single "flat"
border or separate borders per side.

## Development guidelines

The `BorderBoxControl` effectively has two view states. The first, a "linked"
view, allows configuration of a flat border via a single `BorderControl`.
The second, a "split" view, contains a `BorderControl` for each side
as well as a visualizer for the currently selected borders. Each view also
contains a button to toggle between the two.

When switching from the "split" view to "linked", if the individual side
borders are not consistent, the "linked" view will display any border properties
selections that are consistent while showing a mixed state for those that
aren't. For example, if all borders had the same color and style but different
widths, then the border dropdown in the "linked" view's `BorderControl` would
show that consistent color and style but the "linked" view's width input would
show "Mixed" placeholder text.

## Usage

```jsx
import { __experimentalBorderBoxControl as BorderBoxControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

const colors = [
	{ name: 'Blue 20', color: '#72aee6' },
	// ...
];

const MyBorderBoxControl = () => {
	const defaultBorder = {
		color: '#72aee6',
		style: 'dashed',
		width: '1px',
	};
	const [ borders, setBorders ] = useState( {
		top: defaultBorder,
		right: defaultBorder,
		bottom: defaultBorder,
		left: defaultBorder,
	} );
	const onChange = ( newBorders ) => setBorders( newBorders );

	return (
		<BorderBoxControl
			colors={ colors }
			label={ __( 'Borders' ) }
			onChange={ onChange }
			value={ borders }
		/>
	);
};
```

If you're using this component outside the editor, you can
[ensure `Tooltip` positioning](/packages/components/README.md#popovers-and-tooltips)
for the `BorderBoxControl`'s color and style options, by rendering your
`BorderBoxControl` with a `Popover.Slot` further up the element tree and within
a `SlotFillProvider` overall.

## Props

### `colors`: `Array`

An array of color definitions. This may also be a multi-dimensional array where
colors are organized by multiple origins.

Each color may be an object containing a `name` and `color` value.

- Required: No

### `disableCustomColors`: `boolean`

This toggles the ability to choose custom colors.

- Required: No

### `enableAlpha`: `boolean`

This controls whether the alpha channel will be offered when selecting
custom colors.

- Required: No

### `enableStyle`: `boolean`

This controls whether to support border style selections.

- Required: No
- Default: `true`

### `hideLabelFromVision`: `boolean`

Provides control over whether the label will only be visible to screen readers.

- Required: No

### `label`: `string`

If provided, a label will be generated using this as the content.

_Whether it is visible only to screen readers is controlled via
`hideLabelFromVision`._

- Required: No

### `onChange`: `( value?: Object ) => void`

A callback function invoked when any border value is changed. The value received
may be a "flat" border object, one that has properties defining individual side
borders, or `undefined`.

_Note: The will be `undefined` if a user clears all borders._

- Required: Yes

### `popoverClassNames`: `Object`

An object defining CSS classnames for all the inner `BorderControl` popover
content.

Example:
```js
{
	linked: 'linked-border-popover-content',
	top: 'top-border-popover-content',
	right: 'right-border-popover-content',
	bottom: 'bottom-border-popover-content',
	left: 'left-border-popover-content',
}
```

By default, popovers are displayed relative to the button that initiated the popover. By supplying classnames for each individual popover, it is possible to add styling rules to align the popover positions to an unrelated design element, for example, the sidebar inspector in the block editor.

- Required: No

### `value`: `Object`

An object representing the current border configuration.

This may be a "flat" border where the object has `color`, `style`, and `width`
properties or a "split" border which defines the previous properties but for
each side; `top`, `right`, `bottom`, and `left`.

Examples:
```js
const flatBorder = { color: '#72aee6', style: 'solid', width: '1px' };
const splitBorders = {
	top: { color: '#72aee6', style: 'solid', width: '1px' },
	right: { color: '#e65054', style: 'dashed', width: '2px' },
	bottom: { color: '#68de7c', style: 'solid', width: '1px' },
	left: { color: '#f2d675', style: 'dotted', width: '1em' },
};
```

- Required: No

### `__experimentalHasMultipleOrigins`: `boolean`

This is passed on to the color related sub-components which need to be made
aware of whether the colors prop contains multiple origins.

- Required: No

### `__experimentalIsRenderedInSidebar`: `boolean`

This is passed on to the color related sub-components so they may render more
effectively when used within a sidebar.

- Required: No
