Tailwind CSS Starter

The Tailwind Starter, which serves as the base for the sample created on this document site, applies Tailwind CSS as the stylesheet framework based on the Next.js Starter. This document introduces the work done on the base Next.js Starter.

The base of the template was created as follows:

Creating the Template

Creating the Site

First, launch XM Cloud in a SaaS environment based on the above template.

Select Empty as the template for the site to be created.
Create the site as shown below and prepare the site to be worked on in the XM Cloud development environment.
Work will proceed with the Next.js Starter Kit’s Basic site and the site created above side by side.
In Pages, link with the local Next.js instance to check the page display using the development code.

Since Empty is selected this time, nothing is displayed as shown below.
Open the Content Editor, select the item /sitecore/content/sites/tailwind-starter/Settings as the JSS setting, and change the Grid setting to Tailwind.
Next, open the site setting /sitecore/content/sites/tailwind-starter/Settings/Site Grouping/tailwind-starter and change the Predefined application editing host to tailwindstarter.

The environment for development is now ready.

Applying Tailwind CSS

Since the Next.js Starter Kit uses Bootstrap as the CSS framework, Tailwind CSS will be applied while removing unnecessary bootstrap packages.

Installing Tailwind CSS

First, rewrite to enable the use of Tailwind CSS.

First, install Tailwind CSS.

npm install tailwindcss @tailwindcss/postcss postcss

Copy the src/assets/app.css file and create src/styles/app.css.
Create the src/styles/globals.css file and set the following styles.
```
@import 'tailwindcss';

@import './app.css';
```

Modify the code in src/pages/_app.tsx to load the stylesheet as follows.

import type { AppProps } from 'next/app';
import { I18nProvider } from 'next-localization';
import { SitecorePageProps } from 'lib/page-props';
import Bootstrap from 'src/Bootstrap';

import 'assets/main.scss';
import '@/styles/globals.css';

Create the postcss.config.mjs file and add the following code.

const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
export default config;

To enable the use of @/ when loading the stylesheet, add the following lines to the Typescript configuration tsconfig.json.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "components/*": ["src/components/*"],
      "lib/*": ["src/lib/*"],
      "temp/*": ["src/temp/*"],
      "assets/*": ["src/assets/*"],
      "graphql-types": ["node_modules/@types/graphql-let/__generated__/__types__"],
      "react": ["node_modules/react"],
      "@/*": ["./src/*"]
    },

Now Tailwind CSS is applied. You can confirm that the stylesheet is applied by accessing it with npm run start:connected and checking with developer tools since there is no content yet.

tailwind css

Removing Bootstrap

Next, remove the Bootstrap-related files that will no longer be used.

Delete the folder src/assets where the stylesheet-related files are located.
Uninstall the bootstrap and font-awesome packages.
Terminal window
```
npm uninstall bootstrap font-awesome
```

This removes the bootstrap-related files.

Adjusting Stylesheets

The above work only switches the stylesheet framework, and no styles are defined for each component. Therefore, add styles for some components.

Grid

Two frequently used components are Column Splitter and Row Splitter. When placing the Column Splitter, it looks like this.

Column Splitter

The expected result is to be arranged horizontally, but it is arranged vertically. The HTML output is as follows.

<div class="row component column-splitter basis-full">
  <div class="basis-1/2"><div class="row"></div></div>
  <div class="basis-1/2"><div class="row"></div></div>
</div>

To arrange them horizontally, add the flex class. Create a file src/styles/components/ColumnSplitter.css and apply the following code.

.column-splitter {
  @apply flex;
}

As a result, the display changes as follows.

Column Splitter

They are arranged horizontally, but the width specified by basis-1/2 is not applied. Tailwind CSS disables styles not specified in the code to keep the stylesheet simple, so the styles output by the component are not applied.

