Define your own design tokens in a block theme by adding them to settings.custom in theme.json. WordPress converts each key to a kebab-case CSS custom property, prints the resulting variables for both the Site Editor and the front end, and lets you reference them in theme.json with var:custom|…. Standard color, font, spacing, and shadow presets follow the same workflow but use the --wp--preset--… naming scheme.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
The practical rule is simple: register a value in settings.custom (or the appropriate preset collection), consume it in the styles tree when a standard style control exists, and use the generated var(--wp--…) name in ordinary CSS. The sections below show the exact syntax, placement, naming behavior, and fixes for common failures.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What theme.json does with CSS custom properties
theme.json is the configuration file for block themes and global styles. Its settings section declares design options; its styles section applies those options to the site, semantic elements, and blocks. WordPress turns registered settings into CSS and loads that CSS in the editor and on the front end, so authors see the same token values that visitors receive.
For free-form tokens, WordPress documentation describes settings.custom as a way to create CSS custom properties needed elsewhere in a theme. Adding a key and value causes WordPress to generate the property, assign the value, and load it for you. A key named lineHeight becomes --wp--custom--line-height; nested keys append segments, so lineHeight.md becomes --wp--custom--line-height--md.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
Built-in presets are different. Colors, font sizes, font families, spacing, and shadows are registered in their documented settings collections and receive standardized names such as --wp--preset--color--primary. Preset registration also enables the corresponding editor controls and standardized preset classes.
Prepare a valid theme.json file
Place theme.json in the root of a block theme. The examples use API version 2, which is the version represented by the documented examples. Keep the schema declaration so your editor can validate property names and values:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2
}The schema URL is a living reference. If you target a newer theme.json API version, check the current reference and adjust the version and supported properties rather than assuming that every version-2 example applies unchanged.
Define custom variables in settings.custom
Use an object under settings.custom. You may store a single token or group related values in nested objects. The following declaration creates two line-height tokens and one color preset:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"lineHeight": {
"sm": "1.25",
"md": "1.5"
}
},
"color": {
"palette": [
{
"name": "Primary",
"slug": "primary",
"color": "#1e40af"
}
]
}
}
}WordPress hyphenates camelCase names. In this example, lineHeight becomes line-height, and the nested keys produce the following custom properties:
body {
--wp--custom--line-height--sm: 1.25;
--wp--custom--line-height--md: 1.5;
--wp--preset--color--primary: #1e40af;
}Use practical nesting. Every additional object level adds another ---delimited segment, making the variable longer and harder to reference. Choose stable, descriptive keys because changing a key changes the generated property name and every consumer that uses it.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
Reference tokens inside theme.json
Values in the styles tree use WordPress token syntax, not the CSS var() function. A custom token is written as var:custom|path|to|value; a preset is written as var:preset|feature|slug.
{
"styles": {
"typography": {
"lineHeight": "var:custom|line-height|md"
},
"color": {
"text": "var:preset|color|primary"
},
"blocks": {
"core/paragraph": {
"typography": {
"lineHeight": "var:custom|line-height|sm"
}
}
}
}
}The path after var:custom| follows the generated name after --wp--custom--. For the nested object above, var:custom|line-height|md resolves to --wp--custom--line-height--md. The preset path follows the feature and slug, so var:preset|color|primary resolves to --wp--preset--color--primary.
Choose the right styles location
- Top-level
styles: applies global values and is emitted for the body-level site style. styles.elements: targets semantic elements such as headings, links, or buttons when those element controls are supported.styles.blocks: targets a specific block, such ascore/paragraph, and is emitted for that block’s selector.
Use the most specific supported location that matches the intent. A global line-height belongs at the top level; a paragraph-only adjustment belongs under styles.blocks.core/paragraph. This keeps the token definition centralized while allowing deliberate per-context use.
Custom settings versus standard presets
Both systems generate CSS variables, but they solve different problems. Use this comparison before deciding where a value belongs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Question | settings.custom |
Standard preset collection |
|---|---|---|
| Primary purpose | Free-form theme tokens that your design system or custom CSS needs. | Standardized colors, font sizes, font families, spacing, shadows, and other documented features. |
| Editor control | Not automatically exposed as a matching user-facing control. | Designed to power Site Editor controls and user-selectable options. |
| Generated name | --wp--custom--{path}, with kebab-case segments. |
--wp--preset--{feature}--{slug}. |
| theme.json reference | var:custom|…. |
var:preset|…. |
| Plain CSS use | Use the generated var(--wp--custom--…) property. |
Use the generated var(--wp--preset--…) property. |
| Best fit | Internal scales, ratios, component-specific values, or a token with no standard control. | A value users should adjust through Appearance → Editor → Styles. |
If a value is a color, font size, spacing preset, or another feature that WordPress already models, register it in that feature’s preset collection. You get the standard naming and editor integration instead of recreating a parallel control with settings.custom.
Use generated variables in style.css or another stylesheet
Regular CSS cannot use the var:custom|… notation. It must use the generated CSS custom-property name with the CSS var() function:
Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
.example-class {
line-height: var(--wp--custom--line-height--md);
color: var(--wp--preset--color--primary);
}The variables are available because WordPress emits them for both the editor and front end. A class in an external stylesheet, a stylesheet enqueued by the theme, or the styles.css field can therefore consume the same token values used by global styles.
Keep declarations in theme.json whenever the property maps cleanly to a supported global-style control. Use styles.css or an external stylesheet for selectors and CSS features that the standard style schema cannot express. Once you move a rule into ordinary CSS, normal cascade and specificity rules apply.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Control cascade and selector scope
Registering a variable does not decide where a declaration wins. The value is inherited like any CSS custom property, while the rule that consumes it still competes according to selector specificity, source order, and whether a more specific block or user style exists.
- Put a site-wide token consumer in top-level
stylesor a low-specificity global selector. - Put a block-specific consumer under that block in
styles.blockswhen possible. - Avoid redefining the same generated variable in unrelated selectors unless you intentionally want scoped overrides.
- When a custom stylesheet appears to lose, inspect the computed style and compare selector specificity and load order rather than changing the token declaration.
Users can change values through the Site Editor when they are represented by supported style settings. Your custom token remains the source value, but a later user or block style can still override the property that consumes it.
Build a maintainable token system
Start with semantic names
Name tokens by purpose or scale rather than by the first component that uses them. A pair such as lineHeight.sm and lineHeight.md can serve paragraphs, cards, and headings. If a value is truly component-only, make that scope obvious in the nested path.
Keep one source of truth
Define a value once in settings.custom or a preset collection, then reference it from global styles, block styles, and ordinary CSS. Copying the same literal into several rules makes later changes error-prone and defeats the point of a token.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
Separate registration from application
The settings tree answers “which values exist?” The styles tree answers “where are they used?” Keeping those responsibilities separate makes it easier to add a new consumer without inventing another variable and easier to change a value without hunting through selectors.
Common failures and precise fixes
The variable is undefined
Check spelling, capitalization, and every segment of the generated name. lineHeight becomes line-height; it does not remain camelCase. For nested values, include every segment, for example --wp--custom--line-height--md. Also confirm that the token is under settings.custom in the active theme’s root theme.json, not in an unrelated JSON file.
The theme.json reference is ignored
Inside theme.json, use var:custom|… or var:preset|…. Writing var(--wp--custom--…) in that JSON value uses CSS syntax where WordPress expects its token syntax. Reserve var() for CSS files and the styles.css field.
A preset path does not resolve
Preset references must match the registered feature and slug exactly. A color declared with slug primary is referenced as var:preset|color|primary; the human-readable name is not the path.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesThe value does not appear in the editor
Custom settings are free-form variables, not automatic controls. If users need a selectable color, font size, spacing value, or another supported option, register it in the corresponding preset collection and apply it through the supported styles property.
The editor and front end differ
Inspect both generated styles and look for a later block, user, or custom stylesheet rule. The token can be present in both contexts while different selectors consume or override it. Validate the JSON first, then compare the computed property and winning rule in each context.
Validation errors appear after adding a key
Check commas, quotation marks, object nesting, and the schema-selected API version. Keep custom values in valid JSON types and confirm that the property you are setting is supported by the version declared in theme.json.
A complete working pattern
This compact pattern registers a custom line-height scale, a color preset, applies both globally, and tightens paragraphs through a block style:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"lineHeight": {
"sm": "1.25",
"md": "1.5"
}
},
"color": {
"palette": [
{ "name": "Primary", "slug": "primary", "color": "#1e40af" }
]
}
},
"styles": {
"typography": {
"lineHeight": "var:custom|line-height|md"
},
"color": {
"text": "var:preset|color|primary"
},
"blocks": {
"core/paragraph": {
"typography": {
"lineHeight": "var:custom|line-height|sm"
}
}
}
}
}Then consume the same generated values in a stylesheet:
.example-class {
line-height: var(--wp--custom--line-height--md);
color: var(--wp--preset--color--primary);
}This arrangement gives the editor and front end one token source, uses standard global-style controls where they exist, and leaves selector-specific behavior to block styles or ordinary CSS.
The Bottom Line
Use settings.custom for free-form tokens, preset collections for standardized editor-facing options, WordPress’s var:custom|… and var:preset|… syntax inside theme.json, and generated var(--wp--…) names in regular CSS.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
