Documentation
Feedback
Guides
Storefront Development

Storefront Development
Store FrameworkStyling
Contributing with new CSS Handles

CSS Handles are CSS classes mapped to HTML elements, allowing for flexible customization of store components. The more CSS Handles available, the greater the potential for design customization.

This guide walks you through adding a new CSS Handle, using the customization of a filter on the Search Results page as an example.

Before you begin

Before you begin, we recommend installing the React Chrome extension to inspect the React component tree of any store page.

Instructions

Step 1 - Identifying the React component

  1. Open the store page you are working on.

  2. Right-click on the HTML element you want to customize, then select Inspect. You should see the HTML structure like the following example:


    _10
    <div tabindex="0" role="link" class="ph5 ph3-ns pv5 pv1-ns lh-copy pointer hover-bg-muted-5 c-muted-1">Hats</div>

  3. In Chrome Dev Tools, go to the Components tab and find the React component that wraps this element. For example, CategoryItem.

    {"base64":"  ","img":{"width":199,"height":84,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":5992,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-contributing-with-new-css-handles-0.png"}}

Step 2 - Forking the app's repository

  1. Fork the repository of the app that contains the block wrapping the HTML element you are targeting.

  2. Clone the forked repository to your local files.


    _10
    git clone {repoUrl}

  3. Open the project in your preferred code editor and locate the React component identified earlier (e.g., CategoryItem.jsx).

Step 3 - Adding a new CSS Handle

Now, depending on how the component imports its CSS, there are two ways to add a CSS Handle:

  • Using the import {useCssHandles} from 'vtex.css-handles' function.
  • Using the import styles from './styles.css' function.

Using the import {useCssHandles} from 'vtex.css-handles' function

  1. Locate the variable passed to the useCssHandles hook (e.g., CSS_HANDLES).

    CategoryItem.jsx

    _10
    const CSS_HANDLES = ['container', 'element']
    _10
    // ...
    _10
    const handles = useCssHandles(CSS_HANDLES)

  2. Add the new CSS Handle to the array:


    _10
    const CSS_HANDLES = [
    _10
    'container',
    _10
    'element',
    _10
    + 'headline',
    _10
    ]

    Note that the useCssHandles hook will create an object where each key corresponds to the CSS Handle you defined, and the value is a unique, automatically generated CSS class name. So, handles.container, handles.element, and handles.headline will contain these generated class names. For a component called foobar, the generated class names might look like this: vtex-foobar-1-x-container, vtex-foobar-1-x-element, vtex-foobar-1-x-headline.

  3. Apply the new CSS Handle to the desired HTML element using the handles variable:

    CategoryItem.jsx

    _10
    - <div className="ph0 mr2">
    _10
    + <div className={`$\{handles.headline\} ph0 mr2`}>

  4. Save your changes.

Using the import styles from './styles.css' function

  1. Identify and open the CSS file imported in the component (e.g., searchResult.css):

    CategoryItem.jsx

    _10
    import styles from '../searchResult.css'

  2. Add a new class to the CSS file with the name of the new CSS Handle:

    searchResult.css

    _10
    .headline {}

  3. Go back to the React component file and add the new CSS Handle to the desired HTML element. Remember to use the name of the function variable (in our example, styles) when adding it:

    CategoryItem.jsx

    _10
    - <div className="ph0 mr2">
    _10
    + <div className={`$\{styles.headline\} ph0 mr2`}>

  4. Save your changes.

Step 4 - Checking your changes

  1. Using the terminal and the VTEX IO CLI, log in to a VTEX account and use a Development workspace to link the app you are working on.
  2. Access the account's website through the development workspace ({workspaceName}--{accountName}.myvtex.com) and inspect the modified HTML element to verify if the new CSS class is being applied correctly.

Following our example, we would have something like:


_10
<div class="vtex-foobar-1-x-headline ph0 mr2">

(Optional) Step 5 - Adding modifiers

To customize elements based on user interactions, you can apply modifiers to CSS Handles.

Handle modifiers work as identifiers. They are responsible for overriding the HTML element style according to the behavior assumed by them on the interface, according to user interaction.

Let's suppose you have a handle called handles.slide for each slide of a slider and want to customize the currently visible slide via CSS. For this purpose, you should add a modifier to handles.slide, allowing customization according to the user's navigation.

  1. Import the applyModifiers method:

    import {useCssHandles, applyModifiers} from 'vtex.css-handles'

  2. Instead of directly passing the handle, apply the applyModifiers method:


    _10
    -<div class={{`$\{handles.slide\}`}}">...</div>
    _10
    +<div class={{`$\{applyModifiers(handles.slide, isCurrentSlide ? 'active' : undefined\}`}}">...</div>

    This results in:


    _10
    <div class="vtex-foobar-1-x-slide vtex-foobar-1-x-slide--active">...</div>
    _10
    <div class="vtex-foobar-1-x-slide">...</div>
    _10
    <div class="vtex-foobar-1-x-slide">...</div>

Step 6 - Committing your changes

After verifying that the new CSS class is correctly rendered, follow these steps to commit and submit your updates:

  1. Use Git and GitHub to create a new branch for your changes.

  2. Open the CHANGELOG.md file and add a new entry under the [Unreleased] section to briefly describe your changes. For example:


    _10
    ## [Unreleased]
    _10
    ### Added
    _10
    - New CSS Handle `headline`.

  3. In the docs folder, update the documentation to include the new CSS Handle. Modify the Customization section and the CSS Handles table as in the example below:


    _10
    | CSS Handles |
    _10
    | ----------- |
    _10
    | `container` |
    _10
    | `element` |
    _10
    +| `headline` |

  4. Commit your updates with a clear, descriptive message.

  5. Push your branch to your forked repository.

  6. Open a Pull Request for the team. In the Pull Request description, include a link to the development workspace where your changes can be tested. For example: https://john--storecomponents.myvtex.com.

After your Pull Request is reviewed and approved, your changes will be merged, making the new CSS Handle available to other users and contributing to the app's improvement.

Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
See also
Using CSS handles for store customizations
Guides
Contributors
1
Photo of the contributor
+ 1 contributors
On this page