# Bleed (/components/layout/bleed)



`Bleed` lets content extend beyond the space provided by its parent. Use it when a child should
reach farther on one or more edges without changing the parent's spacing.

apps/docs/src/examples/bleed/basic.tsx

```tsx
import { Bleed } from '@luke-ui/react/bleed';
import { Box } from '@luke-ui/react/box';
import { Stack } from '@luke-ui/react/stack';
import { ExampleItem } from '#docs';

export default () => {
	return (
		<Box
			backgroundColor="surface.recessed"
			borderColor="decorative"
			borderStyle="solid"
			borderWidth="thin"
			padding="sp24"
		>
			<Stack gap="sp16">
				<ExampleItem>Inset within the padding</ExampleItem>
				<Bleed inline="sp24">
					<ExampleItem>Extends to both inline edges</ExampleItem>
				</Bleed>
			</Stack>
		</Box>
	);
};
```

## Choose how far to extend [#choose-how-far-to-extend]

Pass a spacing token for the distance to extend. The value does not need to match the parent's
padding. When it does, the content reaches the parent's edge.

Use `all` to extend both axes by the same amount.

Bleed accepts the same responsive spacing values as other layout props. Read
[Responsive values](/docs/layout#responsive-values) for breakpoint behaviour.

## Choose the edges [#choose-the-edges]

Use `inline` to extend both inline edges and `block` to extend both block edges. Use `inlineStart`,
`inlineEnd`, `blockStart`, or `blockEnd` when only one edge should extend.

At the same breakpoint, an axis prop overrides `all`, and an edge prop overrides its axis prop.

apps/docs/src/examples/bleed/edges.tsx

```tsx
import { Bleed } from '@luke-ui/react/bleed';
import { Box } from '@luke-ui/react/box';
import { ExampleItem } from '#docs';

export default () => {
	return (
		<Box
			backgroundColor="surface.recessed"
			borderColor="decorative"
			borderStyle="solid"
			borderWidth="thin"
			padding="sp16"
		>
			<Bleed inlineStart="sp16">
				<ExampleItem>Inline start edge</ExampleItem>
			</Bleed>
		</Box>
	);
};
```

Use `'0'` at a breakpoint to stop bleeding. Here, `inline` matches the parent's padding on narrow
viewports, so the item reaches both edges. Resize the preview: at `bp640`, `inline` is `'0'` and the
parent's padding keeps the item inset.

apps/docs/src/examples/bleed/responsive.tsx

```tsx
import { Bleed } from '@luke-ui/react/bleed';
import { Box } from '@luke-ui/react/box';
import { Stack } from '@luke-ui/react/stack';
import { ExampleItem } from '#docs';

export default () => {
	return (
		<Box
			backgroundColor="surface.recessed"
			borderColor="decorative"
			borderStyle="solid"
			borderWidth="thin"
			paddingBlock="sp16"
			paddingInline="sp16"
		>
			<Stack gap="sp16">
				<ExampleItem>Inset within the padding</ExampleItem>
				<Bleed inline={{ initial: 'sp16', bp640: '0' }}>
					<ExampleItem>Full bleed on narrow viewports, inset from bp640</ExampleItem>
				</Bleed>
			</Stack>
		</Box>
	);
};
```

## Overlap adjacent items [#overlap-adjacent-items]

In a `Stack`, a block bleed larger than the gap extends into the space around adjacent items.

apps/docs/src/examples/bleed/stack-overlap.tsx

```tsx
import { Bleed } from '@luke-ui/react/bleed';
import { Stack } from '@luke-ui/react/stack';
import { Comparison, ComparisonItem, ExampleItem } from '#docs';

export default () => {
	return (
		<Comparison>
			<ComparisonItem label="Without bleed">
				<Stack gap="sp16">
					<ExampleItem>First item</ExampleItem>
					<ExampleItem backgroundColor="info.subtle.rest">Middle item</ExampleItem>
					<ExampleItem>Last item</ExampleItem>
				</Stack>
			</ComparisonItem>
			<ComparisonItem label="With block bleed">
				<Stack gap="sp16">
					<ExampleItem>First item</ExampleItem>
					<Bleed block="sp24" position="relative">
						<ExampleItem backgroundColor="info.subtle.rest">Middle item</ExampleItem>
					</Bleed>
					<ExampleItem>Last item</ExampleItem>
				</Stack>
			</ComparisonItem>
		</Comparison>
	);
};
```

In a `Grid`, use `all` to extend a cell into the gaps on every side.

apps/docs/src/examples/bleed/grid-overlap.tsx

```tsx
import { Bleed } from '@luke-ui/react/bleed';
import { Box } from '@luke-ui/react/box';
import { Grid } from '@luke-ui/react/grid';
import { ExampleItem } from '#docs';

export default () => {
	return (
		<Box
			backgroundColor="surface.recessed"
			borderColor="decorative"
			borderStyle="solid"
			borderWidth="thin"
			padding="sp24"
		>
			<Grid columns={3} gap="sp8">
				<ExampleItem>1</ExampleItem>
				<ExampleItem>2</ExampleItem>
				<ExampleItem>3</ExampleItem>
				<ExampleItem>4</ExampleItem>
				<Bleed all="sp12" position="relative">
					<ExampleItem backgroundColor="info.subtle.rest" blockSize="100%">
						5
					</ExampleItem>
				</Bleed>
				<ExampleItem>6</ExampleItem>
				<ExampleItem>7</ExampleItem>
				<ExampleItem>8</ExampleItem>
				<ExampleItem>9</ExampleItem>
			</Grid>
		</Box>
	);
};
```

## Choose the rendered element [#choose-the-rendered-element]

Bleed uses
[Box's `elementType` and `render` contract](/components/layout/box#choose-the-rendered-element).

## API [#api]

### BleedProps

Props for `Bleed`.

`BleedProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

| Prop                  | Type                     | Description                                                                                                                                         |
| --------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children?`           | `ReactNode`              |                                                                                                                                                     |
| `className?`          | `string`                 |                                                                                                                                                     |
| `style?`              | `object`                 |                                                                                                                                                     |
| `alignSelf?`          | `union`                  |                                                                                                                                                     |
| `blockSize?`          | `ResponsiveValue<union>` |                                                                                                                                                     |
| `flex?`               | `ResponsiveValue<union>` |                                                                                                                                                     |
| `flexBasis?`          | `ResponsiveValue<union>` |                                                                                                                                                     |
| `flexGrow?`           | `union`                  |                                                                                                                                                     |
| `flexShrink?`         | `union`                  |                                                                                                                                                     |
| `gridArea?`           | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridColumn?`         | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridColumnEnd?`      | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridColumnStart?`    | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridRow?`            | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridRowEnd?`         | `ResponsiveValue<union>` |                                                                                                                                                     |
| `gridRowStart?`       | `ResponsiveValue<union>` |                                                                                                                                                     |
| `inlineSize?`         | `ResponsiveValue<union>` |                                                                                                                                                     |
| `inset?`              | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetBlock?`         | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetBlockEnd?`      | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetBlockStart?`    | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetInline?`        | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetInlineEnd?`     | `ResponsiveValue<union>` |                                                                                                                                                     |
| `insetInlineStart?`   | `ResponsiveValue<union>` |                                                                                                                                                     |
| `justifySelf?`        | `union`                  |                                                                                                                                                     |
| `maxBlockSize?`       | `ResponsiveValue<union>` |                                                                                                                                                     |
| `maxInlineSize?`      | `ResponsiveValue<union>` |                                                                                                                                                     |
| `minBlockSize?`       | `ResponsiveValue<union>` |                                                                                                                                                     |
| `minInlineSize?`      | `ResponsiveValue<union>` |                                                                                                                                                     |
| `order?`              | `ResponsiveValue<union>` |                                                                                                                                                     |
| `overflow?`           | `union`                  |                                                                                                                                                     |
| `overflowX?`          | `union`                  |                                                                                                                                                     |
| `overflowY?`          | `union`                  |                                                                                                                                                     |
| `padding?`            | `union`                  |                                                                                                                                                     |
| `paddingBlock?`       | `union`                  |                                                                                                                                                     |
| `paddingBlockEnd?`    | `union`                  |                                                                                                                                                     |
| `paddingBlockStart?`  | `union`                  |                                                                                                                                                     |
| `paddingInline?`      | `union`                  |                                                                                                                                                     |
| `paddingInlineEnd?`   | `union`                  |                                                                                                                                                     |
| `paddingInlineStart?` | `union`                  |                                                                                                                                                     |
| `placeSelf?`          | `union`                  |                                                                                                                                                     |
| `position?`           | `union`                  |                                                                                                                                                     |
| `elementType?`        | `union`                  | Chooses a supported structural element. Use `elementType` instead of `render` for a supported structural element. Default: `div`                    |
| `ref?`                | `union`                  | Ref to the rendered element.                                                                                                                        |
| `render?`             | `function`               | Use `render` instead of `elementType` to own the rendered element. Passes the component's content and presentation props to a caller-owned element. |
| `all?`                | `union`                  | Amount to extend from all four edges. Axis and edge props override this at the same breakpoint.                                                     |
| `block?`              | `union`                  | Amount to extend from both block edges. Overrides `all` at the same breakpoint.                                                                     |
| `blockEnd?`           | `union`                  | Amount to extend from the block-end edge. Overrides `block` at the same breakpoint.                                                                 |
| `blockStart?`         | `union`                  | Amount to extend from the block-start edge. Overrides `block` at the same breakpoint.                                                               |
| `inline?`             | `union`                  | Amount to extend from both inline edges. Overrides `all` at the same breakpoint.                                                                    |
| `inlineEnd?`          | `union`                  | Amount to extend from the inline-end edge. Overrides `inline` at the same breakpoint.                                                               |
| `inlineStart?`        | `union`                  | Amount to extend from the inline-start edge. Overrides `inline` at the same breakpoint.                                                             |