After defining your theme's block, it is time to think about the style you want for it, defining colors, typography, among other elements that establish the visual identity of the app when it is rendered.
To define the style of your component(s), we will use Cascading Style Sheets - CSS.
In VTEX IO, there are three different tools for using CSS in a store:
- Tachyons - Main option for styling components from CSS classes.
- CSS Modules - Secondary option for styling components from CSS classes. It should only be used when the desired style cannot be configured using Tachyons.
- CSS Handles - Exports generic CSS classes to allow users that work with your component to customize it according to their respective scenarios.
Now that you know the difference between the tools that are available on the platform, you are ready to learn more about them.
Below, you can find the instructions for each of these tools and their purpose.
Customizing the style in a component requires basic CSS knowledge. We recommended that you check the documentation for this language before following the instructions detailed in this article.
Using Tachyons
VTEX Tachyons is a functional CSS structure built on a Tachyons base.
The framework has single-purpose CSS classes that can be structured to build anything from complex layouts to responsive components.
In practice, VTEX Tachyons helps you use CSS classes in your store-front app with little effort.
To better understand VTEX Tachyons tokens for CSS classes, it is important to familiarize yourself with the Tachyons solution. Carefully read your documentation.
- Open your app's code in your code editor.
- In the
react
folder, access the file created for the component you want to style. - Access the VTEX Tachyons documentation and look for the most appropriate CSS classes according to the customization you want to apply.
- In the React component code, declare the desired CSS classes. For example:
const Example = () => (
<div className="flex justify-center pv4 ph3 bg-base--inverted">
<p>Hello, World!</p>
</div>
)
- Save your changes.
Using CSS Modules
CSS Modules is a CSS file in which CSS classes are designed according to the store-front app that exports the component.
By defining CSS classes this way, the CSS Modules tool becomes limiting when considering the scenarios for importing and exporting components between different apps. That is why we recommend only using VTEX Tachyons in your project. Use CSS Modules only for cases not solved by Tachyons.
- In your app's
react
folder, create thestyles.css
file. - In this file, create the desired CSS classes (those not understood by Tachyons tokens). For example:
.myButton {
background-color: red;
}
- Still in the
react
folder, access the component file being customized and import thestyles
file, created in step 1. For example:
import styles from './styles.css'
- It is also possible to import the
styles
file so that the generated CSS classes are private, that is, they are generated with a unique identifier (hash) instead of the traditionalvendor-app-major-x-format-classname
. For this, you need to do an import following the model below:
import styleModule from './style.module.css'
- From there, the
styles
imported for your component will be an object whose keys will be the names of the classes you created (className
). For example:
/* /react/MyButton.tsx */
import styles from './styles.css'
export default function MyButton() {
return (
<button className={styles.myButton}>
My button
</button>
)
}
Remember that the name of the created classes will depend on the import model you made (step 3 or step 4 in this section).
- Save the changes you made and link your app.
When rendered and inspected, the component will now have the following HTML structure if you chose to follow the import model shown in step 3:
<button class="vtex-my-app-name-0-x-myButton">My button</button>
Using CSS Handles
A CSS Handle is an HTML element identifier. That is why Handles are very handy when creating store themes, allowing your app users to apply CSS classes according to the visual identity they want.
To make Handles available for future app users, add vtex.css-handles
to the dependencies
list in the manifest.json
file:
"dependencies": {
+ "vtex.css-handles": "0.x"
}
Once vtex.css-handles
is added as a dependency, your app is ready to generate CSS Handles.
However, when generating them, you will need to pay attention to how your app's React component(s) are imported and defined.
There are two possible scenarios:
- Function components - React components are defined in your app using a function.
- Class components - React components are defined in your app using a class.
Creating CSS Handles for function components
- In your app's
react
folder, access the file of the React component you want. - Copy and paste the following code example in the file:
import { useCssHandles } from 'vtex.css-handles'
const CSS_HANDLES = ['container', 'background', 'text', 'item'] as const
/* Using `as const` at the end hints to Typescript that this array
* won't change, thus allowing autocomplete and other goodies. */
const Component: FC = () => {
const handles = useCssHandles(CSS_HANDLES)
- In the
CSS_HANDLES
array, replace the exemple strings with new ones (according to the names of the CSS Handles you want). You can choose any name for the CSS Handle, but remember, it will be used with CSS classes by your app users to personalize HTML elements in stores. We recommend choosing intuitive names.
Following the above example, the variable (CSS_HANDLES)
will be an object using the following format:
{
container: 'vtex-foobar-1-x-container',
background: 'vtex-foobar-1-x-background',
text: 'vtex-foobar-1-x-text',
item: 'vtex-foobar-1-x-item',
}
Note that the CSS Handles generated and stored in the object follow this pattern:
vtex-{appName}-{majorVersion}-x-{handleName}
.
- Add the new CSS Handle to the desired CSS class–according to the HTML element to be customized by app users. Remember to use the
handle
variable when adding it and also the CSS Handle name defined in theCSS_HANDLES
array (likecontainer
). For example:
<div className={handles.container}>
<div className={`$\{handles.background\} bg-red`}>
<h1 className={`$\{handles.text\} f1 c-white`}>Hello world</h1>
<ul>
{['blue', 'yellow', 'green'].map(color => (
<li
className={`$\{handles.item\} bg-$\{color\}`}>
Color {color}
</li>
))}
</ul>
</div>
</div>
Creating CSS Handles for class components
- In your app's
react
folder, access the file of the React component you want. - Copy and paste the following code example in the file:
import { withCssHandles } from 'vtex.css-handles'
const CSS_HANDLES = ['text'] as const
class ExampleComponent extends Component {
render() {
const { cssHandles } = this.props
Since components defined as classes cannot use hooks, we will use an HOC called
withCssHandles
.
- In the
CSS_HANDLES
array, replace the example strings with new ones (according to the names of the CSS Handles you want). You can choose any name for the CSS Handle, but remember, it will be used with CSS classes by your app users to personalize HTML elements. We recommend using intuitive names.
Following the above example, the variable { cssHandles }
will be an object using the following format:
{
text: 'vtex-foobar-1-x-text',
}
Note that the CSS Handles generated and stored in the object follow this pattern:
vtex-{appName}-{majorVersion}-x-{handleName}
.
- Add the new CSS Handle to the desired CSS class–according to the HTML element to be customized by app users. Remember to use the
handle
variable when adding it and also the CSS Handle name defined in theCSS_HANDLES
array (liketext
). For example:
<div className={`$\{cssHandles.text\} f1 c-white`}>Hello world</div>
After saving your changes, your app will be able to not only export a predefined style according to the CSS classes you set up but also export CSS Handles, giving your users more customization flexibility.
For more details on how CSS Handles can be used to define styles, access the documentation for Using CSS Handles for store customization.