All docs
V20.1
20.2 (CTP)
20.1
19.2
19.1
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
17.1
The page you are viewing does not exist in version 17.1. This link will take you to the root page.
16.2
The page you are viewing does not exist in version 16.2. This link will take you to the root page.

Create a DevExtreme Application

If you are starting a project from scratch, use the DevExtreme React Template. It is a simple application with a navigation menu and several sample views in a responsive layout (see live preview).

You can generate the application with the DevExtreme CLI:

npx -p devextreme-cli devextreme new react-app app-name
cd app-name
npm run start

The application already contains the DataGrid and Form components. You can find their configurations in the src\pages\display-data\display-data.js and src\pages\profile\profile.js files correspondingly.

For further information about DevExtreme React components, refer to the following resources:

For more information about the structure and contents of the DevExtreme React Template, continue reading this article.

Layouts

The application includes two layouts. The only difference between them is where the toolbar is located.

  • Outer Toolbar (default)
    DevExtreme React Template - Outer toolbar

  • Inner Toolbar
    DevExtreme React Template - Inner toolbar

To generate a new application with an inner toolbar, set the --layout flag to side-nav-inner-toolbar:

npx devextreme-cli new react-app app-name --layout=side-nav-inner-toolbar

To switch to another layout after the application is created, open the src\Content.js file and replace the SideNavOuterToolbar import with SideNavInnerToolbar:

Content.js
import {
  SideNavInnerToolbar as SideNavBarLayout,
  SingleCard
} from './layouts';

Add a New View

Run the following command to add a new view. --icon specifies an icon from the DevExtreme icon library.

npx devextreme add view view-name [--icon=IconName]

You can find the added view under the src\pages folder. This command also creates a navigation menu item for the added view in the src\app-navigation.js file.

Configure the Navigation Menu

Configure Menu Items

Edit the src\app-navigation.js file to configure navigation menu items. Each item configuration can have the following fields:

  • text - the item's text

  • icon - the item's icon

  • path - a navigation path associated with the item

  • items - child items

NOTE
A menu item should either navigate to a page OR include subitems. For that reason, do not specify both path and items for the same menu item.
JavaScript
{
    text: 'Category',
    icon: 'folder',
    items: [{
        text: 'About',
        path: '/about'
    }]
}

Hide the Menu in the Closed State

In the closed state, the navigation menu is partially visible because it displays item icons. If the items do not have icons, you can hide the menu. To do this, open the SideNavOuterToolbar or SideNavInnerToolbar component (depending on the used layout), find the Drawer configuration, and set its minSize option to 0:

side-nav-outer-toolbar.js
// ...
export default function ({ title, children }) {
    // ...
    return (
        <div className={'side-nav-inner-toolbar'}>
            <Drawer ...
                minSize={0}>
                {/* ... */}
            </Drawer>
        </div>
    );
}

Add a Custom Toolbar Item

The application template uses the DevExtreme Toolbar component. The Toolbar is part of the Header component whose configuration is in the src\components\header\header.js file. To add a custom toolbar item, open this file and add an Item element inside Toolbar. Refer to the items help section for information on Item attributes.

The following code adds a search button to the toolbar:

header.js
side-nav-outer-toolbar.js
// ...
export default ({ ..., search }) => (
    <header className={'header-component'}>
        <Toolbar className={'header-toolbar'}>
            {/* ... */}
            <Item location="after">
                <Button icon="search" onClick={search} />
            </Item>
            {/* ... */}
        </Toolbar>
    </header>
)
// ...
export default function ({ title, children }) {
    // ...
    const search = useCallback(() => {
        console.log("search");
    }, []);

    return (
        <div className={'side-nav-outer-toolbar'}>
            <Header ...
                search={search}
            />
            {/* ... */}
        </div>
    );
}

In the code above, the button click handler is declared in the SideNavOuterToolbar component. This component applies when the outer toolbar layout is used. If the application uses the inner toolbar layout, add the same code to the SideNavInnerToolbar component.

Configure Themes

Switch the Theme

The DevExtreme React Template uses a main theme for the view content and an additional theme (color swatch) for the navigation menu. To switch to another theme, open the src\themes\metadata.base.json or src\themes\metadata.additional.json file and assign a theme name to the baseTheme field:

metadata.base.json
{
    // ...
    "baseTheme": "material.blue.light",
    // ...
}

You can find all theme names in the Predefined Themes help topic.

Run the following command to rebuild themes:

npm run build-themes

Create a Custom Theme

You can use the DevExtreme ThemeBuilder to create custom themes based on predefined themes. Follow the steps below:

  1. Import src\themes\metadata.base.json or src\themes\metadata.additional.json to the ThemeBuilder.

  2. Customize the theme.

  3. Export theme metadata to the initial file (see Postpone Customization).

Run the following command to rebuild themes:

npm run build-themes

Apply a Color Swatch

Color swatches are secondary color schemes used alongside a primary color scheme.

In the DevExtreme React Template, a color swatch is applied to the navigation menu and is configured in the src\themes\metadata.additional.json file. To apply this color swatch to an element, add the dx-swatch-additional class to this element:

JSX
<div className={'dx-swatch-additional'}>
    <!-- Your content here -->
</div>

Apply Theme Variables to Custom Elements

Theme variables are defined in the src\themes\generated\variables.base.scss and src\themes\generated\variables.additional.scss files. Apply them to custom elements, so that the elements have a uniform appearance with the rest of the application.

The following code applies the $base-accent variable as the background-color of my-element:

SCSS
// Your SCSS file
@import "../../../themes/generated/variables.base.scss";

#my-element {
    background-color: $base-accent;
}

Authentication

A DevExtreme React application includes authentication UI and API. Client-side routing is configured so that unauthenticated users can navigate to authentication pages only. These pages allow the users to sign in, create a new account, or reset the password.

Authentication pages are rendered by the NonAuthenticatedContent.js component. The rest of the application is rendered by the Content.js component.

IMPORTANT
Do not rely on client-side routing to protect your application from unauthorized access. Always verify user credentials on the back end.

Integrate with a Back End

Stub authentication functions for back-end requests are located in the src\api\auth.js file. Update these functions to make actual requests to your back end.

Each function returns an object with the following fields:

Field Description
isOk A Boolean value that is true if the request was successful and false otherwise.
message An error message (if an error occurred).
data The request result (user information).

Get User Information

User information is stored in a context declared in the contexts\auth.js module.

To access user information from any part of the application, use the useAuth hook. This hook returns an object with the following fields:

Field Description
user An object with information about the current user; undefined if the user is not authenticated.
setUser A function that updates information about the current user; accepts an object with new user information.
loading A Boolean value that is true while user information is being loaded (an HTTP request is in progress).

The following code uses the useAuth hook to access user information:

JSX
import { useAuth } from './contexts/auth'; 

export default function() { 
    const { user } = useAuth(); 
    if (user) { 
        // User is authenticated 
        ...
    } 
    ... 
} 

Create an Empty Application

To generate an application without views and a navigation menu, use the --empty flag:

npx devextreme-cli new react-app app-name --empty