Concepts
Panda Integration Hooks
Panda hooks can be used to add new functionality or modify existing behavior during certian parts of the compiler lifecycle.
Hooks are mostly callbacks that can be added to the panda config via the hooks
property, or installed via plugins.
Here are some examples of what you can do with hooks:
- modify the resolved config (
config:resolved
), like strip out tokens or keyframes. - tweak the design token or classname engine (
tokens:created
,utility:created
), like prefixing token names, or customizing the hashing function - transform a source file to a
tsx
friendly syntax before it's parsed (parser:before
) so that Panda can automatically extract its styles usage - create your own styles parser (
parser:before
,parser:after
) using the file's content so that Panda could be used with any templating language - alter the generated JS and DTS code (
codegen:prepare
) - modify the generated CSS (
cssgen:done
), allowing all kinds of customizations like removing the unused CSS variables, etc. - restrict
strictTokens
to a specific set of token categories, ex: only affectcolors
andspacing
tokens and therefore allow any value forfontSizes
andlineHeights
Examples
Prefixing token names
This is especially useful when migrating from other css-in-js libraries, like Stitches.
import { defineConfig } from '@pandacss/dev'
export default defineConfig({
// ...
hooks: {
'tokens:created': ({ configure }) => {
configure({
formatTokenName: path => '$' + path.join('-')
})
}
}
})
Customizing the hash function
When using the hash: true
config property, you can customize the function used to hash the classnames.
export default defineConfig({
// ...
hash: true,
hooks: {
'utility:created': ({ configure }) => {
configure({
toHash: (paths, toHash) => {
const stringConds = paths.join(':')
const splitConds = stringConds.split('_')
const hashConds = splitConds.map(toHash)
return hashConds.join('_')
}
})
}
}
})
Modifying the config
Here's an example of how to leveraging the provided utils
functions in the config:resolved
hook to remove the stack
pattern from the resolved config.
import { defineConfig } from '@pandacss/dev'
export default defineConfig({
// ...
hooks: {
'config:resolved': ({ config, utils }) => {
return utils.omit(config, ['patterns.stack'])
}
}
})
Configuring JSX extraction
Use the matchTag
/ matchTagProp
functions to customize the way Panda extracts your JSX.
This can be especially useful when working with libraries that have properties that look like CSS properties but are not and should be ignored.
Let's see a Radix UI example where the Select.Content
component has a position
property that should be ignored:
// Here, the `position` property will be extracted because `position` is a valid CSS property, but we don't want that
<Select.Content position="popper" sideOffset={5}>
export default defineConfig({
// ...
hooks: {
'parser:before': ({ configure }) => {
configure({
// ignore the Select.Content entirely
matchTag: tag => tag !== 'Select.Content',
// ...or specifically ignore the `position` property
matchTagProp: (tag, prop) =>
tag === 'Select.Content' && prop !== 'position'
})
}
}
})
Remove unused variables from final css
Here's an example of how to transform the generated css in the cssgen:done
hook.
import { defineConfig } from '@pandacss/dev'
import { removeUnusedCssVars } from './remove-unused-css-vars'
import { removeUnusedKeyframes } from './remove-unused-keyframes'
export default defineConfig({
// ...
hooks: {
'cssgen:done': ({ artifact, content }) => {
if (artifact === 'styles.css') {
return removeUnusedCssVars(removeUnusedKeyframes(content))
}
}
}
})
Get the snippets for the removal logic from our Github Sandbox in the remove-unused-css-vars (opens in a new tab) and remove-unused-keyframes (opens in a new tab) files.
Note: Using this means you can't use the JS function token.var
(or token(xxx) where xxx
is the path to a semanticToken) from styled-system/tokens
as the CSS variables will be removed based on the usage found in the generated CSS
Sharing hooks
Hooks can be shared as a snippet or as a plugin
. Plugins are currently simple objects that contain a name
associated with a hooks
object with the same structure as the hooks
object in the config.
Plugins differ from presets
as they can't be extended, but they will be called in sequence in the order they are defined in the plugins
array, with the user's config called last.
import { defineConfig } from '@pandacss/dev'
export default defineConfig({
// ...
plugins: [
{
name: 'token-format',
hooks: {
'tokens:created': ({ configure }) => {
configure({
formatTokenName: path => '$' + path.join('-')
})
}
}
}
]
})
Reference
export interface PandaHooks {
/**
* Called when the config is resolved, after all the presets are loaded and merged.
* This is the first hook called, you can use it to tweak the config before the context is created.
*/
'config:resolved': (
args: ConfigResolvedHookArgs
) => MaybeAsyncReturn<void | ConfigResolvedHookArgs['config']>
/**
* Called when the token engine has been created
*/
'tokens:created': (args: TokenCreatedHookArgs) => MaybeAsyncReturn
/**
* Called when the classname engine has been created
*/
'utility:created': (args: UtilityCreatedHookArgs) => MaybeAsyncReturn
/**
* Called when the Panda context has been created and the API is ready to be used.
*/
'context:created': (args: ContextCreatedHookArgs) => void
/**
* Called when the config file or one of its dependencies (imports) has changed.
*/
'config:change': (args: ConfigChangeHookArgs) => MaybeAsyncReturn
/**
* Called after reading the file content but before parsing it.
* You can use this hook to transform the file content to a tsx-friendly syntax so that Panda's parser can parse it.
* You can also use this hook to parse the file's content on your side using a custom parser, in this case you don't have to return anything.
*/
'parser:before': (args: ParserResultBeforeHookArgs) => string | void
/**
* Called after the file styles are extracted and processed into the resulting ParserResult object.
* You can also use this hook to add your own extraction results from your custom parser to the ParserResult object.
*/
'parser:after': (args: ParserResultAfterHookArgs) => void
/**
* Called right before writing the codegen files to disk.
* You can use this hook to tweak the codegen files before they are written to disk.
*/
'codegen:prepare': (
args: CodegenPrepareHookArgs
) => MaybeAsyncReturn<Artifact[]>
/**
* Called after the codegen is completed
*/
'codegen:done': (args: CodegenDoneHookArgs) => MaybeAsyncReturn
/**
* Called right before adding the design-system CSS (global, static, preflight, tokens, keyframes) to the final CSS
* Called right before writing/injecting the final CSS (styles.css) that contains the design-system CSS and the parser CSS
* You can use it to tweak the CSS content before it's written to disk or injected through the postcss plugin.
*/
'cssgen:done': (args: CssgenDoneHookArgs) => string | void
}