Skip to content

Latest commit

 

History

History
284 lines (202 loc) · 7.74 KB

functions-and-directives.mdx

File metadata and controls

284 lines (202 loc) · 7.74 KB

import { CodeExampleStack } from "@/components/code-example";

export const title = "Functions and directives"; export const description = "A reference for the custom functions and directives Tailwind exposes to your CSS.";

Directives

Directives are custom Tailwind-specific at-rules you can use in your CSS that offer special functionality for Tailwind CSS projects.

@import

Use the @import directive to inline import CSS files, including Tailwind itself:

/* [!code filename:CSS] */
@import "tailwindcss";

@theme

Use the @theme directive to define your project's custom design tokens, like fonts, colors, and breakpoints:

/* [!code filename:CSS] */
@theme {
  --font-display: "Satoshi", "sans-serif";

  --breakpoint-3xl: 120rem;

  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.98 0.04 113.22);
  --color-avocado-300: oklch(0.94 0.11 115.03);
  --color-avocado-400: oklch(0.92 0.19 114.08);
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --color-avocado-600: oklch(0.53 0.12 118.34);

  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);

  /* ... */
}

Learn more about customizing your theme in the theme variables documentation.

@source

Use the @source directive to explicitly specify source files that aren't picked up by Tailwind's automatic content detection:

/* [!code filename:CSS] */
@source "../node_modules/@my-company/ui-lib";

Learn more about automatic content detection in the detecting classes in source files documentation.

@utility

Use the @utility directive to add custom utilities to your project that work with variants like hover, focus and lg:

/* [!code filename:CSS] */
@utility tab-4 {
  tab-size: 4;
}

Learn more about registering custom utilities in the adding custom utilities documentation.

@variant

Use the @variant directive to apply a Tailwind variant to styles in your CSS:

/* [!code filename:CSS] */
.my-element {
  background: white;

  /* [!code highlight:4] */
  @variant dark {
    background: black;
  }
}

If you need to apply multiple variants at the same time, use nesting:

/* [!code filename:CSS] */
.my-element {
  background: white;

  /* [!code highlight:6] */
  @variant dark {
    @variant hover {
      background: black;
    }
  }
}

Learn more about variants in the hover, focus, and other states documentation.

@custom-variant

Use the @custom-variant directive to add a custom variant in your project:

/* [!code filename:CSS] */
@custom-variant pointer-coarse (@media (pointer: coarse));
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

This lets you write utilities like pointer-coarse:size-48 and theme-midnight:bg-slate-900.

Learn more about adding custom variants in the registering a custom variant documentation.

@apply

Use the @apply directive to inline any existing utility classes into your own custom CSS:

/* [!code filename:CSS] */
.select2-dropdown {
  /* [!code highlight:2] */
  @apply rounded-b-lg shadow-md;
}

.select2-search {
  /* [!code highlight:2] */
  @apply rounded border border-gray-300;
}

.select2-results__group {
  /* [!code highlight:2] */
  @apply text-lg font-bold text-gray-900;
}

This is useful when you need to write custom CSS (like to override the styles in a third-party library) but still want to work with your design tokens and use the same syntax you’re used to using in your HTML.

@reference

If you want to use @apply or @variant in the <style> block of a Vue or Svelte component, or within CSS modules, you will need to import your theme variables, custom utilities, and custom variants to make those values available in that context.

To do this without duplicating any CSS in your output, use the @reference directive to import your main stylesheet for reference without actually including the styles:

<!-- [!code filename:Vue] -->
<template>
  <h1>Hello world!</h1>
</template>

<style>
  /* [!code highlight:2] */
  @reference "../../app.css";

  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

If you’re just using the default theme with no customizations, you can import tailwindcss directly:

<!-- [!code filename:Vue] -->
<template>
  <h1>Hello world!</h1>
</template>

<style>
  /* [!code highlight:2] */
  @reference "tailwindcss";

  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

Functions

Tailwind provides the following build-time functions to make working with colors and the spacing scale easier.

--alpha()

Use the --alpha() function to adjust the opacity of a color:

/* [!code filename:Input CSS] */
.my-element {
  /* [!code highlight:2] */
  color: --alpha(var(--color-lime-300) / 50%);
}
/* [!code filename:Compiled CSS] */
.my-element {
  color: color-mix(in oklab, var(--color-lime-300) 50%, transparent);
}

--spacing()

Use the --spacing() function to generate a spacing value based on your theme:

/* [!code filename:Input CSS] */
.my-element {
  /* [!code highlight:2] */
  margin: --spacing(4);
}
/* [!code filename:Compiled CSS] */
.my-element {
  margin: calc(var(--spacing) * 4);
}

This can also be useful in arbitrary values, especially in combination with calc():

<!-- [!code filename:HTML] -->
<!-- [!code classes:py-[calc(--spacing(4)-1px)]] -->
<div class="py-[calc(--spacing(4)-1px)]">
  <!-- ... -->
</div>

Compatibility

The following directives and functions exist solely for compatibility with Tailwind CSS v3.x.

@config

Use the @config directive to load a legacy JavaScript-based configuration file:

/* [!code filename:CSS] */
@config "../../tailwind.config.js";

The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0.

@plugin

Use the @plugin directive to load a legacy JavaScript-based plugin:

/* [!code filename:CSS] */
@plugin "@tailwindcss/typography";

The @plugin directive accepts either a package name or a local path. Tailwind CSS provides a number of official plugins that you can use with this directive:

  • @tailwindcss/typography - Provides a set of prose classes you can use to add beautiful typographic defaults to any vanilla HTML you don’t control, like HTML rendered from Markdown, or pulled from a CMS.
  • @tailwindcss/forms - Provides a basic reset for form styles that makes form elements easy to override with utilities.
  • @tailwindcss/aspect-ratio - Provides a composable API for giving elements a fixed aspect ratio.

theme()

Use the theme() function to access your Tailwind theme values using dot notation:

/* [!code filename:CSS] */
.my-element {
  /* [!code highlight:2] */
  margin: theme(spacing.12);
}

This function is deprecated, and we recommend using CSS theme variables instead.