# Body

**Kind:** Function

**Source:** [`packages/common/decorators/http/route-params.decorator.ts`](https://github.com/nestjs/nest/blob/master/packages/common/decorators/http/route-params.decorator.ts#L502)

**Part of:** [Common](subsystem-packages-common)

Route handler parameter decorator. Extracts the entire `body` object
property, or optionally a named property of the `body` object, from
the `req` object and populates the decorated parameter with that value.
Also applies pipes to the bound body parameter.

For example:
```typescript
async create(@Body('role', new ValidationPipe()) role: string)
```

`Body()` binds a route handler parameter to the request `body` value. When given a property key, it extracts that property from `req.body`; pipes passed to the decorator run on the bound value.

## Signature

```ts
function Body(property: string | (Type<PipeTransform> | PipeTransform), pipes: (Type<PipeTransform> | PipeTransform)[]): ParameterDecorator
```

## Parameters

| Name | Type |
|---|---|
| `property` | `string | (Type<PipeTransform> | PipeTransform)` |
| `pipes` | `(Type<PipeTransform> | PipeTransform)[]` |

**Returns:** `ParameterDecorator`

## Diagram

```mermaid
graph LR
  Request[HTTP request] --> ReqBody[req.body]
  ReqBody --> BodyDecorator["@Body()"]
  BodyDecorator --> Property[Selected body property]
  Property --> Pipes[Pipes]
  Pipes --> Parameter[Route handler parameter]
```

## Usage

```typescript
import { Body, Controller, Post, ValidationPipe } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Post()
  async create(
    @Body('role', new ValidationPipe()) role: string,
  ) {
    return { role };
  }
}
```

## AI Coding Instructions

- Use `@Body()` when the handler needs the full request body.
- Pass a property key, such as `@Body('role')`, when the handler needs a single body field.
- Pass pipes after the property key so they receive the extracted value.
- Keep body-property names aligned with the request DTO or client payload.