Web features: [@function](https://webstatus.dev/features/function) > [!NOTE] > **Note:** These guides are authored for AI coding agents (apologies for the robotic tone!). To have your coding agent adopt these patterns automatically, check out [Modern Web Guidance](https://github.com/GoogleChrome/modern-web-guidance). Maintaining large stylesheets often leads to repetitive logic, especially when dealing with design system tokens like gradients or responsive layout patterns. The CSS `@function` at-rule allows you to encapsulate this logic into reusable, parameterized functions, making your CSS more maintainable, consistent and DRY (Don't Repeat Yourself). ## The `@function` Syntax A custom function is defined using the `@function` rule followed by a dashed name and a list of parameters. The function returns a value using the `result` property. ```css @function --my-function(--input1 , --input2: default-value) returns { /* Logic goes here */ result: var(--input1); } ``` ### Key Concepts - **Parameters:** Must start with a double dash (`--`). - **Defaults:** You can provide default values using a colon (`:`). - **Result:** The `result` property determines the value the function returns. The last `result` declared in the function body wins. - **Scoping:** Parameters and variables defined inside the function are locally scoped. - **Types:** You can require parameters and the returned value to match a CSS type with bracket notation (e.g., ``) and allow multiple types with the `type` function (e.g., `type( | )`). ## Practical Examples ### 1. Design System Tokens (Gradients) Ensure consistent color gradients across your app by encapsulating gradient logic. The `--angle` provides a default value to provide consistency that can be overridden. ```css @function --fancy-gradient(--start-color , --end-color , --angle: 98deg) returns { result: linear-gradient(in oklab var(--angle), var(--start-color), var(--end-color) ); } .card { background: --fancy-gradient(#ed73d7, #5d87e9); } ``` ### 2. Conditional Layout Logic You can use `@media` or other queries directly inside a function to return different values based on the environment. When using conditional logic in a function, note that the `@function` does not "return" at the first value of `result`, but rather follows the CSS cascade, and resolves to the last value that matches based on the screen size, container size, or other query. ```css @function --grid-template(--count ){ /* MANDATORY: Put default value first. */ result: 1fr; /* Default: stack */ @media (min-width: 800px) { result: repeat(var(--count), 1fr); /* Grid on larger screens */ } } main { display: grid; grid-template-columns: --grid-template(2); } ``` ## Best Practices - **Use Dashed Names:** Always prefix your function names and parameters with `--`. - **Provide Defaults:** Make your functions more robust by providing sensible default values. - **Keep it Simple:** Use functions for logic that is actually repeated or complex. Don't over-engineer simple property-value pairs. - **Use Types:** Ensure your parameters and return values are the expected types. - **Consider Precompiled Alternatives:** For functions that do not depend on user input, media queries or other client-side variation, consider using a CSS precompiler to avoid doing unnecessary work on the client. ### Fallback strategies In browsers that do not support CSS Functions, values set using CSS functions will be invalid. To support other browsers, provide a fallback value for the property first. This will be overridden in browsers with CSS function support. ```css .card { /* Provide fallback, in this case a solid color. */ background: #5d87e9; background: --fancy-gradient(#ed73d7, #5d87e9); } main { /* Provide fallback, in this case a simple stacked default. */ grid-template-columns: 1fr; grid-template-columns: --grid-template(2); } ``` If it is a requirement to reduce style repetition while supporting other browsers, consider a CSS precompiler with functions, like Sass. Source: [reduce-style-repetition guide on GitHub](https://github.com/GoogleChrome/modern-web-guidance-src/blob/main/guides/css/reduce-style-repetition/guide.md)