{
"name": "customizing",
"title": "Customizing",
"description": "Learn how to customize eurodata-ui through themes, parts, and custom properties.",
"docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/customizing/",
"sections": [
{
"heading": "Customizing",
"markdown": "You can customize the look and feel of eurodata-ui at a high level with themes. For more advanced customizations, you can make use of CSS parts and custom properties to target individual components."
},
{
"heading": "Themes",
"markdown": "eurodata-ui uses so-called themes to apply a cohesive look and feel across the entire library. Themes are built with a collection of predefined CSS custom properties, which we call [design tokens](https://test-apps.eurodata.de/a/eurodata-ui/docs/theming/token-reference/). Currently there is only one default theme that represents our \"Petrol Theme\".\n\nYou should generally use our **default theme** for most cases. For products that require a different style, we offer two options:\n\n1. **Request a new theme** \n If your style guide significantly differs from the default theme, you can contact us to create a new theme. For example, we can provide a `deep-purple-theme` similar in structure to the default theme.\n \n2. **Create a custom theme** \n You can create your own theme by copying the default theme and adjusting the design tokens that differ from it.\n \n\nIf you need to share your theme across multiple projects, we recommend option 1.\n\nFor even more customizations, you can off-road and override any theme just with CSS — no preprocessor required. All design tokens are prefixed with `--ed-` to avoid collisions with other libraries and your own custom properties. Simply style any design token in your own stylesheet by scoping your styles to `:root` and the class for the relevant color scheme (if needed). Here's an example that uses a darker gray as background color in light mode:\n\n```css\n:root,\n.ed-light,\n.ed-dark .ed-invert {\n --ed-color-surface-default: var(--ed-color-coolgray-220);\n}\n```\n\nFor a complete list of all custom properties used for theming, refer to `src/styles/themes/default.css` in the project's source code.\n\nWhile themes offer a high-level way to customize the library, individual components offer different hooks as a low-level way to customize them individually. eurodata-ui components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose a set of CSS parts, custom properties, and custom states that can be targeted to customize their appearance."
},
{
"heading": "Tokens Reach Component Internals — Element Selectors Don't",
"markdown": "Components carry the design system's [base styles](https://test-apps.eurodata.de/a/eurodata-ui/docs/theming/base-styles) inside their shadow roots, so native elements they render for you — a link in a [data grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid) cell, a dialog heading, inline code — always match the design system. Because shadow roots are out of reach for page-level element selectors, design tokens are the supported way to customize that content: custom properties pierce shadow boundaries and restyle the light DOM and every shadow copy in sync.\n\n```css\n/* ✅ restyles links on the page AND inside every component */\n:root {\n --ed-color-text-link: red;\n}\n\n/* ❌ only restyles light-DOM links — component-rendered links keep the default */\na {\n color: red;\n}\n```\n\nThe link tokens (`--ed-color-text-link`, `--ed-link-decoration-default`, `--ed-link-decoration-hover`) and the focus tokens (`--ed-focus-ring`, `--ed-focus-ring-offset`) cover the most common cases. For a one-off override of a single component's internals, use its documented CSS parts instead (see below)."
},
{
"heading": "CSS Parts",
"markdown": "CSS parts offer the most flexibility to customize individual components. The \"parts\" exposed by each component can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.\n\nParts allow you to style _any_ standard CSS property, not just those exposed through custom properties. Here's an example that modifies buttons with the `gradient-button` class.\n\n```html\n Gradient Button \n\n\n```\n\nCSS parts have a few important advantages:\n\n- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.\n \n- The internal structure of a component will likely change as it evolves. By exposing CSS parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.\n \n- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.\n \n\nMost (but not all) components expose parts. You can find them in each component's API documentation under the \"CSS Parts\" section."
},
{
"heading": "Custom Properties",
"markdown": "Every custom property in eurodata-ui starts with `--ed-`, and a component's own properties name the component they belong to: `--ed-avatar-size`, `--ed-dialog-width`, `--ed-data-grid-row-height`. The prefix is not decoration — a custom property set on a component is inherited by everything you slot into it, so a generic name like `--spacing` would quietly replace a value your own CSS framework relies on.\n\n**Where you set the property decides how far it reaches.** This is the same idea as a theme default versus a one-off override, expressed in plain CSS:\n\n```css\n/* Every dialog on the page is 40rem wide */\n:root {\n --ed-dialog-width: 40rem;\n}\n```\n\n```html\n\n…\n```\n\nThere is no separate \"theme property\" and \"instance property\" to choose between: one name, set globally or per element. Which properties a component understands is listed on its own documentation page.\n\nA component also uses custom properties internally — to hand a measured value from its own script to its own stylesheet, for example. Those are named with a leading underscore (`--_indent-guide-x`) and are **not** part of the component's API: they are absent from its documentation, and they may change or disappear in any release. Setting one is unsupported.\n\nYou can set a component's properties from your stylesheet.\n\n```css\ned-avatar {\n --ed-avatar-size: 6rem;\n}\n```\n\nThis will also work if you need to target a subset of components with a specific class.\n\n```css\ned-avatar.your-class {\n --ed-avatar-size: 6rem;\n}\n```\n\nAlternatively, you can set them inline directly on the element.\n\n```html\n\n```\n\nThe custom properties exposed by each component can be found in the component's API documentation."
},
{
"heading": "Custom States",
"markdown": "Components can expose custom states that allow you to style them based on their current condition using the `:state()` selector. Custom states provide a way to target specific component states that aren't covered by standard pseudo-classes like `:hover` or `:focus`. Here's an example that styles a checkbox that's checked.\n\n```css\ned-checkbox:state(checked) {\n outline: dotted 2px tomato;\n}\n```\n\nCustom states can be combined with CSS parts and custom properties to create sophisticated customizations. The custom states exposed by each component can be found in the component's API documentation under the \"Custom States\" section."
}
]
}