# Sortable A Stimulus behavior that reorders a list with drag-and-drop and, optionally, saves the new position of each moved item to your server. Powered by [SortableJS](https://sortablejs.github.io/Sortable/). Put it on any container, like a list, a table body or a grid, and its children become draggable. ```twig ``` ## Installation > [!NOTE] > Available since UX Toolkit 3.7. ```shell php bin/console ux:install sortable --kit common ``` ## Usage Add `data-controller="sortable"` to the element whose children you want to reorder: ```twig ``` The other items slide out of the way as you drag. Set `animation` to change how long this takes, in milliseconds (`150` by default). Set it to `0` to disable the animation. ## Examples ### Drag Handle Set `handle` to a CSS selector to drag the items by a handle only. The rest of each item stays free, so you can select its text or click its links: ```twig ``` ### Fixed Items Set `draggable` to a CSS selector to choose which items can be dragged. By default, these are the `li` children of a list, or all the children of any other element. The other items stay where they are, like the slot to add a photo at the end of this grid. Start the selector with `>` to match the children of the controller element only, and not the elements inside them. When you [save the new position](#content-save-the-new-position), only the draggable items are counted. ```twig
A
B
C
D
E
Add a photo
``` ### Ignored Elements Set `filter` to a CSS selector of the elements that do not start a drag, like the buttons inside the items. Pressing one of them does not pick up its item. ```twig ``` ### Grid The items do not have to be stacked. In a grid, they move along both axes. ```twig
A
B
C
D
E
F
``` ### Save the New Position Give each item a `data-sortable-update-url`. When the item is dropped at a new index, the controller sends a `POST` request to that URL. Its `position` parameter holds the new position of the item, starting at 1. Set `csrfToken` to also send a CSRF token, as a `_token` parameter: ```twig ``` In your app, generate each URL with `path()`, and update the position in the matching controller: ```twig ``` ```php #[Route('/tasks/{id}/position', name: 'app_task_position', methods: ['POST'])] #[IsCsrfTokenValid('reorder-tasks')] public function position(Task $task, Request $request, EntityManagerInterface $entityManager): Response { $task->setPosition($request->getPayload()->getInt('position')); $entityManager->flush(); return new Response('', Response::HTTP_NO_CONTENT); } ``` This controller only changes the position of the moved task, so two tasks can end up with the same position. Your app must also shift the positions of the other tasks, or save the whole order with a form, as shown in the next section. The position counts only the items rendered in the list, so on a paginated list you must add the number of items on the previous pages. Set `paramName` to rename the `position` field. A value like `task[position]` nests the field the way a Symfony form names its fields. When Turbo is loaded on the page, the request also accepts a Turbo Stream response, and Turbo renders it. ### Submit the Order with a Form To save the whole order at once instead of each move, put the list in a form. The browser submits the fields in the order they appear on the page, so a hidden field in each item sends the ids in their new order. ```twig
``` The payload class receives the submitted ids through `#[MapRequestPayload]`, and its constraints reject an empty list, duplicate ids, and ids that are not strings of digits (the ids arrive as strings, because the Serializer does not convert the items of an array). ```php use Symfony\Component\Validator\Constraints as Assert; final class TaskOrder { /** * @param list $tasks */ public function __construct( #[Assert\NotBlank] #[Assert\Unique] #[Assert\All(new Assert\Type('digit'))] public array $tasks, ) { } } ``` The controller checks the CSRF token, receives the validated ids from first to last, and passes them to the repository. ```php #[Route('/tasks/order', name: 'app_task_order', methods: ['POST'])] #[IsCsrfTokenValid('reorder-tasks')] public function order(#[MapRequestPayload] TaskOrder $order, TaskRepository $taskRepository): Response { $taskRepository->reorder($order->tasks); return $this->redirectToRoute('app_task_index'); } ``` ## API Reference ### `data-controller="sortable"` | Value | Type | Default | Description | |:------|:-----|:--------|:------------| | `data-sortable-animation-value` | `Number` | `150` | How long, in milliseconds, the items take to slide into their new place while sorting; 0 disables the animation. | | `data-sortable-handle-value` | `String` | - | CSS selector of the drag handle inside each item; when omitted, an item is dragged from anywhere. | | `data-sortable-draggable-value` | `String` | - | CSS selector of the items that can be dragged; when omitted, the `li` children of a list, or all the children of any other element. | | `data-sortable-filter-value` | `String` | - | CSS selector of the elements that do not start a drag when pressed, like the buttons inside the items. | | `data-sortable-param-name-value` | `String` | `'position'` | Name of the field that carries the new position of the moved item among the draggable ones, starting at 1; a value like `task[position]` nests it like a Symfony form field. | | `data-sortable-csrf-token-value` | `String` | - | CSRF token sent with the request as the `_token` parameter, e.g. from `csrf_token('reorder-tasks')`. |