Therefore, add the following code to the configuration file tailwind.config.js to enable the use of salelist.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  safelist: [
    {
      pattern: /basis-/,
      variants: ['sm', 'md', 'lg', 'xl', '2xl'],
    },
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Successfully, they are arranged horizontally with the 1/2 width applied.

Column Splitter

Display Options

This time, use the RichText editor to add styles for the component’s display position and text position. First, place the RichText component using Pages.

RichText Components

When placed, the component options display Spacing / Add Highlight / Content Alignment / Rich Text settings. Rich Text will be covered separately, but for example, set the items as follows.

RichText Options

When set, the HTML code changes as follows.

<div id="content">
  <!--$-->
  <div class="component rich-text indent-bottom highlighted-left position-center basis-full">
    <div class="component-content">
      <div>
        <div class="ck-content"><p>Text</p></div>
      </div>
    </div>
  </div>
  <!--/$-->
</div>

These definitions are defined as items within the site being built. Refer to the site’s tree as follows. The values listed on the right side of the items are the values output to the CSS.

DirectoryPresentation
- DirectoryStyles
  - DirectorySpacing
    Indent top indent-top
    Indent bottom indent-bottom
    Indent side indent
  - DirectoryAdd highlight
    Highlighted left highlighted-left
    Highlighted right highlighted-right
    Highlighted top highlighted-top
    Highlighted bottom highlighted-bottom
  - DirectoryContent alignment
    Align content left position-left
    Align content center position-center
    Align content right position-right

Spacing and Content alignment are general display options that can also be used for images. Create two files for common styles.

.position-left {
  @apply flex;
  @apply justify-start;
}

.position-right {
  @apply flex;
  @apply justify-end;
}

.position-center {
  @apply flex;
  @apply justify-center;
}

.highlighted-left {
  @apply border-l-4;
  @apply border-blue-500;
}

.highlighted-right {
  @apply border-r-4;
  @apply border-blue-500;
}

.highlighted-top {
  @apply border-t-4;
  @apply border-blue-500;
}

.highlighted-bottom {
  @apply border-b-4;
  @apply border-blue-500;
}

.indent {
  @apply mx-3;
}

.indent-top {
  @apply mt-3;
}

.indent-bottom {
  @apply mb-3;
}

Add the above three files to the globals.css file.

@import './app.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Pages Style - Common */
@import './common/alignment.css';
@import './common/highlight.css';
@import './common/spacing.css';

/* Components */
@import './components/ColumnSplitter.css';

This reflects the display position as follows.

RichText spacing

Rich Text

For the HTML inside the RichText component, let’s start by setting up paragraphs as follows:

<p>Paragraph</p>
<ul>
  <li>Bullets 1</li>
  <li>Bullets 2</li>
  <li>Bullets 3</li>
</ul>
<p>Paragraph</p>
<ol>
  <li>Number 1</li>
  <li>Number 2</li>
  <li>Number 3</li>
</ol>

When using Tailwind CSS, if nothing is defined, it will be displayed flat as shown below.

HTML List

We need to add definitions for the display in RichText. This also needs to be applied to tags like h1, so let’s create a file to define the styles for RichText as follows:

.component.rich-text {
  h1 {
    @apply text-4xl;
  }

  h2 {
    @apply text-3xl;
  }

  h3 {
    @apply text-2xl;
  }

  ul {
    @apply list-disc pb-2 pl-3 pt-2;
  }

  ol {
    @apply list-decimal pb-2 pl-3 pt-2;
  }

  li {
    @apply ml-4;
  }
}

After importing the above styles in the src/styles/globals.css file, you can preview the changes and see that the display has been updated.

HTML List

There are also sample values prepared to display styles for Rich Text.

DirectoryPresentation
- DirectoryStyles
  - DirectoryRich-text
    Custom-bullet-points rich-text-lists

To enable this and change the list display, add the following code to src/styles/components/RichText.css:

.component.rich-text.rich-text-lists {
  ul {
    @apply list-disc px-2 pl-9 text-2xl;
  }
}

After setting this, checking the display options for the RichText component will enlarge the list text.

HTML List

Container Background Color

Containers can hold various components and can be very useful for controlling display and responsiveness at the container level. The styles prepared specifically for containers are as follows:

DirectoryPresentation
- DirectoryStyles
  - DirectoryBackground color
    Clean background container-clean-background
    Color background container-color-background
    Dark background container-dark-background
    Gray background container-gray-background
  - DirectoryBackground layout
    Cover background cover-background
    Fix background fix-background
    Parallax background parallax-background
  - DirectoryContainer
    Centered container
    Bordered sxa-bordered

To define only the background color part, add the following stylesheet:

.container-dark-background {
  @apply bg-gray-800 text-white;
}

.container-color-background {
  @apply bg-blue-400 text-gray-800;
}

.container-gray-background {
  @apply bg-gray-300 text-gray-800;
}

.container-clean-background {
  @apply bg-white text-gray-800;
}

Add the above file to src/styles/globals.css to enable the container background colors. Below is the result of placing a container and specifying the background color.

Container background

LinkList

To check the display of the standard list component, first create sample items and place them in Pages, which will be displayed as follows:

LinkList

The actual HTML output is as follows:

<div class="component link-list basis-full">
  <div class="component-content">
    <h3>LinkList</h3>
    <ul>
      <li class="item0 odd first">
        <div class="field-link">
          <a href="https://doc.sitecore.com/" target="">Sitecore Documentation</a>
        </div>
      </li>
      <li class="item1 even">
        <div class="field-link">
          <a href="https://developers.sitecore.com/" target="">Sitecore Developers</a>
        </div>
      </li>
      <li class="item2 odd last">
        <div class="field-link"><a href="https://www.sitecore.com/" target="">Sitecore.com</a></div>
      </li>
    </ul>
  </div>
</div>

For the above HTML, you can use the list styles from RichText. Therefore, add the following file:

.component.link-list {
  ul {
    @apply list-disc pb-2 pl-3 pt-2;
  }

  ol {
    @apply list-decimal pb-2 pl-3 pt-2;
  }

  li {
    @apply ml-4;
  }
}

Add the above file to src/styles/globals.css to display the link list as shown below.

LinkList with List

The Navigation component has several styles prepared, and explaining all of them would be lengthy, so let’s adjust one navigation style for now. First, create sample items and arrange them hierarchically in the site pages as follows:

Directoryhome
- Directoryproducts
  - Directorysitecore-language-switcher/
    …
  - Directorytailwindcss/
    …
- Directoryresources
  - Directorycomponents/
    …
  - Directorynextjs/
    …
- Directoryblog/
  - …

Using the above content tree, place the Navigation component, which will be displayed as follows. When using Tailwind CSS, it is initially displayed flat.

Site content tree

The actual HTML output is as follows:

<div class="component navigation basis-full">
  <label class="menu-mobile-navigate-wrapper"
    ><input type="checkbox" class="menu-mobile-navigate" />
    <div class="menu-humburger"></div>
    <div class="component-content">
      <nav>
        <ul class="clearfix">
          <li class="level1 submenu item0 odd first rel-level1" tabindex="0">
            <div class="navigation-title child">
              <a title="Products" href="/products?sc_site=tailwind-starter"
                ><span>Products</span></a
              >
            </div>
            <ul class="clearfix">
              <li class="level2 item0 odd first rel-level2" tabindex="0">
                <div class="navigation-title">
                  <a
                    title="Sitecore Language Switcher"
                    href="/products/sitecore-language-switcher?sc_site=tailwind-starter"
                    ><span>Sitecore Language Switcher</span></a
                  >
                </div>
              </li>
              <li class="level2 item1 even last rel-level2" tabindex="0">
                <div class="navigation-title">
                  <a
                    title="Tailwind CSS Starter Kit"
                    href="/products/tailwindcss?sc_site=tailwind-starter"
                    ><span>Tailwind CSS Starter Kit</span></a
                  >
                </div>
              </li>
            </ul>
          </li>
          <li class="level1 submenu item1 even rel-level1" tabindex="0">
            <div class="navigation-title child">
              <a title="Resources" href="/resources?sc_site=tailwind-starter"
                ><span>Resources</span></a
              >
            </div>
            <ul class="clearfix">
              <li class="level2 item0 odd first rel-level2" tabindex="0">
                <div class="navigation-title">
                  <a title="Components" href="/resources/components?sc_site=tailwind-starter"
                    ><span>Components</span></a
                  >
                </div>
              </li>
              <li class="level2 item1 even last rel-level2" tabindex="0">
                <div class="navigation-title">
                  <a title="Next.js" href="/resources/nextjs?sc_site=tailwind-starter"
                    ><span>Next.js</span></a
                  >
                </div>
              </li>
            </ul>
          </li>
          <li class="level1 item2 odd last rel-level1" tabindex="0">
            <div class="navigation-title">
              <a title="Blog" href="/blog?sc_site=tailwind-starter"><span>Blog</span></a>
            </div>
          </li>
        </ul>
      </nav>
    </div></label
  >
</div>

The styles added to the display options for the menu are defined in the site’s styles as follows. This time, let’s enable Main navigation - Drop down vertical and Main navigation - Drop down horizontal, and leave the mobile implementation for later.

DirectoryPresentation
- DirectoryStyles
  - DirectoryNavigation
    Main navigation - Drop down vertical navigation-main navigation-main-vertical
    Main navigation - Drop down horizontal navigation-main navigation-main-horizontal
    Mobile navigation navigation-mobile
    Sidebar navigation navigation-sidebar
    Sitemap navigation sitemap-navigation
    Big/Fat navigation navigation-fat

The actual stylesheet will adjust the top-level display with navigation-main, display the menu vertically with navigation-main-vertical, and display the submenu horizontally with navigation-main-horizontal. Below is the completed code:

.component.navigation.navigation-main {
  .rel-level1 {
    @apply relative float-left mx-3;
  }

  .rel-level2 {
    @apply mx-5 mb-3;
  }

  &.navigation-main-vertical {
    .rel-level1 {
      &:hover {
        > ul {
          @apply absolute left-0 top-full z-10 block w-max min-w-[200px] border border-gray-300 bg-white pt-3 shadow-md;
        }
      }

      > ul {
        overflow: hidden;
        display: none;
      }
    }
  }

  &.navigation-main-horizontal {
    .rel-level1 {
      &:hover {
        > ul {
          @apply absolute left-0 top-full z-10 flex w-screen border border-gray-300 bg-white pt-3 shadow-md;
        }
      }

      > ul {
        overflow: hidden;
        display: none;
      }
    }
  }
}

.menu-mobile-navigate {
  display: none;
}

Below is a video showing the two menus placed and their respective behaviors.

Navigation

Summary

This time, we introduced the initial steps for using Tailwind CSS stylesheets based on the Next.js Starter Kit provided by Sitecore. By following this walkthrough, you can learn how to manage stylesheets and how to call and apply site styles when holding styles on the Sitecore side.

References

Install Tailwind CSS with Next.js

Update Information

2024-01-24 Upgrade to Tailwind CSS 4.0