# Getting Started with the KendoReact ListBox

This guide provides essential information about using the KendoReact ListBox package—you will learn how to install the ListBox package and add a free React ListBox component to your project.

<div data-component="StartKendoReactFreeSection"></div>

After completing this guide, you will have a free React [ListBox](https://www.telerik.com/kendo-react-ui/components/listbox) up and running.

[Demo Source](https://demos.telerik.com/kendo-react-ui/listbox/get-started/func/source.txt)

## Before You Begin

To follow the steps in this guide, you need to have a React project set up. If you don't have one, you can create a new React application using Vite by running the following command in your terminal:

```sh
npm create vite@latest my-app -- --template react-ts
```

This guide requires that you have **basic knowledge of React and TypeScript**, and that you have already created [**a blank React project**](https://www.telerik.com/kendo-react-ui/components/getting-started).

> tip You can speed up the development of your KendoReact application with the [Kendo UI Template Wizard for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=KendoUI.kendotemplatewizard).

## Install the Component

To install the ListBox package, run the following command in the root folder of your React project:

```sh
npm i @progress/kendo-react-listbox @progress/kendo-theme-meridian
```

Run these commands in the root of your React project to install the KendoReact ListBox package and its [dependencies](https://www.telerik.com/kendo-react-ui/components/listbox/get-started#kendoreact-listbox-dependencies), and the Kendo UI [Meridian theme](https://www.telerik.com/design-system/docs/themes/kendo-themes/meridian/).

## Import the Component

Place the `import` statements in the App component file (for example: `src/App.tsx`) for your project.

```tsx
import {
    ListBox,
    ListBoxToolbar,
    processListBoxData,
    ListBoxToolbarClickEvent,
    ListBoxItemClickEvent
} from '@progress/kendo-react-listbox';
```

## Use the Component

1. Import the data for the ListBox.

   ```tsx
   import { data } from './data';
   ```

2. Create a state variable to hold the data for the two ListBox components.

   ```tsx
   const [state, setState] = React.useState({
       employees: data,
       developers: []
   });
   ```

3. Set the [selectedField](https://www.telerik.com/kendo-react-ui/components/listbox/api/listboxprops#selectedfield) value. That value will determine which items are selected.

   ```tsx
   const SELECTED_FIELD = 'selected';
   ```

4. Handle the [onItemClick](https://www.telerik.com/kendo-react-ui/components/listbox/api/listboxprops#onitemclick) event of the ListBox to select or deselect items.

   ```tsx
   const handleItemClick = (event, data, connectedData) => {
       setState({
           ...state,
           [data]: state[data].map((item) => {
               if (item.name === event.dataItem.name) {
                   item[SELECTED_FIELD] = !item[SELECTED_FIELD];
               } else if (!event.nativeEvent.ctrlKey) {
                   // Without Ctrl, clicking an item clears the other selections.
                   item[SELECTED_FIELD] = false;
               }
               return item;
           }),
           // Clear the selection in the other list so tools act on one list.
           [connectedData]: state[connectedData].map((item) => {
               item[SELECTED_FIELD] = false;
               return item;
           })
       });
   };
   ```

5. Handle the [onToolClick](https://www.telerik.com/kendo-react-ui/components/listbox/api/listboxtoolbarprops#ontoolclick) event of the ListBoxToolbar to update the lists.

   ```tsx
   const handleToolBarClick = (e: ListBoxToolbarClickEvent) => {
       let toolName: string = e.toolName || '';
       let result: any = processListBoxData(state.employees, state.developers, toolName, SELECTED_FIELD);
       setState({
           ...state,
           employees: result.listBoxOneData,
           developers: result.listBoxTwoData
       });
   };
   ```

6. Add the markup of the two components to the `src/App.tsx` file in your project.

   ```tsx
   return (
       <div className="container">
           <div className="row justify-content-center">
               <div className="col k-pr-2">
                   <h6>Employees</h6>
                   <ListBox
                       style={{ height: 400, width: '100%' }}
                       data={state.employees}
                       textField="name"
                       selectedField={SELECTED_FIELD}
                       onItemClick={(e: ListBoxItemClickEvent) => handleItemClick(e, 'employees', 'developers')}
                       toolbar={() => {
                           return (
                               <ListBoxToolbar
                                   tools={[
                                       'moveUp',
                                       'moveDown',
                                       'transferTo',
                                       'transferFrom',
                                       'transferAllTo',
                                       'transferAllFrom',
                                       'remove'
                                   ]}
                                   data={state.employees}
                                   dataConnected={state.developers}
                                   onToolClick={handleToolBarClick}
                               />
                           );
                       }}
                   />
               </div>
               <div className="col k-pl-0">
                   <h6>Developers</h6>
                   <ListBox
                       style={{ height: 400, width: '100%' }}
                       data={state.developers}
                       textField="name"
                       selectedField={SELECTED_FIELD}
                       onItemClick={(e: ListBoxItemClickEvent) => handleItemClick(e, 'developers', 'employees')}
                   />
               </div>
           </div>
       </div>
   );
   ```

7. Build and run the application by typing the following command in the root folder of your project:

   ```sh
   npm run dev
   ```

8. Navigate to [http://localhost:5173](http://localhost:5173/) to see the KendoReact ListBox component on the page.

## Style the Components

> tip Are you looking for guidance around how to create visually appealing and consistent user interfaces with Telerik UI components? Check out the [Progress Design System](https://www.telerik.com/design-system/docs/).

To use the built-in styling of the components, start by installing a theme:

```sh
npm i @progress/kendo-theme-meridian
```

Import the CSS file from the package in `src/App.tsx`. Add this import before your existing `App.css` import:

```jsx
import '@progress/kendo-theme-meridian/dist/all.css';
```

With this import in place, you already have professionally designed styling applied to your app out-of-box. You can also try any of the other available [Kendo UI Themes](https://www.telerik.com/design-system/docs/themes/get-started/introduction/#available-themes).

## KendoReact ListBox APIs

[ListBox API](https://www.telerik.com/kendo-react-ui/components/listbox/api)

## KendoReact ListBox Dependencies

The ListBox package requires you to install the following [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies/) in your application:

| Package Name                  | Description                                                                                                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| react 18.0.0\*                | Contains the functionality necessary to define React components.                                                                                                            |
| react-dom                     | Contains the React renderer for the web.                                                                                                                                    |
| @progress/kendo-licensing     | Contains the internal infrastructure related to licensing.                                                                                                                  |
| @progress/kendo-react-intl    | Contains the KendoReact Internationalization package that applies the desired cultures by providing services and pipes for the parsing and formatting of dates and numbers. |
| @progress/kendo-svg-icons     | Contains the KendoReact SVG icons.                                                                                                                                          |
| @progress/kendo-react-buttons | Contains the KendoReact Buttons components.                                                                                                                                 |
| @progress/kendo-react-common  | Contains common utilities that enhance the performance and functionalities of the KendoReact UI components.                                                                 |

## Suggested Links

* [Virtual Classroom (Introductory Course Available to Trial and Commercial License Holders)](https://learn.telerik.com/learn/course/external/view/elearning/14/kendoreact)
* [Explore the Finance Portfolio Sample Application](https://www.telerik.com/kendo-react-ui/components/sample-applications/finance-application/)
* [Explore the Coffee Warehouse Sample Application](https://www.telerik.com/kendo-react-ui/components/sample-applications/react-coffee-warehouse-dashboard/)
* [Explore the GitHub Issues Grid Sample Application](https://www.telerik.com/kendo-react-ui/components/sample-applications/issues-grid/)
