{
  "name": "usage",
  "title": "Usage",
  "description": "Learn more about using custom elements.",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/usage/",
  "sections": [
    {
      "heading": "Usage",
      "markdown": "eurodata-ui components are just regular HTML elements, or [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to be precise. You can use them like any other element. Each component has detailed documentation that describes its full API, including properties, events, methods, and more.\n\nIf you're new to custom elements, often referred to as \"web components,\" this section will familiarize you with how to use them."
    },
    {
      "heading": "Attributes & Properties",
      "markdown": "Many components have properties that can be set using attributes. For example, buttons accept a `density` attribute that maps to the `density` property which controls the button's spacing.\n\n```html\n<ed-button density=\"compact\">Click me</ed-button>\n```\n\nSome properties are boolean, so they only have true/false values. To activate a boolean property, add the corresponding attribute without a value.\n\n```html\n<ed-button disabled>Click me</ed-button>\n```\n\nNote that setting `disabled=\"false\"` as a string attribute still disables the element — boolean attributes are considered `true` whenever they are present, regardless of their value.\n\nAvoid using self-closing tags! Custom elements cannot be void elements and must always include a closing tag."
    },
    {
      "heading": "Slots",
      "markdown": "Many components use slots to accept content inside of them. The most common slot is the _default_ slot, which includes any content inside the component that doesn't have a `slot` attribute.\n\nFor example, a button's default slot is used to populate its label.\n\n```html\n<ed-button>Click me</ed-button>\n```\n\nSome components also have _named_ slots. A named slot can be populated by adding a child element with the appropriate `slot` attribute. Notice how the icon below has the `slot=\"start\"` attribute? This tells the component to place the icon into its `start` slot.\n\n```html\n<ed-button>\n  <ed-icon slot=\"start\" name=\"gear\" variant=\"solid\"></ed-icon>\n  Settings\n</ed-button>\n```\n\nThe location of a named slot doesn't matter. You can put it anywhere inside the component and the browser will move it to the right place automatically!\n\nRefer to a component's documentation for a complete list of available slots."
    },
    {
      "heading": "Events",
      "markdown": "You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components have their own custom events. For example, you might listen to `ed-after-show` to determine when a dialog has been shown.\n\nCustom eurodata-ui events are prefixed with `ed-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its events.\n\nIf you're using React or another framework with synthetic events, see the [frameworks guides](https://test-apps.eurodata.de/a/eurodata-ui/docs/frameworks/react) for caveats around binding to custom event names.\n\n### Event bubbling\n\nMost custom events bubble, so you can listen for them on an ancestor (event delegation) — for example, listening for `ed-navigate` on a navigation container catches navigations from any nested item.\n\nEvents that describe a single component's own visibility or state — `ed-show`, `ed-hide`, `ed-after-show`, `ed-after-hide`, `ed-expand`, `ed-collapse` and similar — **do not bubble**, matching native HTML (the `close`/`cancel` events of `<dialog>` and the `toggle` event of `<details>`). Listen for them on the element that emits them.\n\nBecause they don't bubble, a nested component's open/close is never attributed to an ancestor: an `ed-dialog` that contains an `ed-select` does **not** receive the select's `ed-hide` when its menu closes — a dialog's `ed-hide` handler only ever runs for the dialog itself."
    },
    {
      "heading": "Methods",
      "markdown": "Some components have methods you can call to trigger various behaviors. For example, you can set focus on an eurodata-ui input using the `focus()` method.\n\n```html\n<ed-input></ed-input>\n\n<script>\n  const input = document.querySelector('ed-input');\n  input.focus();\n</script>\n```\n\nRefer to a component's documentation for a complete list of its methods and their arguments."
    },
    {
      "heading": "Differences from Native Elements",
      "markdown": "You might expect similarly named elements to share the same API as native HTML elements, but this is not always the case. eurodata-ui components **are not** designed to be one-to-one replacements for their HTML counterparts. While they usually share the same API, there may be subtle differences.\n\nFor example, `<button>` and `<ed-button>` both have a `type` attribute, but the native one defaults to `submit` while the eurodata-ui one defaults to `button` since this is a better default for most users.\n\nDon't make assumptions about a component's API!\n\nTo prevent unexpected behaviors, please take the time to review the documentation and make sure you understand what each attribute, property, method, and event is intended to do."
    },
    {
      "heading": "Waiting for Components to Be Ready",
      "markdown": "When you interact with components from JavaScript on first load, the elements may not have upgraded yet. Unlike traditional frameworks, custom elements don't have a centralized initialization phase, so you need to verify that a component has been registered before reading its properties or calling its methods.\n\n### Individual components: customElements.whenDefined()\n\nYou can use the [`customElements.whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined) method to ensure a specific component is ready:\n\n```ts\nawait customElements.whenDefined('ed-button');\n\n// <ed-button> is ready to use!\nconst button = document.querySelector('ed-button');\n```\n\n### All eurodata-UI components: allDefined()\n\nWhen working with multiple components, checking each one individually can become tedious. For convenience, eurodata-ui provides the `allDefined()` function which automatically detects and waits for all eurodata-UI components in the DOM to be initialized before resolving.\n\n```ts\nimport { allDefined } from '/dist/eurodata.js';\n\n// Waits for all eurodata-ui components in the DOM to be registered\nawait allDefined();\n\n// All eurodata-ui components on the page are ready!\n```\n\nBy default, `allDefined()` will wait for all `ed-` prefixed custom elements within the current `document` to be registered. You can customize this behavior by passing in options:\n\n-   `root` allows you to pass in a different element to search within, or a different document entirely (defaults to `document`).\n-   `match` allows you to specify a custom function to determine which elements to wait for. This function should return `true` for elements you want to wait for and `false` for those you don't.\n-   `additionalElements` allows you to wait for custom elements to be defined that may not be present in the DOM at the time `allDefined()` is called. This can be useful for elements that are loaded dynamically via JS.\n\nHere is an example of using `match` and `root` to await registration of eurodata-ui components inside an element with an id of `sidebar`, plus a `<my-component>` element if present in the DOM, and `<ed-slider>` and `<other-slider>` elements whether present in the DOM or not:\n\n```js\nimport { allDefined } from '/dist/eurodata.js';\n\nawait allDefined({\n  match: tagName => tagName.startsWith('ed-') || tagName === 'my-component',\n  root: document.getElementById('sidebar'),\n  additionalElements: ['ed-slider', 'other-slider'],\n});\n```"
    },
    {
      "heading": "Component Rendering and Updating",
      "markdown": "eurodata-ui components are built with [Lit](https://lit.dev/), a tiny library that makes authoring custom elements easier, more maintainable, and a lot of fun! As an eurodata-UI user, here is some helpful information about rendering and updating you should probably be aware of.\n\nTo optimize performance and reduce re-renders, Lit batches component updates. This means changing multiple attributes or properties at the same time will result in just a single re-render. In most cases, this isn't an issue, but there may be times you'll need to wait for the component to update before continuing.\n\nConsider this example. We're going to change the `checked` property of the checkbox and observe its corresponding `checked` attribute, which happens to reflect.\n\n```js\nconst checkbox = document.querySelector('ed-checkbox');\ncheckbox.checked = true;\n\nconsole.log(checkbox.hasAttribute('checked')); // false\n```\n\nMost developers will expect this to be `true` instead of `false`, but the component hasn't had a chance to re-render yet so the attribute does not exist when `hasAttribute()` is called. Since changes are batched, we need to wait for the update before proceeding. This can be done using the `updateComplete` property, which is available on all Lit-based components.\n\n```js\nconst checkbox = document.querySelector('ed-checkbox');\ncheckbox.checked = true;\n\ncheckbox.updateComplete.then(() => {\n  console.log(checkbox.hasAttribute('checked')); // true\n});\n```\n\nThis time we see `true`, confirming the boolean attribute is present after the update.\n\nTo wait for multiple components to update, await all of their `updateComplete` promises together:\n\n```js\nawait Promise.all(elements.map(el => el.updateComplete));\n```"
    },
    {
      "heading": "Code Completion",
      "markdown": "### VS Code\n\neurodata-ui ships with a file called `vscode.html-custom-data.json` that can be used to describe its custom elements to [Visual Studio Code](https://code.visualstudio.com/). This enables code completion for eurodata-UI components (also known as \"code hinting\" or \"IntelliSense\"). To enable it, you need to tell VS Code where the file is.\n\n1.  [Install eurodata-ui locally](https://test-apps.eurodata.de/a/eurodata-ui/docs/#installing-via-pnpm)\n2.  If it doesn't already exist, create a folder called `.vscode` at the root of your project\n3.  If it doesn't already exist, create a file inside that folder called `settings.json`\n4.  Add the following to the file\n\n```json\n{\n  \"html.customData\": [\"./node_modules/@eurodata/eurodata-ui/dist/vscode.html-custom-data.json\"]\n}\n```\n\nIf `settings.json` already exists, simply add the above line to the root of the object. Note that you may need to restart VS Code for the changes to take effect.\n\n### JetBrains IDEs\n\nIf you are using a [JetBrains IDE](https://www.jetbrains.com/) and you are installing eurodata-ui from NPM, the editor will automatically detect the `web-types.json` file from the package and you should immediately see component information in your editor.\n\nBe sure to add a reference to the `web-types.json` file in your `package.json` in order for your editor to properly detect it.\n\n```json\n{\n  ...\n  \"web-types\": \"./web-types.json\"\n  ...\n}\n```\n\nIf you are using types from multiple projects, you can add an array of references.\n\n```json\n{\n  ...\n  \"web-types\": [\n    ...,\n    \"./web-types.json\"\n  ]\n  ...\n}\n```\n\n### Other Editors\n\nMost popular editors support custom code completion with a bit of configuration."
    },
    {
      "heading": "Where to Go Next",
      "markdown": "-   [Customizing](https://test-apps.eurodata.de/a/eurodata-ui/docs/customizing) — themes, CSS parts, and custom properties.\n-   [Form Controls](https://test-apps.eurodata.de/a/eurodata-ui/docs/form-controls) — using form components, validation, and submission.\n-   [Frameworks](https://test-apps.eurodata.de/a/eurodata-ui/docs/frameworks/react) — guides for React, Vue, Angular, and others.\n-   [Localization](https://test-apps.eurodata.de/a/eurodata-ui/docs/localization) — translating component strings and configuring text direction.\n-   [Preventing FOUCE](https://test-apps.eurodata.de/a/eurodata-ui/docs/utilities/fouce) — avoid the flash of un-upgraded custom elements on first load."
    }
  ]
}