# OVHcloud Design System - Generic Documentation Documentation for design tokens, styling, theming, guides, tools, and general information about OVHcloud Design System. ## Welcome --- title: "Welcome" slug: ovhcloud-design-system-welcome category: generic type: overview version: 20.0.0 tokens: 252 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-welcome.txt --- # Welcome > OVHcloud Design System is a collection of assets, guidelines and UI components for building consistent user experiences across OVHcloud products OVHcloud Design System provides React components, design tokens, helpers and usage guidelines for building OVHcloud products. - Online documentation: https://ovh.github.io/design-system/v20.0.0/ - Components documented in this set: Accordion, Avatar, Badge, Breadcrumb, Button, Button Group, Card, Cart, Checkbox, Clipboard, Code, Combobox, Command, Data Table, Datepicker, Divider, Drawer, Editable, File Thumbnail, File Upload, Form Field, Icon, Input, Kbd, Link, Logo, Markdown, Medium, Menu, Message, Message Bubble, Meter, Modal, Pagination, Password, Phone Number, Popover, Progress Bar, Prompt Input, Quantity, Query Filter, Radio Group, Range, Select, Skeleton, Spinner, Table, Tabs, Tag, Text, Textarea, Tile, Timepicker, Toaster, Toggle, Tooltip, Tree View - Get started: https://ovh.github.io/design-system/v20.0.0/guides/get-started ## Get Started --- title: "Get Started" slug: ovhcloud-design-system-get-started category: generic type: overview version: 20.0.0 tokens: 1174 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-get-started.txt --- # Get Started OVHcloud Design System is a set of reusable React UI components to create a consistent user experience across OVHcloud pages and products, acting as a single source of truth. All OVHcloud Design System packages are available on [NPM](https://www.npmjs.com). ## Installation Include **ODS** in your projects like any other npm, pnpm or yarn module. `react` and `react-dom` (`v18.2+` or `v19+`) are peer dependencies: they must already be installed in your project. ```bash npm i --save-exact @ovhcloud/ods-react @ovhcloud/ods-themes ``` ```bash pnpm add --save-exact @ovhcloud/ods-react @ovhcloud/ods-themes ``` ```bash yarn add --exact @ovhcloud/ods-react @ovhcloud/ods-themes ``` ## Usage All components can be imported from the root path: ```tsx import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@ovhcloud/ods-react'; const App = () => { return ( Hello World! Lorem ipsum dolor sit amet. ); }; ``` Each component is also available as compound component from its subpath: ```tsx import { Accordion } from '@ovhcloud/ods-react/accordion'; const App = () => { return ( Hello World! Lorem ipsum dolor sit amet. ); }; ``` ## Import components constants All enums, interfaces, events are available directly from the `ods-react` lib ```typescript import { BUTTON_SIZE, type CheckboxProp } from '@ovhcloud/ods-react'; ``` ## Import theme & fonts You need to import a theme to display all the components correctly. It defines all the colors, typographies, etc. A theme names its fonts but does not load them: load them too. The default theme uses Source Sans 3 and Source Code Pro, which ODS ships with its icon font. via ES import: ```typescript import '@ovhcloud/ods-themes/default/css'; import '@ovhcloud/ods-themes/default/fonts'; ``` via Sass import: ```scss @use 'pkg:@ovhcloud/ods-themes/default/css'; @use '@ovhcloud/ods-themes/default/fonts'; ``` `pkg:` URLs require the [Node.js package importer](https://sass-lang.com/documentation/js-api/classes/nodepackageimporter/) (Sass `v1.71.1+`), enabled with `importers: [new NodePackageImporter()]` in your Sass options. The fonts stylesheet declares its font files with relative `url()`s, which Sass does not rewrite: keep a bare path for it, so your bundler (Vite for instance) resolves the file, rebases these URLs and emits the fonts. Through a `pkg:` URL, the URLs stay relative to your stylesheet and the fonts are not found. If your bundler does not rebase them, load the fonts from JavaScript instead, as in the ES import above. ODS ships three more themes, Aluminium dark, Blue Jeans and Blue Jeans dark, each to load instead of the default one. [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) lists their imports and fonts, and explains how to switch between them, load the fonts when your setup cannot serve font files, or create your own theme. ## Server-side rendering ODS components rely on React state, effects and browser APIs: they cannot be used as React Server Components. With the Next.js App Router, import the theme in your root layout and use the components from client components, marked with the `'use client'` directive: ```tsx // app/layout.tsx import '@ovhcloud/ods-themes/default/css'; import '@ovhcloud/ods-themes/default/fonts'; import { type ReactNode } from 'react'; export default function RootLayout({ children }: { children: ReactNode }) { return ( { children } ); } ``` ```tsx // app/page.tsx 'use client'; import { Link } from '@ovhcloud/ods-react'; export default function Home() { return My ODS Link; } ``` The `Toaster` renders into `document.body` by default, which does not exist on the server, so the page fails to prerender with `document is not defined`. Pass `createPortal={ false }` to render it where it is placed, or render it only once the page is mounted in the browser. ## TypeScript To ensure the types are correctly resolved, you'll have to use the `bundler` module resolution, released with [TypeScript 5.0](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#--moduleresolution-bundler). ```typescript "moduleResolution": "bundler" ``` ## Accessibility --- title: "Accessibility" slug: ovhcloud-design-system-build-accessibility category: generic type: overview version: 20.0.0 tokens: 4541 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-build-accessibility.txt --- # Accessibility ## Introduction This guide focuses on accessibility best practices specifically for developers integrating the **OVHcloud Design System**. While our components are built with accessibility in mind, using semantic HTML elements and including the necessary ARIA attributes by default. Nevertheless, ensuring full accessibility in your specific use case might require you to implement additional ARIA attributes, roles, and behaviors at the integration level. However, depending on the context, you might need to enhance a component's accessibility. This guide will help you understand: * When and how to use ARIA properly * Common mistakes and best practices * How screen readers interpret different ARIA attributes For broader accessibility information beyond the **OVHcloud Design System**, consult our [Accessibility Statement](https://www.ovhcloud.com/fr/accessibility/) available on our official website. ### Before using ARIA #### Consult the Accessibility section for each component Each component in **OVHcloud Design System** comes with a dedicated **"Accessibility"** section that provides best practices and usage guidance. #### Be careful when adding extra ARIA attributes as ODS components may already handle it To be as close as possible to the accessible experiences provided by modern browsers, **OVHcloud Design System** aims to rely on semantic and native HTML elements whenever they are inherently well-suited for screen reader experiences. In addition to the predefined accessibility features of our components, you can find more guidance regarding accessible integration in the **"Accessibility"** section. ## Essential ARIA attributes ### aria-label: Providing an accessible name Use [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) when an element needs a descriptive name but has no visible text. ```tsx ``` Screen readers will announce a button. ```tsx ``` Screen readers will announce a button and the aria-label. #### Related Sources * [MDN Documentation - aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) * [RGAA - 6.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#6.1) * [RGAA - 7.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.2) * [RGAA - 11.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.1) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) * [RGAA - 11.9](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.9) ### aria-labelledby: Referencing another element as a label Use [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) to associate an element with an existing label (instead of duplicating text). ```tsx <> Filter your search results ``` Screen readers will announce a button. ```tsx <> Filter your search results ``` When the **Button** is focused, the screen reader should announce the linked label. > Use [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) when there is no visible label, and [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) when there is one. #### Related Sources * [MDN Documentation - aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) * [RGAA - 6.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#6.1) * [RGAA - 7.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.2) * [RGAA - 11.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.1) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) * [RGAA - 11.9](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.9) ### aria-describedby: Providing additional context [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) associates an interactive element with extra information, ensuring screen reader users receive helpful guidance without disrupting the UI. #### Difference between aria-labelledby and aria-describedby Attribute Purpose When to use it? Reading order aria-labelledby Defines the main context of the element When an element has no visible text or needs an external label Read first by the screen reader aria-describedby Provides additional description When secondary information is needed to clarify context Read after the main label #### When to use aria-labelledby vs aria-describedby? Use case aria-labelledby aria-describedby Use an external / hidden label Add complementary information Associate multiple elements to form a label (field group) Provide contextual help / information (e.g., input rules, field error) ```tsx Delete item ``` Screen readers won't announce the **Modal** content. ```tsx Delete item ``` Screen readers will announce the **Modal** content. #### Related Sources * [MDN Documentation - aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) * [RGAA - 11.10](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.10) ### aria-hidden: Hiding elements from screen readers Use [aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) set to `"true"` on elements that are purely decorative and should not be announced by screen readers. ```tsx ``` Some screen readers will announce the icon and detect the presence of the image. > Depending on the screen reader, some additional information might be read aloud, which is confusing and unhelpful. ```tsx ``` Screen readers will announce nothing, the icon is ignored. #### Related Sources * [MDN Documentation - aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) ### aria-busy: Indicating loading state When a section of the UI is loading, users should be informed that the content is not yet ready. [aria-busy](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) set to `"true"` signals that an element is currently in a loading state. Once loading is complete, `aria-busy` should be set to `"false"`. ```tsx
``` Screen readers will give no indication that the content is loading. The screen reader may start reading the page without knowing that this section is waiting to be updated. ```tsx
``` Screen readers understand that the content is not yet ready, so they delay announcing or interacting with it. #### Related Sources * [MDN Documentation - aria-busy](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### status role: Announcing dynamic status changes Use [status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) to ensure that important updates are announced by screen readers without disrupting focus. ```tsx { const [message, setMessage] = useState(''); const handleClick = () => { setMessage('Copied to clipboard.'); }; return ( <> { message } ); } ``` Screen readers will announce the button and its label. ```tsx { const [message, setMessage] = useState(''); const handleClick = () => { setMessage('Copied to clipboard.'); }; return ( <> { message } ); } ``` Screen readers will announce the button and its label, and the message on click or press. > It also matters since it keeps focus on the button, avoiding disruption for keyboard users. #### Related Sources * [MDN Documentation - status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### alert role: Announcing important messages Use [alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) for critical, time-sensitive messages that require immediate attention. Unlike `status role`, `alert role` is announced by screen readers, even if the user is focused elsewhere. ```tsx { const [error, setError] = useState(''); const handleClick = () => { setError('A critical error occurred while saving.'); }; return ( <> { error } ); } ``` Screen readers won’t immediately announce the error message when it appears, unless the user manually navigates to it. ```tsx { const [error, setError] = useState(''); const handleClick = () => { setError('A critical error occurred while saving!'); }; return ( <> { error } ); } ``` Screen readers will announce the error message, even when the user is focused elsewhere. #### Related Sources * [MDN Documentation - alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### radiogroup and radio roles: Making custom radio controls accessible [radiogroup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) and [radio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) roles ensure that screen readers correctly interpret and announce the selection. ```tsx <>
``` Screen readers will read each star individually with no context of selection group. ```tsx <>
``` Screen readers will announce a radio button, its label and aria-label, which item is focused on out of the total amount of items and that it is a radio group. > Please note that you should navigate within a radio group using `Arrow` keys. In the example above, `tabindex="-1"` is applied to all elements except the currently selected one. This is because only one item in a radio group should be focusable at a time. Users can navigate between options using the `Arrow` keys, rather than the `Tab` key, which moves focus to the next interactive element outside the group. For more details, see [Managing focus within components using a roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio/) #### Sources * [MDN Documentation - radiogroup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) * [MDN Documentation - radio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) ## Final Accessibility check for ARIA roles ### Validate the screen reader behavior Test with a screen reader to ensure that your changes are communicated correctly. Ensure that actions such as button clicks, form submissions, and changes in state are clearly communicated to the user. ### Testing Environment For consistent testing across different platforms and screen readers, here is the testing setup used by **OVHcloud Design System**, based on the recommendations from RGAA (France): Assistive Technology Browser NVDA Firefox JAWS Firefox or Internet Explorer Safari VoiceOver ## Resources to help you test accessibility * [Accessibility France Guidelines (FR)](https://accessibilite.numerique.gouv.fr): The French government's official accessibility resource for best practices and testing criteria * [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21): The internationally recognized standards for web accessibility, providing guidelines for creating more accessible web content * [WebAIM: Introduction to Web Accessibility](https://webaim.org/intro): A guide to the principles of web accessibility from WebAIM * [WebAIM: Semantic Structure](https://webaim.org/techniques/semanticstructure): Learn about the importance of semantic HTML and how it impacts accessibility * [WebAIM: Contrast Checker](https://webaim.org/resources/contrastchecker): Tool to ensure sufficient color contrast between text and background for readability * [French Accessibility Testing Methodology (FR)](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests): An in-depth guide to testing web accessibility in France * [French Testing Environment (FR)](https://accessibilite.numerique.gouv.fr/methode/environnement-de-test): Official guidelines on the tools and technologies to use when testing accessibility on desktop computers * [W3C Tutorial on Alternative Text for Images](https://www.w3.org/WAI/tutorials/images/decision-tree): A decision tree for writing appropriate alternative text for images ## Internationalization --- title: "Internationalization" slug: ovhcloud-design-system-build-internationalization category: generic type: overview version: 20.0.0 tokens: 608 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-build-internationalization.txt --- # Internationalization ODS does not embed any i18n library, as most of the translatable contents are coming from the integration side. There are two exceptions, components with full embedded translation and components with default translation on some accessibility attribute. ## Embedded translation So far, only the following components internally manage a complete translation system: - [Datepicker](https://ovh.github.io/design-system/v20.0.0/components/datepicker) - [Phone number](https://ovh.github.io/design-system/v20.0.0/components/phone-number) Both are relying on the native [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) feature. They do de-facto support the same locales as [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). ## ODS specific translation Although you have complete control on label translation when using the ODS components, there are a few internal elements that need a textual description for accessibility purpose. For example, take the [Message](https://ovh.github.io/design-system/v20.0.0/components/message) component: ![i18n anatomy](components/message/anatomy-i18n.png) Here, the close button needs to have the right `aria-label` value set for accessibility compliance. Though the element is not part of the composable components, it is internal. By default, ODS will provide a default `aria-label` message for all locales that we currently support. So if you use the component as-is, it will be accessible already. In case you want to change the locale to one supported by ODS, you can use the `locale` attribute of the component. ```tsx // This will change the close button aria-label to the french version Mon message ``` If the `locale` is not set, the component will try to use the navigator languages by default. In case you want to change to a locale not supported by ODS, or you want to override the default messages, you can set your own translation using the `i18n` attribute of the component. ```tsx // This will change the close button aria-label to your own string Mon message ``` ## ODS supported locale Current locales supported by ODS: - de - en - es - fr - it - nl - pl - pt ## Forms --- title: "Forms" slug: ovhcloud-design-system-build-forms category: generic type: overview version: 20.0.0 tokens: 6900 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-build-forms.txt --- # Forms These guidelines define how forms should behave and be structured across products using the OVHcloud Design System. This documentation does not describe a technical implementation, but provides functional and UX rules to follow when designing and developing forms. ## Mandatory and optional fields ### How to define mandatory fields A mandatory field must: - Explicitly include the word "Mandatory" in the label. - Never rely on an asterisk alone. - Clearly communicate the expected format in the helper text when relevant. ### Optional fields Optional fields do not need to be labeled "Optional" and can remain unmarked if mandatory fields are clearly identified. ```tsx { const [localError, setLocalError] = useState>({}); function onBlur(e: FormEvent): void { const target = e.target as HTMLInputElement; setLocalError((error) => ({ ...error, [target.name]: target.validity.valid ? undefined : target.validationMessage, })); } return (
First name - mandatory Last name - mandatory Company Phone Include country code (e.g. +33 6 00 00 00 00) Email - mandatory Format: name@example.com
); } ``` ## Submit behavior In the OVHcloud Design System, the submit should button remain enabled at all times. Validation is triggered when the user attempts to submit the form. The form must provide feedback after user action rather than prevent the action. ### Standard submit flow Initial state: - The submit button is visible and enabled. - Mandatory fields are clearly marked in the label. - Helper text communicates expected formats when relevant. - No error messages are displayed before interaction. When the user clicks the submit button: - All mandatory fields are validated. - All format validations are executed. - Field-level errors are displayed where needed. - A global error may be displayed if applicable. - No field values are cleared. If errors are found: - Each invalid field displays its error message. - Error styling is applied. - Fields remain populated. - The submit button remains enabled. - The user can immediately correct the fields and resubmit. If the form is displayed in a **Modal** or **Drawer**: - The container remains open. - Errors are displayed within the same context. If no errors are found: - The form proceeds to submission. - Success feedback is triggered (**Toast** or confirmation page depending on the flow). ### Relationship with inline validation Inline validation (on blur): - May display format errors as soon as the user leaves a field. - Improves correction speed. - Does not replace submit validation. On submit: - All validations are executed again to ensure consistency. - Required errors appear even if the field was never focused. ### Loading & action buttons states When the user submits a form: - The primary action button switches to a loading state. - The secondary action, if any, becomes disabled. This prevents duplicate submissions and conflicting actions, and clearly communicates that the request is being processed. ## Error handling Error handling must clearly communicate what went wrong and how the user can correct it. Error handling exists at two levels. Global errors explain why submission failed. Field-level errors explain what needs correction. ### Local errors (field-level) Field-level errors are tied to a specific input. They indicate that the value entered in a particular field is invalid or missing. #### When field-level errors are triggered Field-level errors can be triggered: - On blur (inline validation). - On submit. - After asynchronous validation (e.g. backend check). Submit validation must always re-validate all fields, even if inline validation is enabled. #### Examples of field-level errors - Required field left empty. - Invalid email format. - Password does not meet requirements. ### Global errors (form-level) Global errors are not tied to a single field. They occur when: - Backend validation fails. - A network error occurs. - A business rule prevents submission. - The action cannot be completed. #### Types of Global Errors ##### Recoverable Failure Use a **Toast** when: - The failure is temporary. - The user can retry immediately. - The error does not block form structure. Example: - Temporary network issue. ##### Critical / Blocking Failure Use a critical Message component when: - The submission fails definitively. - The user must take action. - The error is structural or business-related. - The error message is long or detailed. ##### In Modal or Drawer contexts - Always use a critical **Message**. - The message is displayed inside it. - The container remains open. #### Placement of global error When using a critical **Message**: - It should be placed above the action buttons. - It must not replace field-level errors. ### Example ```tsx { const [localError, setLocalError] = useState>({}); const [globalError, setGlobalError] = useState(''); const [isSubmitting, setIsSubmitting] = useState(false); function handleSubmit(e: FormEvent): void { e.preventDefault(); setGlobalError(''); setIsSubmitting(true); // Fake API call setTimeout(() => { setGlobalError('Something went wrong'); setIsSubmitting(false); }, 1000); } function onBlur(e: FormEvent): void { const target = e.target as HTMLInputElement; setLocalError((error) => ({ ...error, [target.name]: target.validity.valid ? undefined : target.validationMessage, })); } function onInvalid(e: FormEvent): void { e.preventDefault(); const target = e.target as HTMLInputElement; setLocalError((error) => ({ ...error, [target.name]: target.validationMessage, })); } return (
First name - mandatory { localError.firstname } Email - mandatory { localError.email } { !!globalError && setGlobalError('') }> { globalError } }
); } ``` ## Success handling ### Direct feedback Use a **Toast** when: - The action is completed successfully. - The user stays on the same page. - No additional flow is required. ### Confirmation page / modal Use when: - The flow continues. - The user moves to a next step. - A confirmation summary is required. ## Form structures ### Simple form with standard action buttons ```tsx
Phone number
``` ### Grouped fields form ```tsx { const [localError, setLocalError] = useState>({}); function onBlur(e: FormEvent): void { const target = e.target as HTMLInputElement; setLocalError((error) => ({ ...error, [target.name]: target.validity.valid ? undefined : target.validationMessage, })); } return (
Personal Information First name - mandatory Last name - mandatory Company Information Company name VAT number
); } ``` ### Critical form ```tsx { const [localError, setLocalError] = useState>({}); function onBlur(e: FormEvent): void { const target = e.target as HTMLInputElement; setLocalError((error) => ({ ...error, [target.name]: target.validity.valid ? undefined : target.validationMessage, })); } return (
Please type DELETE to confirm - mandatory This action is irreversible.
); } ``` ## Accessibility requirements - "Mandatory" must be visible in the label. - Expected input format must be visible in helper text. - Error messages must be programmatically associated with fields. - Fields must remain populated after validation errors. - Inline validation must not trap focus. ## Component selection guidelines This non-exhaustive section helps teams choose the right input component depending on intent. It is presented from the user intention perspective. Choosing a component is not only about the type of data. It is about: - How users think about the choice. - Whether comparison is important. - Whether precision is required. - Whether the action is reversible. - The cognitive load of the interface. The right component reduces friction before validation is even needed. ### When the user needs to provide short, structured information Use [Input](https://ovh.github.io/design-system/v20.0.0/components/input) component. Use for: - Personal information (First name, Last name). - Identifiers (Reference number, Customer ID). - Short labels (Project name, Tag name). Why? - Users expect a single-line input for short, structured answers. - Keeps vertical space minimal. - Encourages concise input. Do not use when: - The user must provide explanation or justification. - The expected answer may exceed one short sentence. ### When the user needs to explain, justify, or describe something Use [Textarea](https://ovh.github.io/design-system/v20.0.0/components/textarea) component. Use for: - Explain why the user is requesting a change. - Describe an issue the user encountered. - Additional comments. Why? - Visually communicates that longer input is expected. - Encourages detailed answers. - Prevents frustration caused by limited visible space. ### When the user must create or confirm secure credentials Use [Password](https://ovh.github.io/design-system/v20.0.0/components/password) component. Use for: - Account creation. - Password reset. - Sensitive authentication fields. Why? - Hides sensitive information. - May include strength indicators. - Can support show/hide functionality. ### When the user must enter an exact numeric value Use [Input](https://ovh.github.io/design-system/v20.0.0/components/input) or [Quantity](https://ovh.github.io/design-system/v20.0.0/components/quantity) component Use for: - Quantity of items. - Budget amount (precise value). - Number of licenses. - Percentage rate. Why? - Precision matters. - Value must be exact. Avoid when: - The number has formatting rules (phone, IBAN, BIC). - Users are more likely to think in ranges than exact values. ### When the user is selecting an approximate value or a range Use [Range](https://ovh.github.io/design-system/v20.0.0/components/range) component. Use for: - Budget filter. - Price filtering in search results. - Age range selection. - Performance tuning. Why? - Encourages exploration. - Works well for filtering. - Suitable when precision is not critical. Avoid when: - Legal, financial, or contractual precision is required. - The user must enter a specific numeric value. ### When users must choose one option and all options should be visible Use [Radio](https://ovh.github.io/design-system/v20.0.0/components/radio-group) buttons. Use for: - Choosing a subscription plan (e.g., Basic / Pro / Enterprise). - Selecting delivery method. - Choosing payment type. Why? - All options are visible. - Encourages comparison. - Reduces hidden choices. - Recommended when there are between 2 and 5 options. - Each option has important contextual differences. ### When users must choose one option from a list #### Select vs Combobox When a user must select a single option from a predefined list, the choice between **Select** and **Combobox** depends mainly on the size and complexity of the list. #### Use Select Use [Select](https://ovh.github.io/design-system/v20.0.0/components/select) when the list is limited and easy to scan visually. Typical situations: - Selecting a status (Draft / Pending / Approved). - Choosing a priority level (Low / Medium / High). - Selecting a department in a small organization. **Select** is appropriate when: - The number of options is moderate. - Users can easily scroll and recognize the right option. - Search is not necessary. #### Use Combobox Use [Combobox](https://ovh.github.io/design-system/v20.0.0/components/combobox) when the list is long or when search significantly improves usability. Typical situations: - Selecting a country from a global list. - Choosing a city. - Assigning a user from a large organization. - Selecting a product from a large catalog. **Combobox** is appropriate when: - The dataset is large. - Users are likely to know what they are looking for. - Scrolling through the entire list would be inefficient. ### When users can select multiple independent options Use [Checkboxes](https://ovh.github.io/design-system/v20.0.0/components/checkbox). Use for: - Selecting product features. - Choosing notification preferences. - Accepting multiple agreements. Why? - Clearly communicates independence. - No mutual exclusion implied. - Good for visible, short lists. ### When the user is enabling or disabling a setting Use [Toggle](https://ovh.github.io/design-system/v20.0.0/components/toggle) component. Use for: - Enable dark mode. - Activate notifications. - Turn on auto-renewal. Why? - Communicates immediate on/off state. - Best for persistent settings. Avoid when: - The action is critical or legally binding. - The user must explicitly confirm something important. In those cases, use a [Checkbox](https://ovh.github.io/design-system/v20.0.0/components/checkbox). ### When the user must select a specific date Use [Datepicker](https://ovh.github.io/design-system/v20.0.0/components/datepicker) component. Use for: - Booking a meeting. - Setting a deadline. - Scheduling delivery. Why? - Prevents format errors. - Reduces cognitive load. - Ensures valid date selection. Consider alternatives when: - Only month and year are required. - The user frequently types dates manually (advanced users). ### When the user must provide supporting material Use [File Upload](https://ovh.github.io/design-system/v20.0.0/components/file-upload) component. Use for: - Uploading identity documents. - Adding attachments to a request. - Submitting supporting evidence. - Uploading invoices. Why? - Allows users to provide official or visual proof that cannot be reliably captured in structured fields. - The content may need to be reviewed manually. - Reproducing the information through fields would be incomplete or unreliable. Avoid when: - The information can be captured through structured inputs (text, number, date, select). - The upload is used to compensate for missing inputs. ODS form elements can either be [controlled or uncontrolled](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components). You can use each form element directly in your own form, or wrap them using the [Form Field](https://ovh.github.io/design-system/v20.0.0/components/form-field) component. ## Form Field Using [Form Field](https://ovh.github.io/design-system/v20.0.0/components/form-field) component will enforce layout, design, behavior and accessibility through a few dedicated components: - `FormFieldLabel` - `FormFieldHelperText` - `FormFieldError` You can also deport the `invalid` prop from the form element to the `FormField` component which will handle the error display automatically. ```tsx Input: {/* Displayed only if invalid on FormField is true */} Error message ``` ## Uncontrolled Form Uncontrolled component will not have the `value` property set. You can use the `defaultValue` property to initialize the component with a value. Example of uncontrolled form: ```tsx import { BUTTON_EMPHASIS, Button, FormField, FormFieldLabel, Input } from '@ovhcloud/ods-react'; import { type FormEvent, useRef } from 'react'; const UncontrolledForm = () => { const formRef = useRef(null); function onSubmit(e: FormEvent) { e.preventDefault(); if (formRef.current) { const formData = new FormData(formRef.current); console.log(formData); } } return (
Input:
); }; ``` ## Controlled Form Controlled components will manage their `value` prop on their own and react to value change events. Example of controlled form: ```tsx import { BUTTON_EMPHASIS, Button, FormField, FormFieldLabel, Input } from '@ovhcloud/ods-react'; import { type ChangeEvent, useState } from 'react'; const ControlledForm = () => { const [inputValue, setInputValue] = useState('default'); function onInputChange(e: ChangeEvent) { setInputValue(e.target.value); } function onSubmit(e: FormEvent) { e.preventDefault(); console.log('input: ', inputValue); } return (
Input:
); }; ``` ## Using form library We'll demonstrate here a few form librairy, but you can plug ODS form elements with any library you like. Regardless of the library used, you can also use a schema validator to manage your data (like [yup](https://github.com/jquense/yup) or [zod](https://zod.dev/)). ### react-hook-form [React Hook Form](https://react-hook-form.com) is thought around native uncontrolled form elements (using `register`). These will mork on most ODS components, but some specific one may still need to rely on the lib `Controller` component. ```tsx import { BUTTON_EMPHASIS, Button, Datepicker, DatepickerContent, DatepickerControl, FormField, FormFieldLabel, Input } from '@ovhcloud/ods-react'; import { Controller, useForm } from 'react-hook-form'; type FormData = { datepicker: string, input: string, } const FormHookForm = () => { const { control, formState: { errors }, handleSubmit, register, setValue, } = useForm({ mode: 'onBlur' }); function onSubmit(data: FormData): void { console.log(data); } return (
Input: ( Datepicker: setValue(field.name, value) }> )} /> ); } ``` ### formik Here is another example using [Formik](https://formik.org) library. ```tsx import { BUTTON_EMPHASIS, Button, Datepicker, DatepickerContent, DatepickerControl, FormField, FormFieldLabel, Input } from '@ovhcloud/ods-react'; import { useFormik } from 'formik'; type FormData = { datepicker: string, input: string, } const FormFormik = () => { const formik = useFormik({ onSubmit: (values) => { console.log(values); }, validateOnMount: true, validationSchema, }); return (
Input: Datepicker: { formik.setFieldValue('datepicker', value); }}>
); } ``` ## Charts --- title: "Charts" slug: ovhcloud-design-system-build-charts category: generic type: overview version: 20.0.0 tokens: 1039 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-build-charts.txt --- # Charts These guidelines provide UI, functional, and UX rules to follow when creating charts. While this documentation is not exhaustive and does not cover technical implementation details, it serves as a comprehensive reference for designing effective and consistent data visualizations. ## General guidelines - **Consistency**: Maintain consistency in your chart types and styles across your application or platform - **Labels**: Clearly label your axes, legend, and data points. Use descriptive titles (or Tooltips) to help users understand the chart's purpose and details - **Accessibility**: Ensure your charts are accessible to all users (see [Accessible Charts](https://www.a11y-collective.com/blog/accessible-charts/)) ## Chart types The following chart types are commonly used in OVHcloud, categorized by their primary use cases: ### Bar Charts **Usage** - Comparing quantities or amounts between different categories - Displaying data in a stacked layout to show cumulative values **Best Practices** - Prefer using vertical bars rather than horizontal layout - Use solid bar colors to distinguish them from background ### Line Charts **Usage** - Showing progression and trends of data over time - Comparing multiple lines through a common criterion such as a timespan **Best Practices** - Prefer using solid lines for data series ### Area Charts **Usage** - Presenting the amplitude of content and focusing on drastic trend changes - Displaying data in a stacked layout to show cumulative values **Best Practices** - Top of areas must be a solid line to draw area limit - Opacity can be applied to areas to show data overlaps ### Pie Charts **Usage** - Displaying proportions and percentages of a whole amount **Best Practices** - Avoid more than 5 slices to keep clarity ## Styling ### Structural elements For structural elements, here are the expected values to apply: Element Token Color Preview Background --ods-semantic-color-chart-background #ffffff --ods-semantic-color-chart-background (default: #ffffff) Axis --ods-semantic-color-chart-axis #b3b3b3 --ods-semantic-color-chart-axis (default: #b3b3b3) Ticks (axis labels) --ods-semantic-color-chart-tick #4d4d4d --ods-semantic-color-chart-tick (default: #4d4d4d) Legends --ods-semantic-color-chart-legend #4d4d4d --ods-semantic-color-chart-legend (default: #4d4d4d) Grids --ods-semantic-color-chart-grid #cccccc --ods-semantic-color-chart-grid (default: #cccccc) Reference Line --ods-semantic-color-chart-reference-line #bf0020 --ods-semantic-color-chart-reference-line (default: #bf0020) - Font-family must follow ODS pre-set for all text labelling - Font-size minimum values to use are: - **12px** for axis labels - **14px** for legends - **16px** for tooltip content - ODS Tooltips must be used to define series data while hovering on values ## Color scheme Use the following colors for your chart series, in the specified order: | Series | Color | |---|---| | 1 | `#0050d7` | | 2 | `#ac246f` | | 3 | `#00875a` | | 4 | `#df3400` | | 5 | `#25327c` | | 6 | `#a61e20` | | 7 | `#006d77` | | 8 | `#6a2ecf` | | 9 | `#374151` | | 10 | `#4f8400` | These colors are picked for their likelihood to be valid regarding color contrast ratio, and can be distinguished from one another. ## Apply ODS Style --- title: "Apply ODS Style" slug: ovhcloud-design-system-customize-apply-ods-style category: generic type: overview version: 20.0.0 tokens: 350 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-apply-ods-style.txt --- # Apply ODS Style After installing ODS (following the [Get Started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) documentation), you'll be able to use every component with the correct style. For the non-component related style, you need to update your app accordingly. ## Use the ODS font ODS components do not enforce any font by default (except for a few, like `Code`). To use one of the ODS fonts in your app, add the expected variables to the top of your app: ```css html { font-family: var(--ods-semantic-font-family-body); } ``` ## Use the ODS design tokens All ODS components are using common design tokens, that are accessible through [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). If you want to use any of those on your own components, you can refer to the exhaustive list on the [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) page. They follow the theme the page loads, as the ODS components do (see [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes)). ```css .my-custom-title { color: var(--ods-semantic-color-content-text); ... } ``` ## Use ODS CSS reset We recommend you to import the ODS CSS reset subset of rules to normalize the rendering of some elements, but it's not mandatory. ```typescript import '@ovhcloud/ods-react/normalize-css'; ``` ## Themes --- title: "Themes" slug: ovhcloud-design-system-customize-themes category: generic type: overview version: 20.0.0 tokens: 2001 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-themes.txt --- # Themes A theme is a stylesheet that declares the ODS design tokens as CSS custom properties on `:root`. ODS components read these tokens, and so can your own CSS: load a theme, and both follow it. A theme names its fonts, but does not load them: loading them is up to you. ## Available themes `@ovhcloud/ods-themes` ships four themes. Each one is a complete stylesheet: - **Default** (`@ovhcloud/ods-themes/default/css`), the Aluminium look. - **Aluminium dark** (`@ovhcloud/ods-themes/aluminium-dark/css`), its dark mode. - **Blue Jeans** (`@ovhcloud/ods-themes/blue-jeans/css`), the OVHcloud look. - **Blue Jeans dark** (`@ovhcloud/ods-themes/blue-jeans-dark/css`), its dark mode. ## Load a theme Load a single theme. A theme does not build on another one: two themes loaded together override each other. ```typescript import '@ovhcloud/ods-themes/blue-jeans-dark/css'; ``` Then load the fonts it names (see **Fonts**). > Make sure the page loads the fonts of the theme you choose. A font the page does not load falls back to the next one of its stack, without any error. ## Fonts A theme names its fonts in three tokens: `--ods-semantic-font-family-body`, `--ods-semantic-font-family-heading` and `--ods-semantic-font-family-code`. Another theme may name other fonts. The four themes above use the same two fonts, **Source Sans 3** for text and **Source Code Pro** for code. ODS ships them in `@ovhcloud/ods-themes/default/fonts`, a name kept from v19 though it serves every theme, with **ODS Icon**, the icon font of the components, needed whatever the theme: ```typescript import '@ovhcloud/ods-themes/default/fonts'; ``` This stylesheet declares the fonts with relative `url()`s to the font files of the package: your bundler resolves them and emits the files. As a help for these four themes, `@ovhcloud/ods-themes/fonts-base64` declares the same fonts with the files inlined as base64, for a setup that cannot serve font files. Load it instead of `default/fonts`, not with it. It weighs about 700 KB and the browser cannot load its fonts in parallel: keep it as a fallback. ## Switch themes A page shows one theme. No attribute or class selects it: to switch themes, replace the theme stylesheet of the page. To follow the color scheme of the operating system, without any script, import each mode with a media query, so that only one applies: ```css @import '@ovhcloud/ods-themes/default/css' (prefers-color-scheme: light); @import '@ovhcloud/ods-themes/aluminium-dark/css' (prefers-color-scheme: dark); @import '@ovhcloud/ods-themes/default/fonts'; ``` To switch from your code, put an empty `` for the theme in the `` of your page, before your own stylesheets, and set its URL from your code: your styles stay after the theme and can override it. With Vite, a `?url` import emits the theme file and gives its URL: ```html ``` ```typescript import '@ovhcloud/ods-themes/default/fonts'; import lightThemeUrl from '@ovhcloud/ods-themes/default/css?url'; import darkThemeUrl from '@ovhcloud/ods-themes/aluminium-dark/css?url'; const theme = document.getElementById('ods-theme') as HTMLLinkElement; theme.href = lightThemeUrl; function setDarkMode(isDark: boolean): void { theme.href = isDark ? darkThemeUrl : lightThemeUrl; } ``` Without a bundler, serve the files the export paths resolve to, and point the `` at them: the layout of the package folder may change from one version to the next, the export paths do not. The fonts stay loaded when the theme changes. If the two themes do not name the same fonts, load the fonts of both. This documentation does it differently: it keeps the default theme loaded, and puts the theme shown, whole, in a single `

Starter plan

€4.99 / month
``` The [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) page explains which tokens to use and lists all of them. To read the token values from JavaScript (charts, a design tool sync), each theme ships a JSON next to its stylesheet: `@ovhcloud/ods-themes/default/tokens`, `aluminium-dark/tokens`, `blue-jeans/tokens` and `blue-jeans-dark/tokens`. Read the one of the theme the page loads. They share the `--ods-semantic-*` keys; the `--ods-palette-*` keys belong to each theme. ## Create your own theme A theme of your own is a stylesheet loaded **after** an ODS theme, that re-declares on `:root` the tokens you want to change. Any token can be re-declared: a color, a radius, a spacing, a font, a duration. ```css :root { /* the brand and accent ramps, from 50 to 900 */ --ods-palette-brand-500: #7a00cc; /* any semantic token */ --ods-semantic-size-radius-control: 0; --ods-semantic-font-family-body: 'My Font', sans-serif; } ``` ```typescript import '@ovhcloud/ods-themes/default/css'; import './my-theme.css'; ``` An ODS theme declares every token: loaded after your stylesheet, it overrides it. When the page switches themes, keep your stylesheet after the one shown. The `--ods-semantic-*` tokens are the public surface of a theme. The [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) page lists them, with their role. To change the colors, the brand and accent ramps are the shortest way: `--ods-palette-brand-*` paints the brand roles, `--ods-palette-accent-*` the text, headings, selection and form controls. They do not reach every role: the focus ring, the information, success, warning, critical and neutral statuses, and the chart series keep their values. Over the default theme, the brand ghost and outline Buttons also take their text from the accent ramp and their border from gray (`--ods-semantic-color-border-brand-minor`), which follows no ramp. Re-declare these roles themselves to change them. The [migration guide](https://ovh.github.io/design-system/v20.0.0/guides/migration-19-to-20) details which roles each ramp reaches. The ramps only take effect on `:root`: a theme scoped to a container, such as the root of a micro-frontend, re-declares the `--ods-semantic-*` roles themselves. The ODS themes do not aim the accent ramp at the same family: the default theme, Aluminium dark and Blue Jeans dark aim it at navy, Blue Jeans at blue. A stylesheet of yours re-declares the ramps of the theme it follows, so each theme can take its own. A font you name in a theme is yours to load (see **Fonts**). ## Style Customization --- title: "Style Customization" slug: ovhcloud-design-system-customize-style-customization category: generic type: overview version: 20.0.0 tokens: 631 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-style-customization.txt --- # Style Customization Although ODS components comes with the expected designs, it is sometime useful to customize the rendering of a component to fit your context. Here we'll describe different ways to customize an ODS component. ## Apply style directly on the component The ODS component host behave like any other React element, so you can apply a class directly to it. For example, if you want to display a vertical list of `Link`, you can override the inline default display: ```html My link 1 My link 2 ``` > As there is no shadow DOM anymore, all of the component DOM can be targeted through CSS selectors. > It is advised to not rely on cascading selector, as the DOM structure may evolve from one version to another. >
> To ensure reliable CSS, use a specific className on the component you want to customize. >
> If you want to specifically target underneath elements, you can rely on some [data attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/How_to/Use_data_attributes#css_access), we'll update the documentation about those soon. ## Reuse existing ODS style In some cases where you cannot use an ODS component, you may want one of your own components to look like an ODS component (for example, when using an external library that doesn't allow custom templating). We did expose a bunch of [Sass](https://sass-lang.com) mixins that allows you to easily apply the ODS style to your own elements. For example, if you need to make an anchor tag looks like a `Link`: ```scss @use '@ovhcloud/ods-react/style' as ods; .my-link { @include ods.ods-link(); } ``` ```html ``` ## CSS variables All ODS components are using common design tokens, that are accessible through [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). We do advise to reuse those variables on your own style, this way your application follows the theme it loads, as the ODS components do (see [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes)). You can find the whole list on the [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) documentation page. Example of CSS variables: ```html

Welcome page

``` ## Design Tokens --- title: "Design Tokens" slug: ovhcloud-design-system-customize-design-tokens category: generic type: overview version: 20.0.0 tokens: 5391 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-design-tokens.txt --- # Design Tokens Design tokens define reusable design values such as colors, borders, and outlines as variables. Instead of using hardcoded values, they provide a consistent, scalable, and maintainable way to style components across all products. ## Usage Design tokens are available as CSS custom properties (variables) and can be used in your CSS files: ```css .my-component { color: var(--ods-semantic-color-content-brand); border-radius: var(--ods-semantic-size-radius-control); } ``` ## Token types Two types of tokens are meant to be used in your code (the `--ods-palette-*` ramps are the input of a theme, see below): - **Semantic**, `--ods-semantic--` (e.g. `--ods-semantic-color-content-text`): values with a role, to style your own components and pages. - **Component**, `--ods--` (e.g. `--ods-button-background-color-brand-high`): values of a single ODS component, to customize it. **Semantic** tokens give a role to a value: the color of a text, of a surface, of a border, the radius of a control, the duration of an animation… Their name reads from the most generic to the most specific part, for example `--ods-semantic-color-surface-selected-solid` is a `color`, used as a `surface`, for a `selected` element, in its `solid` variant, the strongest of `-subtle`, the unsuffixed one and `-solid`. The text on it reads `--ods-semantic-color-content-on-selected-solid`, while `--ods-semantic-color-content-on-selected` is the ink for the tinted ones. **Component** tokens are declared by each component and default to semantic tokens. Override them to adjust one component without affecting the others: each component lists its own in the *CSS Variables* section of its *Technical information* tab. ## Which type should I use? Prefer **semantic** tokens in your application: they follow the theme, so your components stay consistent with ODS ones when the theme changes. Use **component** tokens only to customize an ODS component; never read them to style something else, as their value may change from one version to another. ## What is guaranteed The `--ods-semantic-*` tokens are the public surface of the theme: read them in your CSS, re-declare them in a theme. Their names and their meaning do not change during a major version; their values belong to the theme. The `--ods-palette-*` ramps are public too, as the input of a theme: a brand re-declares the `--ods-palette-brand-*` and `--ods-palette-accent-*` ramps. The tables below list every token of the default theme. ## Theme Variables ### Color | Token | Value | |---|---| | `--ods-semantic-color-surface-page` | `var(--ods-palette-gray-100)` | | `--ods-semantic-color-surface-raised` | `var(--ods-palette-white)` | | `--ods-semantic-color-surface-overlay` | `var(--ods-palette-white)` | | `--ods-semantic-color-surface-header` | `var(--ods-palette-accent-100)` | | `--ods-semantic-color-surface-backdrop` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-surface-code` | `var(--ods-palette-accent-900)` | | `--ods-semantic-color-surface-selected-subtle` | `var(--ods-palette-accent-50)` | | `--ods-semantic-color-surface-selected` | `var(--ods-palette-accent-100)` | | `--ods-semantic-color-surface-selected-solid` | `var(--ods-palette-accent-700)` | | `--ods-semantic-color-surface-muted` | `var(--ods-palette-gray-100)` | | `--ods-semantic-color-surface-neutral-subtle` | `var(--ods-palette-gray-100)` | | `--ods-semantic-color-surface-neutral` | `var(--ods-palette-gray-500)` | | `--ods-semantic-color-surface-brand` | `var(--ods-palette-brand-500)` | | `--ods-semantic-color-surface-accent-subtle` | `var(--ods-palette-accent-100)` | | `--ods-semantic-color-surface-accent` | `var(--ods-palette-accent-500)` | | `--ods-semantic-color-surface-information-subtle` | `var(--ods-palette-blue-100)` | | `--ods-semantic-color-surface-information` | `var(--ods-palette-blue-500)` | | `--ods-semantic-color-surface-success-subtle` | `var(--ods-palette-green-100)` | | `--ods-semantic-color-surface-success` | `var(--ods-palette-green-500)` | | `--ods-semantic-color-surface-warning-subtle` | `var(--ods-palette-orange-100)` | | `--ods-semantic-color-surface-warning` | `var(--ods-palette-orange-500)` | | `--ods-semantic-color-surface-critical-subtle` | `var(--ods-palette-red-100)` | | `--ods-semantic-color-surface-critical` | `var(--ods-palette-red-500)` | | `--ods-semantic-color-surface-control` | `var(--ods-palette-white)` | | `--ods-semantic-color-surface-control-solid` | `var(--ods-palette-accent-700)` | | `--ods-semantic-color-surface-thumb` | `var(--ods-palette-white)` | | `--ods-semantic-color-surface-track` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-surface-segmented` | `var(--ods-palette-accent-200)` | | `--ods-semantic-color-surface-readonly` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-surface-pending` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-surface-drag-over` | `var(--ods-palette-accent-50)` | | `--ods-semantic-color-surface-decorative-alpha` | `var(--ods-palette-decorative-alpha)` | | `--ods-semantic-color-surface-decorative-beta` | `var(--ods-palette-decorative-beta)` | | `--ods-semantic-color-surface-decorative-new` | `var(--ods-palette-decorative-new)` | | `--ods-semantic-color-surface-decorative-promotion` | `var(--ods-palette-decorative-promotion)` | | `--ods-semantic-color-content-heading` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-content-text` | `var(--ods-palette-accent-500)` | | `--ods-semantic-color-content-icon` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-content-group-label` | `var(--ods-palette-gray-900)` | | `--ods-semantic-color-content-placeholder` | `var(--ods-palette-gray-600)` | | `--ods-semantic-color-content-neutral` | `var(--ods-palette-gray-600)` | | `--ods-semantic-color-content-brand` | `var(--ods-palette-brand-500)` | | `--ods-semantic-color-content-brand-minor` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-content-accent` | `var(--ods-palette-accent-600)` | | `--ods-semantic-color-content-information` | `var(--ods-palette-blue-500)` | | `--ods-semantic-color-content-success` | `var(--ods-palette-green-700)` | | `--ods-semantic-color-content-warning` | `var(--ods-palette-orange-700)` | | `--ods-semantic-color-content-critical` | `var(--ods-palette-red-600)` | | `--ods-semantic-color-content-on-selected` | `var(--ods-palette-accent-700)` | | `--ods-semantic-color-content-on-neutral` | `var(--ods-palette-gray-600)` | | `--ods-semantic-color-content-on-brand` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-content-on-accent` | `var(--ods-palette-accent-500)` | | `--ods-semantic-color-content-on-information` | `var(--ods-palette-blue-500)` | | `--ods-semantic-color-content-on-success` | `var(--ods-palette-green-700)` | | `--ods-semantic-color-content-on-warning` | `var(--ods-palette-orange-700)` | | `--ods-semantic-color-content-on-critical` | `var(--ods-palette-red-700)` | | `--ods-semantic-color-content-on-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-selected-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-control-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-neutral-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-brand-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-accent-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-information-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-success-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-warning-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-critical-solid` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-code` | `var(--ods-palette-white)` | | `--ods-semantic-color-content-on-vivid` | `var(--ods-palette-blue-900)` | | `--ods-semantic-color-border-separator` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-border-track` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-border-container` | `var(--ods-palette-gray-300)` | | `--ods-semantic-color-border-neutral-subtle` | `var(--ods-palette-gray-300)` | | `--ods-semantic-color-border-neutral` | `var(--ods-palette-gray-500)` | | `--ods-semantic-color-border-control` | `var(--ods-palette-gray-500)` | | `--ods-semantic-color-border-control-solid` | `var(--ods-semantic-color-surface-control-solid)` | | `--ods-semantic-color-border-readonly` | `var(--ods-palette-gray-300)` | | `--ods-semantic-color-border-selected-solid` | `var(--ods-palette-accent-700)` | | `--ods-semantic-color-border-brand` | `var(--ods-palette-brand-500)` | | `--ods-semantic-color-border-brand-minor` | `var(--ods-palette-gray-500)` | | `--ods-semantic-color-border-accent-subtle` | `var(--ods-palette-accent-300)` | | `--ods-semantic-color-border-accent` | `var(--ods-palette-accent-500)` | | `--ods-semantic-color-border-information-subtle` | `var(--ods-palette-blue-300)` | | `--ods-semantic-color-border-information` | `var(--ods-palette-blue-500)` | | `--ods-semantic-color-border-success-subtle` | `var(--ods-palette-green-300)` | | `--ods-semantic-color-border-success` | `var(--ods-palette-green-500)` | | `--ods-semantic-color-border-warning-subtle` | `var(--ods-palette-orange-300)` | | `--ods-semantic-color-border-warning` | `var(--ods-palette-orange-400)` | | `--ods-semantic-color-border-critical-subtle` | `var(--ods-palette-red-300)` | | `--ods-semantic-color-border-critical` | `var(--ods-palette-red-500)` | | `--ods-semantic-color-border-drag-over` | `var(--ods-palette-brand-600)` | | `--ods-semantic-color-interaction-neutral-subtle-hover` | `var(--ods-palette-gray-100)` | | `--ods-semantic-color-interaction-neutral-subtle-active` | `var(--ods-palette-gray-100)` | | `--ods-semantic-color-interaction-brand-subtle-hover` | `var(--ods-palette-brand-100)` | | `--ods-semantic-color-interaction-brand-subtle-active` | `var(--ods-palette-brand-100)` | | `--ods-semantic-color-interaction-accent-subtle-hover` | `var(--ods-palette-accent-100)` | | `--ods-semantic-color-interaction-accent-subtle-active` | `var(--ods-palette-accent-100)` | | `--ods-semantic-color-interaction-information-subtle-hover` | `var(--ods-palette-blue-100)` | | `--ods-semantic-color-interaction-information-subtle-active` | `var(--ods-palette-blue-100)` | | `--ods-semantic-color-interaction-success-subtle-hover` | `var(--ods-palette-green-100)` | | `--ods-semantic-color-interaction-success-subtle-active` | `var(--ods-palette-green-100)` | | `--ods-semantic-color-interaction-warning-subtle-hover` | `var(--ods-palette-orange-100)` | | `--ods-semantic-color-interaction-warning-subtle-active` | `var(--ods-palette-orange-100)` | | `--ods-semantic-color-interaction-critical-subtle-hover` | `var(--ods-palette-red-100)` | | `--ods-semantic-color-interaction-critical-subtle-active` | `var(--ods-palette-red-100)` | | `--ods-semantic-color-interaction-neutral-hover` | `var(--ods-palette-gray-600)` | | `--ods-semantic-color-interaction-neutral-active` | `var(--ods-palette-gray-600)` | | `--ods-semantic-color-interaction-brand-hover` | `var(--ods-palette-brand-600)` | | `--ods-semantic-color-interaction-brand-active` | `var(--ods-palette-brand-600)` | | `--ods-semantic-color-interaction-brand-visited` | `var(--ods-palette-brand-700)` | | `--ods-semantic-color-interaction-accent-hover` | `var(--ods-palette-accent-600)` | | `--ods-semantic-color-interaction-accent-active` | `var(--ods-palette-accent-600)` | | `--ods-semantic-color-interaction-information-hover` | `var(--ods-palette-blue-600)` | | `--ods-semantic-color-interaction-information-active` | `var(--ods-palette-blue-600)` | | `--ods-semantic-color-interaction-success-hover` | `var(--ods-palette-green-600)` | | `--ods-semantic-color-interaction-success-active` | `var(--ods-palette-green-600)` | | `--ods-semantic-color-interaction-warning-hover` | `var(--ods-palette-orange-600)` | | `--ods-semantic-color-interaction-warning-active` | `var(--ods-palette-orange-600)` | | `--ods-semantic-color-interaction-critical-hover` | `var(--ods-palette-red-600)` | | `--ods-semantic-color-interaction-critical-active` | `var(--ods-palette-red-600)` | | `--ods-semantic-color-interaction-highlight` | `var(--ods-palette-accent-50)` | | `--ods-semantic-color-interaction-selected-highlight` | `var(--ods-palette-accent-200)` | | `--ods-semantic-color-interaction-control-hover` | `var(--ods-palette-accent-700)` | | `--ods-semantic-color-interaction-control-highlight` | `var(--ods-palette-accent-50)` | | `--ods-semantic-color-interaction-control-solid-hover` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-interaction-control-solid-active` | `var(--ods-palette-accent-800)` | | `--ods-semantic-color-interaction-track-hover` | `var(--ods-palette-gray-300)` | | `--ods-semantic-color-chart-background` | `var(--ods-semantic-color-surface-page)` | | `--ods-semantic-color-chart-axis` | `var(--ods-palette-gray-300)` | | `--ods-semantic-color-chart-grid` | `var(--ods-palette-gray-200)` | | `--ods-semantic-color-chart-tick` | `var(--ods-palette-gray-700)` | | `--ods-semantic-color-chart-legend` | `var(--ods-palette-gray-700)` | | `--ods-semantic-color-chart-reference-line` | `var(--ods-semantic-color-content-critical)` | | `--ods-semantic-color-chart-series-01` | `#0050d7` | | `--ods-semantic-color-chart-series-02` | `#ac246f` | | `--ods-semantic-color-chart-series-03` | `#00875a` | | `--ods-semantic-color-chart-series-04` | `#df3400` | | `--ods-semantic-color-chart-series-05` | `#25327c` | | `--ods-semantic-color-chart-series-06` | `#a61e20` | | `--ods-semantic-color-chart-series-07` | `#006d77` | | `--ods-semantic-color-chart-series-08` | `#6a2ecf` | | `--ods-semantic-color-chart-series-09` | `#374151` | | `--ods-semantic-color-chart-series-10` | `#4f8400` | | `--ods-semantic-color-shadow-control` | `var(--ods-palette-gray-900)` | | `--ods-semantic-color-shadow-raised` | `var(--ods-palette-gray-900)` | | `--ods-semantic-color-shadow-overlay` | `var(--ods-palette-gray-900)` | | `--ods-semantic-color-brand` | `var(--ods-palette-brand-700)` | ### Size | Token | Value | |---|---| | `--ods-semantic-size-space-inset-inline` | `8px` | | `--ods-semantic-size-space-inset-block` | `8px` | | `--ods-semantic-size-space-inset-block-compact` | `2px` | | `--ods-semantic-size-space-gap-inline` | `8px` | | `--ods-semantic-size-space-gap-block` | `8px` | | `--ods-semantic-size-space-gap-group` | `16px` | | `--ods-semantic-size-space-gap-section` | `32px` | | `--ods-semantic-size-radius-none` | `0` | | `--ods-semantic-size-radius-control` | `4px` | | `--ods-semantic-size-radius-container` | `8px` | | `--ods-semantic-size-radius-overlay` | `4px` | | `--ods-semantic-size-radius-pill` | `16px` | | `--ods-semantic-size-radius-full` | `calc(infinity * 1px)` | | `--ods-semantic-size-block-size-sm` | `24px` | | `--ods-semantic-size-block-size-md` | `32px` | | `--ods-semantic-size-block-size-lg` | `40px` | | `--ods-semantic-size-inline-size-field` | `280px` | | `--ods-semantic-border-thickness` | `1px` | | `--ods-semantic-border-thickness-strong` | `2px` | ### Font | Token | Value | |---|---| | `--ods-semantic-font-family-heading` | `'Source Sans 3', 'Trebuchet MS', arial, 'Segoe UI', sans-serif` | | `--ods-semantic-font-family-body` | `'Source Sans 3', 'Trebuchet MS', arial, 'Segoe UI', sans-serif` | | `--ods-semantic-font-family-code` | `'Source Code Pro', monospace` | | `--ods-semantic-font-weight-regular` | `400` | | `--ods-semantic-font-weight-semibold` | `600` | | `--ods-semantic-font-weight-bold` | `700` | ### Focus | Token | Value | |---|---| | `--ods-semantic-color-focus` | `var(--ods-palette-blue-600)` | | `--ods-semantic-border-focus-thickness` | `2px` | | `--ods-semantic-border-focus-offset` | `2px` | | `--ods-semantic-border-focus-style` | `solid` | ### Elevation | Token | Value | |---|---| | `--ods-semantic-opacity-disabled` | `var(--ods-palette-opacity-50)` | | `--ods-semantic-opacity-backdrop` | `var(--ods-palette-opacity-75)` | | `--ods-semantic-shadow-control` | `0 0 #0000` | | `--ods-semantic-shadow-raised` | `0 0 #0000` | | `--ods-semantic-shadow-overlay` | `0 4px 6px -1px color-mix(in srgb, var(--ods-semantic-color-shadow-overlay) 20%, transparent), 0 2px 4px -2px color-mix(in srgb, var(--ods-semantic-color-shadow-overlay) 20%, transparent)` | | `--ods-semantic-z-index-sticky` | `100` | | `--ods-semantic-z-index-dropdown` | `200` | | `--ods-semantic-z-index-drawer` | `300` | | `--ods-semantic-z-index-modal` | `400` | ### Motion | Token | Value | |---|---| | `--ods-semantic-motion-duration-instant` | `0s` | | `--ods-semantic-motion-duration-fast` | `150ms` | | `--ods-semantic-motion-duration-medium` | `200ms` | | `--ods-semantic-motion-duration-slow` | `300ms` | | `--ods-semantic-motion-easing` | `ease-in-out` | | `--ods-semantic-motion-easing-enter` | `ease-out` | | `--ods-semantic-motion-easing-exit` | `ease-in` | ## Color Palettes | Token | Value | |---|---| | `--ods-palette-accent-50` | `var(--ods-palette-navy-50)` | | `--ods-palette-accent-100` | `var(--ods-palette-navy-100)` | | `--ods-palette-accent-200` | `var(--ods-palette-navy-200)` | | `--ods-palette-accent-300` | `var(--ods-palette-navy-300)` | | `--ods-palette-accent-400` | `var(--ods-palette-navy-400)` | | `--ods-palette-accent-500` | `var(--ods-palette-navy-500)` | | `--ods-palette-accent-600` | `var(--ods-palette-navy-600)` | | `--ods-palette-accent-700` | `var(--ods-palette-navy-700)` | | `--ods-palette-accent-800` | `var(--ods-palette-navy-800)` | | `--ods-palette-accent-900` | `var(--ods-palette-navy-900)` | | Token | Value | |---|---| | `--ods-palette-blue-50` | `#f3fdff` | | `--ods-palette-blue-100` | `#e6faff` | | `--ods-palette-blue-200` | `#bef1ff` | | `--ods-palette-blue-300` | `#85d9fd` | | `--ods-palette-blue-400` | `#4bb2f6` | | `--ods-palette-blue-500` | `#0050d7` | | `--ods-palette-blue-600` | `#002dbe` | | `--ods-palette-blue-700` | `#000e9c` | | `--ods-palette-blue-800` | `#00185e` | | `--ods-palette-blue-900` | `#000d1f` | | Token | Value | |---|---| | `--ods-palette-brand-50` | `var(--ods-palette-blue-50)` | | `--ods-palette-brand-100` | `var(--ods-palette-blue-100)` | | `--ods-palette-brand-200` | `var(--ods-palette-blue-200)` | | `--ods-palette-brand-300` | `var(--ods-palette-blue-300)` | | `--ods-palette-brand-400` | `var(--ods-palette-blue-400)` | | `--ods-palette-brand-500` | `var(--ods-palette-blue-500)` | | `--ods-palette-brand-600` | `var(--ods-palette-blue-600)` | | `--ods-palette-brand-700` | `var(--ods-palette-blue-700)` | | `--ods-palette-brand-800` | `var(--ods-palette-blue-800)` | | `--ods-palette-brand-900` | `var(--ods-palette-blue-900)` | | Token | Value | |---|---| | `--ods-palette-gray-50` | `#f9f9f9` | | `--ods-palette-gray-100` | `#f2f2f2` | | `--ods-palette-gray-200` | `#e6e6e6` | | `--ods-palette-gray-300` | `#cccccc` | | `--ods-palette-gray-400` | `#b3b3b3` | | `--ods-palette-gray-500` | `#757575` | | `--ods-palette-gray-600` | `#666666` | | `--ods-palette-gray-700` | `#4d4d4d` | | `--ods-palette-gray-800` | `#333333` | | `--ods-palette-gray-900` | `#1a1a1a` | | Token | Value | |---|---| | `--ods-palette-green-50` | `#ecfdf5` | | `--ods-palette-green-100` | `#d1fae5` | | `--ods-palette-green-200` | `#a7f3d0` | | `--ods-palette-green-300` | `#6ee7b7` | | `--ods-palette-green-400` | `#34d399` | | `--ods-palette-green-500` | `#10b981` | | `--ods-palette-green-600` | `#09a171` | | `--ods-palette-green-700` | `#067958` | | `--ods-palette-green-800` | `#002d1f` | | `--ods-palette-green-900` | `#03140e` | | Token | Value | |---|---| | `--ods-palette-navy-50` | `#f4f5f8` | | `--ods-palette-navy-100` | `#edf0f5` | | `--ods-palette-navy-200` | `#d6deea` | | `--ods-palette-navy-300` | `#bbc7db` | | `--ods-palette-navy-400` | `#6c82a6` | | `--ods-palette-navy-500` | `#374f76` | | `--ods-palette-navy-600` | `#283d61` | | `--ods-palette-navy-700` | `#1a2d4b` | | `--ods-palette-navy-800` | `#101e35` | | `--ods-palette-navy-900` | `#091222` | | Token | Value | |---|---| | `--ods-palette-orange-50` | `#fffbeb` | | `--ods-palette-orange-100` | `#fef3c7` | | `--ods-palette-orange-200` | `#fde68a` | | `--ods-palette-orange-300` | `#fcd34d` | | `--ods-palette-orange-400` | `#fbbf24` | | `--ods-palette-orange-500` | `#f59e0b` | | `--ods-palette-orange-600` | `#e08125` | | `--ods-palette-orange-700` | `#a95723` | | `--ods-palette-orange-800` | `#401d0c` | | `--ods-palette-orange-900` | `#1b0b04` | | Token | Value | |---|---| | `--ods-palette-red-50` | `#fdecec` | | `--ods-palette-red-100` | `#fbd5d3` | | `--ods-palette-red-200` | `#f7aaa7` | | `--ods-palette-red-300` | `#f08581` | | `--ods-palette-red-400` | `#f2756f` | | `--ods-palette-red-500` | `#ca4b47` | | `--ods-palette-red-600` | `#b3403c` | | `--ods-palette-red-700` | `#8a302d` | | `--ods-palette-red-800` | `#381312` | | `--ods-palette-red-900` | `#1c0a09` | | Token | Value | |---|---| | `--ods-palette-black` | `#000000` | | `--ods-palette-decorative-alpha` | `#fbfe47` | | `--ods-palette-decorative-beta` | `#47fe78` | | `--ods-palette-decorative-new` | `#47fffa` | | `--ods-palette-decorative-promotion` | `#ccff66` | | `--ods-palette-white` | `#ffffff` | ### Opacity | Token | Value | |---|---| | `--ods-palette-opacity-15` | `0.15` | | `--ods-palette-opacity-20` | `0.2` | | `--ods-palette-opacity-25` | `0.25` | | `--ods-palette-opacity-50` | `0.5` | | `--ods-palette-opacity-75` | `0.75` | ## Tailwind CSS Integration --- title: "Tailwind CSS Integration" slug: ovhcloud-design-system-customize-tailwind-css-integration category: generic type: overview version: 20.0.0 tokens: 2634 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-customize-tailwind-css-integration.txt --- # Tailwind CSS Integration This guide covers how to use Tailwind CSS utilities with the OVHcloud Design System (ODS) design tokens. Tailwind CSS is not mandatory: ODS is not based on it, and `@ovhcloud/ods-react` does not depend on it. `@ovhcloud/ods-tailwind` is an opt-in package for the apps that use Tailwind CSS v4: it maps the Tailwind utilities to the ODS semantic tokens, so that `bg-ods-surface-raised` or `rounded-ods-container` read the same values as the ODS components. ## Installation `@ovhcloud/ods-tailwind` requires Tailwind CSS v4. ```bash npm install @ovhcloud/ods-tailwind tailwindcss @tailwindcss/vite ``` Add the Tailwind plugin of your bundler, for instance with Vite: ```typescript // vite.config.ts import tailwindcss from '@tailwindcss/vite'; import react from '@vitejs/plugin-react'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [react(), tailwindcss()], }); ``` Then import `@ovhcloud/ods-tailwind` in your stylesheet, followed by the ODS theme. It brings Tailwind CSS itself: do not import `tailwindcss` again. ```css /* index.css */ @import '@ovhcloud/ods-tailwind'; @import '@ovhcloud/ods-themes/default/css'; @import '@ovhcloud/ods-themes/default/fonts'; ``` ### Import order Import this stylesheet **before any ODS theme or component**, as the first import of your entry point, and import the ODS theme from it rather than from JavaScript: ```typescript // main.tsx import './index.css'; import { createRoot } from 'react-dom/client'; import { App } from './App'; ``` > `@ovhcloud/ods-tailwind` declares the order of the CSS layers: the Tailwind theme and base, then the ODS layers, then the Tailwind components and utilities. A layer takes its place from the first stylesheet that names it, and the ODS theme and components name the ODS layers too. If either is imported before `@ovhcloud/ods-tailwind`, the ODS layers land before the Tailwind base styles, which then reset the ODS buttons and headings. With this order, the ODS styles win over the Tailwind base styles, and your own styles win over the ODS ones: a utility on an ODS component, or a rule of yours in `@layer components`, where Tailwind puts the styles of your components. Target an ODS element with a class rather than a tag selector there: a `.card button` rule in `@layer components` also restyles every ODS button of the card. For an order that holds whatever the import order, declare it in the `` of your page, before any stylesheet: ```html ``` With a Content Security Policy, allow this inline style with its hash or a nonce. ## Utilities Every utility has an `ods-` prefix, which keeps it apart from the Tailwind defaults (these stay available): ODS tokens Utilities --ods-semantic-color-* bg-ods-surface-raised, text-ods-content-heading, border-ods-border-container, and every other color utility (fill-, ring-, outline-…) --ods-semantic-size-radius-* rounded-ods-control, rounded-ods-container, rounded-ods-pill --ods-semantic-shadow-* shadow-ods-raised, shadow-ods-overlay --ods-semantic-font-family-* font-ods-body, font-ods-heading, font-ods-code --ods-semantic-font-weight-* font-ods-regular, font-ods-semibold, font-ods-bold --ods-semantic-size-space-* p-ods-inset-inline, gap-ods-gap-group, m-ods-gap-section, and every other spacing utility --ods-semantic-size-block-size-*, --ods-semantic-size-inline-size-field h-ods-block-md, w-ods-inline-field --ods-semantic-motion-easing* ease-ods-default, ease-ods-enter, ease-ods-exit A utility is named after its token: `--ods-semantic-color-surface-raised` gives `bg-ods-surface-raised`, `--ods-semantic-size-space-gap-group` gives `gap-ods-gap-group`. See [Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) for what each token is for. The palette (`--ods-palette-*`) is not mapped: use the semantic tokens, the ones a theme re-points. ```tsx import { BADGE_STATUS, Badge, TEXT_PRESET, Text } from '@ovhcloud/ods-react'; function Summary() { return (
Your order Ready
); } ``` On a solid ground, use the content token made for it: `bg-ods-surface-brand` goes with `text-ods-content-on-brand-solid`. `bg-ods-brand` is the brand color of the logo, not a surface. The page font is the ODS body font, and the monospace font the ODS code font: the Tailwind base styles set them on the page, so the ODS components and their overlays (Modal, Popover, Tooltip…) inherit them with no class. The tokens Tailwind has no theme for are not mapped. Read them with the variable shorthand: `z-(--ods-semantic-z-index-modal)`, `opacity-(--ods-semantic-opacity-disabled)`, `duration-(--ods-semantic-motion-duration-fast)`. ## Themes The utilities read the ODS tokens (`var(--ods-semantic-…)`), never their values. The same classes follow the theme the page loads, dark themes included, with no Tailwind configuration: load another theme, or switch themes as [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) explains, and they change with it. Import another theme instead of the default one, after `@ovhcloud/ods-tailwind`. A theme is complete: import only one, with the fonts it names. ```css /* index.css, with the Blue Jeans dark theme */ @import '@ovhcloud/ods-tailwind'; @import '@ovhcloud/ods-themes/blue-jeans-dark/css'; @import '@ovhcloud/ods-themes/default/fonts'; ``` To follow the system setting with no JavaScript, condition each mode on it, so that only one applies: ```css @import '@ovhcloud/ods-tailwind'; @import '@ovhcloud/ods-themes/default/css' (prefers-color-scheme: light); @import '@ovhcloud/ods-themes/aluminium-dark/css' (prefers-color-scheme: dark); @import '@ovhcloud/ods-themes/default/fonts'; ``` A theme switched from your code, as [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) does it with a `` in the ``, is loaded outside `@ovhcloud/ods-tailwind`: declare the layer order first in the ``, before that `` (see **Import order**), or the theme sets it and the Tailwind base styles reset the ODS components. ```html ``` ### The dark variant If your own classes use the `dark:` variant, make it follow the same switch as the ODS dark theme. By default, it follows the color scheme of the operating system, as a dark theme loaded with `(prefers-color-scheme: dark)` does. If your code swaps the light and dark themes, also set an attribute of your own on ``, `data-dark` for instance, and point the variant at it: ```css /* Tailwind CSS v4, in index.css */ @custom-variant dark (&:where([data-dark], [data-dark] *)); ``` ```js // Tailwind CSS v3, in tailwind.config.js export default { darkMode: ['selector', '[data-dark]'], // … }; ``` ODS itself reads no attribute: `data-dark` only drives your `dark:` classes. ### Without the layer order If your app already sets its own Tailwind entry point and layer order, import only the utilities, after Tailwind, and after any reset of a namespace (`--color-*: initial`), which would clear the ODS utilities too: ```css @import 'tailwindcss'; @import '@ovhcloud/ods-tailwind/theme.css'; ``` Then keep the ODS layers (`ods-quarks`, `ods-atoms`, `ods-molecules`, `ods-organisms`) after the Tailwind `base` layer and before `components` in your own `@layer` statement. ## Tailwind CSS v3 `@ovhcloud/ods-tailwind` requires Tailwind CSS v4. With Tailwind CSS v3, map the tokens you need in your `tailwind.config.js`, under the same names: ```js /** @type {import('tailwindcss').Config} */ export default { content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'], theme: { extend: { borderRadius: { 'ods-container': 'var(--ods-semantic-size-radius-container)', 'ods-control': 'var(--ods-semantic-size-radius-control)', }, colors: { 'ods-border-container': 'var(--ods-semantic-color-border-container)', 'ods-content-heading': 'var(--ods-semantic-color-content-heading)', 'ods-surface-raised': 'var(--ods-semantic-color-surface-raised)', }, fontFamily: { 'ods-body': 'var(--ods-semantic-font-family-body)', }, }, }, }; ``` Tailwind CSS v3 has no layer order of its own to declare: its base styles do not use cascade layers, so they always win over the ODS styles and reset the ODS buttons and headings. Leave the Tailwind preflight out: `corePlugins: { preflight: false }`. ## Integration with IDEs In VS Code, install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension: the `ods-*` classes complete from your CSS file (v4) or your configuration (v3). In Tailwind CSS v4, if the extension does not find your CSS file, point its `tailwindCSS.experimental.configFile` setting at it. JetBrains IDEs complete them with no setup. ## Resources - [Tailwind CSS theme variables](https://tailwindcss.com/docs/theme) - [Tailwind CSS v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide) - [ODS Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes) - [ODS Design Tokens](https://ovh.github.io/design-system/v20.0.0/guides/design-tokens) ## What's new --- title: "What's new" slug: ovhcloud-design-system-upgrade-what-s-new category: generic type: overview version: 20.0.0 tokens: 924 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new.txt --- # What's new *Release notes of the current major version, v20. Earlier versions are listed under [What's new in previous versions](https://ovh.github.io/design-system/v20.0.0/guides/whats-new-v19); the [Changelog](https://ovh.github.io/design-system/v20.0.0/guides/changelog) lists every change.* ## v20.0.0 v20 has breaking changes in the component API and in the theme. Follow the [Migration 19.x to 20.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-19-to-20) guide before you upgrade: run `npx @ovhcloud/ods-migrate .` first, it applies most of the guide to your code. ### Project changes - **React 19** is supported, and React 18 still is: the peer dependency range is unchanged. - **Themes** are rebuilt on a semantic layer of tokens, and the default theme gets a new, neutral look. Four themes are shipped, each as one complete stylesheet: the default theme (Aluminium), its dark mode, Blue Jeans (the OVHcloud look) and its dark mode. See [Themes](https://ovh.github.io/design-system/v20.0.0/guides/themes). - **Documentation** moves from Storybook to a new documentation website, published as `@ovhcloud/ods-docs` in place of `@ovhcloud/ods-storybook`. - **APIs deprecated in v19 are removed**, the Switch component among them. The `color` prop is removed too, in favor of `status` where the component has one. ### New packages **@ovhcloud/ods-migrate** Moves the code of an app from ODS v19 to v20: a command that rewrites what has a v20 equivalent and marks what needs a decision, with ESLint and stylelint rules for what is left. [See Documentation](https://ovh.github.io/design-system/v20.0.0/guides/migration-19-to-20). **@ovhcloud/ods-mcp** An MCP server that gives AI assistants access to the ODS documentation. [See Documentation](https://ovh.github.io/design-system/v20.0.0/guides/mcp-server). **@ovhcloud/ods-tailwind** Tailwind CSS v4 utilities mapped to the ODS tokens. [See Documentation](https://ovh.github.io/design-system/v20.0.0/guides/tailwind). ### New components **Command** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/command). ### Feature updates **Accordion** - New attribute `emphasis` has been added. **Badge** - New attributes `status` and `emphasis` have been added. **Button** - New attributes `status` and `emphasis` have been added, `emphasis` replaces `variant`. **Card** - New attribute `status` has been added. **Drawer** - New attribute `backdrop` has been added. With it, the page no longer scrolls and a click on the backdrop closes the drawer. **Input** - New attributes `startContent` and `endContent` have been added. **Message** - New attributes `status` and `emphasis` have been added, `emphasis` replaces `variant`. **Pagination** - New attributes `getPageUrl` and `linkAs` have been added, to render the pages as links. **Spinner** - New CSS custom property `--ods-spinner-color` has been added. **Table** - New attribute `striped` has been added, it replaces `variant`. **Tabs** - New attribute `mountStrategy` has been added, to choose when the content of the inactive panels is rendered. **Tag** - New attribute `status` has been added. **Toaster** - New method `toast.accent()` has been added, it replaces `toast.primary()`. ### Bug fixes **Select** - The hidden native select no longer makes the page taller and scrollable. **Themes** - TypeScript 6 accepts the stylesheet imports, such as `import '@ovhcloud/ods-themes/default/css'` and `import '@ovhcloud/ods-react/normalize-css'`. **Recipes** - The fields and icon buttons of Chat, Dashboard Card, Data Grid, Data Grid With Query Filter, Range Input and Feature List Product Card have an accessible name. ## What's new in v19 --- title: "What's new in v19" slug: ovhcloud-design-system-upgrade-what-s-new-v19 category: generic type: overview version: 20.0.0 tokens: 6632 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v19.txt --- # What's new in v19 *Release notes of v19. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v19.7.3 ### Bug fixes **Datatable** - Fix z-index conflicts with sticky header and pinned columns. **Combobox** - Allow controlled combobox to be cleared programmatically ## v19.7.2 ### Tooling - Package manager migrated from Yarn to **pnpm**. - CI pipeline optimized. ## v19.7.1 ### Bug fixes **PromptInput** - Browser feature detection no longer throws in jsdom or Node.js environments. ## v19.7.0 ### New components **Avatar** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/avatar). **DataTable** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/data-table). **FileThumbnail** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/file-thumbnail). **Markdown** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/markdown). **MessageBubble** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/message-bubble). **PromptInput** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/prompt-input). **QueryFilter** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/query-filter). ### New recipes **Data Grid with Query Filter** [See Recipes](https://ovh.github.io/design-system/v20.0.0/recipes/components). **Chat** [See Recipes](https://ovh.github.io/design-system/v20.0.0/recipes/components). ### Feature updates **Compound components** ODS now offers different ways to be imported in your project, either through the main export that provides everything (like in previous version) or per-component. The current way: ```tsx import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@ovhcloud/ods-react'; Hello World! Lorem ipsum dolor sit amet. ``` The per-component way: ```tsx import { Accordion } from '@ovhcloud/ods-react/accordion'; Hello World! Lorem ipsum dolor sit amet. ``` We did test on a bunch of different bundler configuration to ensure that the tree-shaking is still working as expected and that existing configuration will not be impacted. **Clipboard** - New attribute `positionerStyle` has been added. **Code** - Copy button is now sticky when content is scrollable. - New attribute `positionerStyle` has been added. **Combobox** - New attributes `open`, `defaultOpen` and `onOpenChange` have been added. - New attribute `overlayConfig` has been added, with `flip` and `sameWidth` options. **Datepicker** - New attribute `onOpenChange` has been added. - New attribute `overlayConfig` has been added, with a `flip` option. **Divider** - New attribute `orientation` has been added to support vertical dividers. **Helpers** - New helper function `formatRelativeTime` has been added. **Icon** - Add the following new icons: `accessibility`, `accessibility-full`, `paperclip`, `pause`, `pause-full`, `phone`, `play`, `play-full`, `stop`, `stop-full`, `theme`. **Menu** - New attribute `overlayConfig` has been added, with `flip`, `gutter` and `sameWidth` options. **Pagination** - New page selector feature has been added. **Popover** - New attribute `overlayConfig` has been added, with a `flip` option. **ProgressBar** - New `indeterminate` value has been added. **Select** - New attributes `open`, `defaultOpen` and `onOpenChange` have been added. - New attribute `overlayConfig` has been added, with a `flip` option. **Tooltip** - New attribute `overlayConfig` has been added, with `flip`, `gutter` and `sameWidth` options. ### Bug fixes **Accordion** - Trigger text can now be selected. **Cart** - Remove button is now aligned with the label. - Item price is now correctly aligned to the right. **Combobox** - Caret click no longer triggers a form submit. **Datepicker** - Text input display bug has been fixed. **Font** - Variable weight declaration has been fixed. **Meter** - Track container no longer overflows. **Table** - Sticky header border issue on scroll has been fixed. **Textarea** - Placeholder now uses the theme color. ### Documentation improvements - Tech anatomy sections are now dynamic. - Icon gallery has been improved. ## v19.6.1 ### Feature updates **Menu** - handle disabled state on MenuItem. ### Bug fixes **Combobox** - Hide caret button from screen readers. **FileUpload** - Update file item size color to a valid contrasted one. ## v19.6.0 ### New components **Cart** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/cart). **Menu** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/menu). ### New recipes **Dashboard Card** [See Recipes](https://ovh.github.io/design-system/v20.0.0/recipes/components). ### Design updates **Theme** - New token `--ods-theme-chart-axis-color` has been added. - New token `--ods-theme-chart-background-color` has been added. - New token `--ods-theme-chart-grid-color` has been added. - New token `--ods-theme-chart-legend-color` has been added. - New token `--ods-theme-chart-reference-line-color` has been added. - New token `--ods-theme-chart-tick-color` has been added. **Combobox** - A caret is now displayed on the right side of the control. **Toaster** - Toasts are now animated. ### Feature updates **Icon** - Add the following new icons: brain, diagnostic, handshake, headphones, keyboard, reddit, ssl-key, snowflake, suitcase, target, user-full - `user` icon has been changed, previous icon is now called `user-full`. - `mic-off` and `pin-off` icons have been updated. **Tag** - New attribute `icon` has been added. ### Bug fixes **Accordion** - Content style now inherit only bottom border-radius. **Combobox** - `disable` has been remove from `ComboboxOptionItem` and `ComboboxGroupItem` interfaces, as they weren't doing anything. **Menu** - Arrow tip dom has been changed to inherit content background color. **Popover** - Arrow tip dom has been changed to inherit content background color. **Tooltip** - Arrow tip dom has been changed to inherit content background color. ### Documentation improvements - A new guide `Form Guidelines` has been added to the documentation. - A new guide `Chart Guidelines` has been added to the documentation. - A new separated LLM documentation for every components has been added. - Fix mixin import example. - Fix some code examples that weren't displaying false boolean attribute. ## v19.5.0 ### New components **Editable** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/editable). **Logo** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/logo). **Tile** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/tile). ### New recipes **Config Tile** [See Recipes](https://ovh.github.io/design-system/v20.0.0/recipes/components). **Feature List Product Card** [See Recipes](https://ovh.github.io/design-system/v20.0.0/recipes/components). ### Design updates **Theme** - New token `--ods-theme-brand-color` has been added. - `ods-color-promotion` has been updated to a new value. **Accordion** - Now has a default border radius. **Badge** - `--ods-badge-text-color-promotion` token as been updated to match new promotion color. - Badge sizes and padding have been adjusted. **Modal** - Header is now a colorless element that can contain actual content. **Tag** - Tag sizes and padding have been adjusted. ### Feature updates **Overlays z-index** In previous version of ODS, `Drawer` and `Modal` z-indexes were set to a lesser value than other overlay elements (popover, select, ...). This was allowing those to display correctly when set inside a modal. But this was causing an issue when, for example, a popover was kept open behind a modal, as it will be visible above the modal backdrop. Starting from this version, `Drawer` and `Modal` z-indexes are now greater than other overlay elements. This may cause issue with your current usage of overlay elements inside `Modal`. To use such element correctly, you'll have to set the `createPortal={ false }` on overlay elements inside `Modal`. You can see some examples on the [Modal Technical Page](https://ovh.github.io/design-system/v20.0.0/components/modal). We've also added a `positionerStyle` attribute on all overlay elements to allow you to override the positioner style and set up your own `z-index` values if needed. **Accordion** - New attribute `expandIconPosition` has been added. **Datepicker** - New attribute `positionerStyle` has been added. **Drawer** - New attribute `positionerStyle` has been added. **Form Field** - New composition component `FormFieldLabelSubLabel` has been added. **Modal** - New attribute `backdropStyle` has been added. - New attribute `positionerStyle` has been added. - New composition component `ModalHeader` has been added. - You can now setup your own modal header with a custom node. - [DEPRECATED] Color attribute is not used anymore, as modal header doesn't have any color anymore. **Popover** - New attribute `positionerStyle` has been added. **Select** - New attribute `positionerStyle` has been added. **Tooltip** - New attribute `positionerStyle` has been added. ### Recipe changes **Feature List** **Order Button** **Product Card** - Style have updated with latest design requirements, mostly text changes and tooltip alignment. ### Documentation improvements A new page `Roadmap` has been added to the documentation. You can refer to it to have an overview of what we're working on and what you could expect for the future ODS releases. Please note that this page may be updated in case of major priority changes, outside of an ODS version release. - Medium examples have been updated as they were the same as `Logo`. ### Miscellaneous - Remove console warning about `Modal` color depreciation, as it was print even if color wasn't set. ## v19.4.1 ### Bug fixes **Datepicker** - Overriding `display` on `DatepickerContent` now won't cause any closing issue. **Drawer** - Overriding `opacity` on `DrawerContent` now won't cause any closing issue. **Modal** - Overriding `display` on `ModalContent` now won't cause any closing issue. **Popover** - Overriding `display` on `PopoverContent` now won't cause any closing issue. **Range** - Fix infinite loop that may occurs on dual range. **Select** - Overriding `display` on `SelectContent` now won't cause any closing issue. **Tooltip** - Overriding `display` on `TooltipContent` now won't cause any closing issue. ## v19.4.0 ### New features **Helpers** `@ovhcloud/ods-react` package now expose the following helper functions: - `formatPrice`: useful to format an amount into a price with currency for a given locale. You can find more information about helpers on the new dedicated section in the documentation. **Recipes** Recipes are ready-to-use UI patterns built with ODS components. They provide pre-implemented code snippets for common use cases, helping you build consistent interfaces faster. Each recipe may include multiple implementations, so you can choose the styling approach that fits your project. We're still iterating on the whole recipe system to ensure it fits integrator needs. Feel free to share with us your feedback with your own experience while using those recipes. You can find more information about recipes on the new dedicated section in the documentation. ### New components **Button Group** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/button-group). **Kbd** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/kbd). ### Design updates **Tabs** > This change may impact your layouts. - Default tabs height have been increased. ### Feature updates **Icon** - Add 17 new icons. **Switch** - [DEPRECATED] Whole component is now deprecated, you can use the new Tabs `switch` variant instead. **Tabs** - New attribute `size` has been added. - New attribute `variant` has been added. ### Bug fixes **AI Agents** - LLM files now contain all the relevant Storybook pages. **Code** - Highlighter instance is now correctly cleaned on unmount. **Combobox** - Prevent content close on scrollbar click. - Active option is now automatically scrolled into view. **FileUpload** - Use correct role on file item error. **Range** - Prevent thumb focus when value is changed by external sources. **Select** - Value text and placeholder are now ellipse by default. ## v19.3.0 ### New components **Toaster** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/toaster) ### Design updates ODS theme design tokens have been reworked to be more semantic. It is now easier to understand how each token should be used. Each component have been updated accordingly and are now more normalized design-wise. Each component now also expose custom tokens that may be used to override rendering on a component-level. All those changes are the first major step towards a complete reworked theme that aims to provide more consistency, easier customization and understanding. [DEPRECATED] Previous design tokens should be replaced by the corresponding theme tokens. **Accordion** - Border color has been changed and is now the same for every component states. **Combobox** - `invalid` overlay now uses the critical color. **File Upload** - A more compact version is now available (using `variant` attribute). - Existing layout has been updated to be more compact. **Message** - Light messages now have a colored border. **Range** - Track color now is the same as other track elements. - Cursor has been changed to default (as in native). - Thumb background color change on hover/focus/drag has been removed. **Select** - `invalid` overlay now uses the critical color. - Groups are now separated by a border. **Skeleton** - Default background color is now slightly darker. **Table** - Default `min-width` has been removed on mobile view. **Text** - Font size now uses `rem` instead of `px`. This will only impact app where the root element `font-size` is not `16px`. **Toggle** - Hover effect on `off` label has been removed. ### Feature updates **Code** - New attribute `highlighter` has been added. - Documentation has been updated with how to setup a custom highlighter. **Datepicker** - `value` now also accepts `null` as a value. - `DatepickerValueChangeDetail` `value` and `valueAsString` now may be `null`. **Divider** - [DEPRECATED] Color attribute will now always be primary, if you need another color, prefer overriding it using css. **File Upload** - New attribute `variant` has been added. **Text** - New attribute `disabled` has been added. - New preset `small` has been added. ### Bug fixes **Combobox** - Clicking another combobox while focused on another one, now correctly closes the first one. - Controlled value changed externally is now correctly reflected. **Datepicker** - Clear when controlled now works as expected. **Link** - Disabled links do not have an underline animation when hovered. **Tabs** - `tablist` role now correctly contains only valid children. - Now doesn't automatically scroll to the component on render. ### Documentation improvements A new tool has been added to the documentation, the `Theme Generator`. This allows users to experiment with the ODS tokens directly in the Storybook. You can preview how each design tokens will impact the components, generate your own color palettes and export/import your custom theme. ODS documentation is now available as LLM files to help AI tools to better understand our library and its usage. - Add a theme selector on the top left menu. - Implement dark mode documentation. - New section `AI Agents` added to the documentation. - Design Tokens have been updated and completed with color palettes. - All technical pages have been updated with components custom CSS variables. - Icon `All` page search control now accepts special character. - Update FAQ. ## v19.2.1 ### Feature updates **Combobox** - New attribute `customFilter` has been added. ### Bug fixes **Button** - Use correct border radius for `sm` size. **Input** - Normalize border style on hover & focus. **Password** - Normalize border style on hover & focus. **Tabs** - Container bottom border takes the whole width. ### Documentation improvements - Update FAQ. - Remove ToC on Changelog page. ### Miscellaneous **Tabs** - Add a console warning when no `defaultValue` or `value` are set. ## v19.2.0 ### New components **Meter** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/meter) **TreeView** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/tree-view) ### Font changes Font files are now accessible as actual files instead of base64 conversion. This will reduce the size of the ODS style bundle and allow browser resource loading parallelization. Thanks to [Ennoriel](https://github.com/ennoriel) for the contribution. **@ovhcloud/ods-react** - Now exposes a css reset file (using `import '@ovhcloud/ods-react/normalize-css';`) **@ovhcloud/ods-themes** - Now exposes css without fonts (using `import '@ovhcloud/ods-themes/default/css';`) - Now exposes font-faces separately (using `import '@ovhcloud/ods-themes/default/fonts';`) ### Feature updates **@ovhcloud/ods-themes** - Now exposes design tokens as JSON (using `import '@ovhcloud/ods-themes/default/tokens';`) **File Upload** - Improve i18n default translations. **Icon** - Add 40 new icons. **Password** - Improve i18n default translations. **Phone Number** - Improve i18n default translations. **Popover** - New attribute `autoFocus` has been added. - New attribute `gutter` has been added. - New attribute `sameWidth` has been added. - New attribute `onPositionChange` has been added. - New attribute `triggerId` has been added. **Range** - New attribute `displayBounds` has been added. - New attribute `displayTooltip` has been added. - Ticks now accepts objects with custom labels. - Range component size is now correctly computed, it will fit better in the page rendering flow. **Tabs** - New attribute `withArrows` has been added. **Timepicker** - Improve i18n default translations. ### Bug fixes **Combobox** - Has been rewritten internally, but the usage stays the same. - Fix selection behavior issues. - Add style on selected element. - Fix missing style on group separator. **Input** - Clearable now always appears correctly when controlled. **Quantity** - Fix default value stuck when used inside a FormField. **Range** - Update ticks position computation to match thumb size. ### Documentation improvements A new tool has been added to the documentation, the `Code sandbox`. This allows users to experiment with the ODS library directly in the Storybook. You can also share your sandbox code with others. This is especially useful when trying to reproduce some issue you encounter, but in a smaller dedicated context. - New section `Tools` added to the documentation. - A sandbox shortcut has been added to every examples. - New dedicated page about Tailwind integration. - Add badges when relevant near navigation menu items. - Update "Get Started" with fonts changes. - Update "Apply ODS Style" with CSS reset. - Update GitHub repository contributing page. - Update FAQ with contribution information. - Multiple typo fixes. ### ODS dependencies upgrade - ArkUI bumps from `5.12.0` to `5.25.1`. ## v19.1.0 ### Accessibility improvements #### a11y This version focuses on improving the accessibility for each component. We've implemented all the internal requirements on each component, validated using [axe-core](https://github.com/dequelabs/axe-core) and [lighthouse](https://www.npmjs.com/package/lighthouse). Though, ensuring accessibility for your context does require you to use the right `aria`/`role`/... attribute at the right place. To help you with that, we've added: - a [guide about accessibility](https://ovh.github.io/design-system/v20.0.0/guides/accessibility) best practices. - a dedicated `Accessibility` section on each component `Documentation` page. #### i18n Some components provide internal features that need an explicit context. For example the clear button on the `Input` which require an `aria-label` describing that the button will clear the value. We do provide default values for each supported locales to ensure that integrating ODS component as is will already convey the minimal information to impaired users. You can customize those value further with your own translations. See the related [Internationalization guide](https://ovh.github.io/design-system/v20.0.0/guides/internationalization) for more information. ### Design updates > Some design changes may impact your layouts. **Breadcrumb** - `fontSize` is now inherited and no more fixed to `0.875rem`. **Checkbox** - Added minimal vertical spacing on group. - Checkbox size is now `16px`. **Design Tokens** - New color variants `-025` and `-075` have been added. **Progress Bar** - Now defaults to full width. **Tag** - `md` height is now `24px` by default. ### Feature updates **All components** - A new attribute `data-ods` has been added to each exposed component, allowing them to be identified in the DOM. **Breadcrumb** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Button** - Improve button contrast for accessibility. **Clipboard** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Combobox** - Added `customRendererData` on combobox items. - New attribute `i18n` has been added. - New attribute `locale` has been added. **Datepicker** - New attribute `i18n` has been added. - New attribute `locale` has been added. **File Upload** - New attribute `i18n` has been added on `FileUploadItem`. - New attribute `locale` has been added. **Input** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Message** - Improve color contrast for accessibility. - New attribute `i18n` has been added. - New attribute `locale` has been added. **Modal** - New attribute `i18n` has been added. - New attribute `initialFocusedElement` has been added. - New attribute `locale` has been added. **Password** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Phone Number** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Quantity** - Increment and decrement buttons are no longer focusable, allowing keyboard navigation to focus solely on the input field for consistent vocalization. **Select** - Items `customData` now accept an optional generic type. **Timepicker** - New attribute `i18n` has been added. - New attribute `locale` has been added. **Toggle** - New component `ToggleControl` has been added. - New component `ToggleLabel` has been added. - [DEPRECATED] Using `` alone will still works as expected, though we advise to move to composition using `ToggleControl` and `ToggleLabel`. ### Bug fixes **Combobox** - Click on `FormField` label now behave like native. **File Upload** - Click on `FormField` label now behave like native. **Phone Number** - Following country codes `bq`, `gf`, `gp`, `io`, `pm`, `re`, `sj`, `sx` have been added. - Click on `FormField` label now focus input instead of country select. **Popover** - Positioning is now correct if a custom ID is set on the trigger element. - The trigger is now focusable by default. **Tooltip** - Positioning is now correct if a custom ID is set on the trigger element. - The trigger is now focusable by default. ### Documentation improvements - New `Accessibility` page has been added in the `Guides` section. - New section `Accessibility` has been added on every component `Documentation` page with best practices and examples. - A `react-router` `Link` example has been added. - Github links on component `Documentation` pages have been fixed. - Atomic design link on component `Documentation` pages have been removed, as it was not relevant. - New link to previous major version doc has been added on component `Documentation` pages. - A link to form guide has been added on each `FormField` examples. - FAQ has been updated. ### Miscellaneous - Fix Windows issues when cloning the repository and running the Storybook scripts. ## v19.0.1 ### Feature updates **Pagination** - Add `onPageSizeChange` handler. - Add `pageSize` to `PaginationPageChangeDetail` detail object. ## v19.0.0 Version 19 of ODS is not the direct follow-up of previous versions, it is a new library built 100% on top of [React](https://react.dev). ### Project changes Previous versions were providing a React version of each components too, but there were in fact a wrapping of the Web Component. Thus it was designed with the constraints related to Web Component (no virtual DOM, relying on DOM selector, ...). With this new version we got rid of those constraints, which gave us some benefits like: - component composition. - easier style customization. - easier React integration (no more `ref` needed, nor literal templates). Although, we tried to stay as close as possible to previous version behavior, the way you integrate ODS in your React app should be rethought, to ensure you use components as real React elements and not wrapped Web Components anymore. To check how to start with this new version, please follow the [Get Started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) documentation. Here is a non-exhaustive list of the major changes: - rework of all components as React elements. - tree-shaking. - less restriction on components customization and usage. - reduced CSS size by moving to variable fonts. - no more Ods prefix on all components/constants. - no more web-components nor Vue wrappers provided. - updated icons (now with default padding embed). - updated various component designs (datepicker, message, modal, spinner, ...). - new design tokens. - updated documentation. - card default color changed. - ... ## What's new in v18 --- title: "What's new in v18" slug: ovhcloud-design-system-upgrade-what-s-new-v18 category: generic type: overview version: 20.0.0 tokens: 4759 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v18.txt --- # What's new in v18 *Release notes of v18. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v18.6.4 ### Bug fixes **Clipboard** - Container now inherent parent width. **Code** - Now correctly render large text with fixed height. **Combobox** - Clicking an item now correctly select it on Safari. **File Upload** - Allow same file to be uploaded again after cancellation. **Phone Number** - Add following country codes: `bq`, `gf`, `gp`, `io`, `pm`, `re`, `sj`, `sx`. ## v18.6.3 ### Bug fixes **Pagination** - Now handles very large number of pages correctly. ## v18.6.2 ### Bug fixes **Combobox** - Ensure "Add new entry" option is visible when no items are present. - Hide "Add new entry" option when input is cleared. - Prevent duplicates when using value or default value in allow multiple mode. ## v18.6.1 ### Bug fixes **Clipboard** - Remove spacing between actions and copy button. **Input** - Add spacing between value and actions. ## v18.6.0 ### New components **Combobox** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/combobox) ### Feature updates **Badge** - New feature to allow icon to be aligned either on left or right side. - New attribute `iconAlignment` has been added. - New constant `ODS_BADGE_ICON_ALIGNMENT` has been added. **Clipboard** - New attribute `isMasked` has been added. **Icon** - `alt` attribute has been removed. This optional attribute was in fact doing nothing at all, it can safely be kept if you were using it, but you should remove it and follow the [accessibility best practices](https://ovh.github.io/design-system/v20.0.0/components/icon) instead. ### Bug fixes **Button** - Ensure button height stays the same for all variants. - Fix `sm` height on all variants. **Modal** - Backdrop is no longer removed when pressing `Escape` on non-dismissible modal. ### Documentation improvements - Add new dedicated page about design tokens under the `Design and Style` section. - Update the accessibility section of the [Icon](https://ovh.github.io/design-system/v20.0.0/components/icon) component, with best practices and examples. ## v18.5.3 ### Feature updates **Select** - New attribute `strategy` added that let you manage different positioning, default strategy is `absolute`, you can change to `fixed` when in a fixed context (like in an ods-modal for example). - New constants `ODS_SELECT_STRATEGY` and `ODS_SELECT_STRATEGIES` are now available. ## v18.5.2 ### Feature updates **Code** - Add tooltip message on copy button. - New attribute `labelCopy` added. - New attribute `labelCopySuccess` added. **Design Tokens** - Add new design token `--ods-form-element-input-height`. Useful when trying to use any input (ods-input, ods-datepicker, ods-select, ...) default height. **Modal** - New part `dialog-content` added that let you customize the content of the modal (ie, between header and actions). **Phone Number** - Pressing a letter while focusing the country selector will now move to the first matching country. ### Bug fixes **Code** - Spacing will now be correctly preserved. **Input** - Fix disabled style. **Phone Number** - Countries are now correctly sorted when locale get changed. **Spinner** - Spinner now use inline svg instead of svg file. This should remove some of the `eval` warnings on build. **Tabs** - Tabs bottom border now takes the whole width on horizontal overflow context. ### Documentation improvements - Add more documentation about managing overlays on a modal. ## v18.5.1 ### Feature updates **Clipboard** - New `ariaLabel` prop has been added. - New `ariaLabelledby` prop has been added. - New `name` prop has been added. **Datepicker** - New attribute `strategy` added that let you manage different positioning, default strategy is `absolute`, you can change to `fixed` when in a fixed context (like in an ods-modal for example). - New constants `ODS_DATEPICKER_STRATEGY` and `ODS_DATEPICKER_STRATEGIES` are now available. **Medium** - Now expose an `image` part. **Password** - New `maxlength` prop has been added. - New `minlength` prop has been added. **Textarea** - New `maxlength` prop has been added. - New `minlength` prop has been added. ### Bug fixes **Accordion** - Clickable elements in the slots now behaves as expected when using the React component. **Checkbox** - Fix focus style on error state. **Code** - Copy button is now correctly positioned on the right side. **Datepicker** - Clear button is now correctly displayed when `isClearable` is set, even for invalid value. **Input** - Clear button is now correctly displayed when `isClearable` is set, even for invalid value. **Password** - Clear button is now correctly displayed when `isClearable` is set, even for invalid value. **Phone Number** - Reset now correctly reset the flag, when `countries` is set. - Clear button is now correctly displayed when `isClearable` is set, even for invalid value. **Popover** - `triggerId` & `shadowDomTriggerId` now accepts id with special character (ex: `?`, `:`, ...). **Radio** - Fix focus style on error state. **Tooltip** - `triggerId` & `shadowDomTriggerId` now accepts id with special character (ex: `?`, `:`, ...). ### Documentation improvements - Headings link url are now static, which means you can safely bookmark / share them. - Fix the `Open canvas in new tab` action in the toolbar on Demo pages. - Accessibility tabs has been removed from Demo pages, as it was giving wrong information (as demo are custom made and not valid use case). ## v18.5.0 ### New components **Drawer** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/drawer) ### Feature updates **Accordion** - Update internal logic to use the native behavior of `details` / `summary` tags. - Interactive elements can now be used inside the accordion without toggling it. - New methods `close`, `open` and `toggle` have been added. - Add some documentation about usage with React state. **Link** - Link will now display an ellipsis by default. - New part `label` has been added to allow label customization. **Modal** - Update default width and height. - Update dimensions on mobile-size screen. - `z-index` has been updated to use ODS overlay z indexes ordering. **Range** - Range can now display ticks. - New attribute `ticks` has been added. - Thumb hitbox has been improved. **Select** - `z-index` has been updated to use ODS overlay z indexes ordering. **Tooltip** - Tooltip now stays open for a short time on trigger leave, which allows user to move over it and keep it open (and for example select its content). ### Documentation improvements - Add new guide about using components events. - Add new guide about using components methods. - Update Properties array in the technical page to more clearly display which props are required. - Update form-field caption examples. - Fix FAQ broken link. ## v18.4.1 ### Feature updates **Tabs** - Apply new style on unselected tab text. - Apply new hovering style. **Toggle** - Expose new method `toggle`. ### Bug fixes **Toggle** - Fix toggle style when selected and in an error state. ### Miscellaneous We did integrate [react-testing-library](https://testing-library.com/docs/react-testing-library/intro) to our React wrapper test suites, so that we can replicate more easily issues integrators may encounter. ## v18.4.0 ### Changes on form elements This version is focused on implementing [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) to our form elements. This allows you to setup a fully working form without the need of any external library or custom validation code, as everything behave as a native form. Though you can of course use a lib on top of that if you want to. We've validated forms using native code (vanilla and React), [Formik](https://formik.org) and [React Hook Form](https://react-hook-form.com) on our tests and playgrounds. The changes on each component are massive, but we did focus on ensuring bumping to this version would be transparent for current ODS users. We won't go through an exhaustive list of changes, here are the most important ones for each form element: - Consistent behavior regarding blur and error state. - Consistent event triggering (check the guide about event lifecycle). - New event `odsInvalid` triggered when component internal validity change. - New methods available: `checkValidity`, `getValidationMessage`, `getValidity`, `reportValidity`, `willValidate`. - New interface `OdsFormElement` available with this methods. - Tons of unit & e2e tests have been added. ### Feature updates **Checkbox** - New `hasError` prop has been added. - New style when on error. **Clipboard** - Now expose an `input` part. - Input now inherit component length. **Datepicker** - `defaultValue` now accepts Date or string. - `max` now accepts Date or string. - `min` now accepts Date or string. - Added a new helper method `formatDate`. - Added a new helper method `parseDate`. **Input** - New input type `search` has been added. **Phone Number** - New `customValidityMessage` prop has been added. **Radio** - New `hasError` prop has been added. - New style when on error. **Range** - Now triggers an odsChange on thumb release, not on every move. **Select** - Add a new method `updateCustomRenderer` if you need to update the custom template used. **Switch** - Events are now send from `ods-switch` and not from `ods-switch-item` anymore. You may need to move your handlers if you were defining some on items. - New `hasError` prop to enforce error state. - Focus style has been updated. - New style when on error. **Toggle** - New `hasError` prop to enforce error state. - New style when on error. ### Documentation improvements - New Guide section, with a first one about form management. - Added new control to visualize ValidityState on each form elements Demo page. - Storybook update popup has been disabled. ## v18.3.1 ### Feature updates **Icon** - New icon "columns" has been added. **Link** - Update hover & visited color to a lighter one. **Select** - Update hover style to differentiate it from selected option. **Text** - `caption` preset does not use a `caption` tag anymore, as these is tight to table usage only. - New examples have been added regarding `caption` and `figcaption` usage. ### Bug fixes **Breadcrumb** - Separator is now always correctly aligned, regardless of the number of items. **Modal** - Dialog content height is now correct on Safari ## v18.3.0 ### Feature updates **All form elements** - Apply new style on readonly state. **Breadcrumb** - A new part `last` is now available to customize the last item (which differ from other link items). **Input** - You can now link a native `datalist` to an `ods-input` using the `list` attribute and the `list` slot. A full example is available in the [Technical information](https://ovh.github.io/design-system/v20.0.0/components/input) page. - New attribute `list` has been added. - New slot `list` is now available. **Message** - Message can now be rendered without the close button, as a static message. - New attribute `isDismissible` has been added. **Popover** - New attribute `strategy` added that let you manage different positioning, default strategy is `absolute`, you can change to `fixed` when in a fixed context (like in an ods-modal for example). - New constants `ODS_POPOVER_STRATEGY` and `ODS_POPOVER_STRATEGIES` are now available. **Tooltip** - New attribute `strategy` added that let you manage different positioning, default strategy is `absolute`, you can change to `fixed` when in a fixed context (like in an ods-modal for example). - New constants `ODS_TOOLTIP_STRATEGY` and `ODS_TOOLTIP_STRATEGIES` are now available. ### Bug fixes **All form elements** - Pressing `Enter` on an action button (like the clear button) does not trigger a form submit anymore. **Badge** - Now use the expected border-radius style. **Breadcrumb** - Last attribute is now correctly reset on items changes. **Modal** - `odsClose` event is no more emitted on component unmount. If you were relying on that, please reach out to us so we can find a better approach. - Content is now wrapped by a div to prevent flex weird rendering. - Modal height can now be customized using the `dialog` part. **Range** - Apply correct style to hovered thumb on error state. **Select** - Options are now correctly updated on change. - Disable state is now correctly updated on change. ### Internal changes We now use an `ods-button` instead of a native one for all our internal actions. Ex: input clear, message close, modal close, ... This shouldn't have any impacts. ## v18.2.0 ### Feature updates **Button** - New color style `neutral` and new size `xs`are now available. - New color `neutral` added to `ODS_BUTTON_COLOR`. - New size `xs` added to `ODS_BUTTON_SIZE`. **Spinner** - New size `xs` is now available. - New size `xs` added to `ODS_SPINNER_SIZE`. ### Bug fixes **Modal** - No `odsClose` event emitted anymore on element DOM disconnection if modal was already closed. **Password / Phone Number / Quantity / Timepicker** - Setting a `width: 100%` to the ods element now correctly apply it to the underneath elements. ## v18.1.0 ### Documentation improvements Storybook has been partially rewritten, so you may notice a few changes: - some style has been updated - broken links have been fixed - components documentation has been migrated from `typedoc` to `custom-element-manifest` ### Feature updates **Button** - New feature to allow icon to be aligned either on left or right side. - New attribute `iconAlignment` has been added. - New constant `ODS_BUTTON_ICON_ALIGNMENT` has been added. **Icon** - New icons `bill` and `box` have been added. - `globe` icon has been updated. **Link** - New feature to allow icon to be aligned either on left or right side. - New attribute `iconAlignment` has been added. - New constant `ODS_LINK_ICON_ALIGNMENT` has been added. **Select** - Apply new style to multi-select counter. **Table** - Update header color to neutral-050. **Text** - No more default margin on any presets. ### Bug fixes **All** - Components now correctly inherits font-family. **Modal** - Prevent undefined element when using with react testing library. **Phone Number** - Locale fallback has been moved from french to english (fallback that is applied if no locale or a wrong locale is set and the locale of your browser is not managed). ## v18.0.0 As it is a major version, you'll have to follow the [migration guide 17.x to 18.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-17-to-18) ### Project changes From the beginning of the project to the latest v17 version, our vision of the project has greatly evolved. Thanks to real-user feedbacks, a better understanding of our use cases and how ODS fits in the OVHCloud ecosystem. With this new version we've tried to tackle most of the known issues to offer a better end-user experience: - components are now behaving more like native html elements - components are now easier to use and to customize - no more invasive `console.log`, we only print meaningful warnings when needed - enum values can now be used directly instead of importing it - events are now normalized for all components - release process will be shorter On top of that, the v18 does bring new features: - new components: file-upload and timepicker - latest design applied on all components - now sync with figma changes - a new set of icons - a reworked documentation To achieve all this, we had to rewrite almost the whole library. This is a major version change with tons of breaking changes. But this aims to be the last time. To help you moving from a previous version to the v18, we've added a dedicated page on each component presenting the changes and some migration examples. ### ODS libraries The following libs have been removed: - @ovhcloud/ods-cdk - @ovhcloud/ods-common-core - @ovhcloud/ods-common-stencil - @ovhcloud/ods-common-testing - @ovhcloud/ods-common-theming - @ovhcloud/ods-theme-blue-jeans There is now only two library published that you should include: - `@ovhcloud/ods-components` that contain all web-components, react and vue wrappers and the sass mixins - `@ovhcloud/ods-themes` that contain the design tokens and the assets (fonts and icons) The CDK has been removed and we do not plan on publishing it again. If you were using part of it, please reach out to us so that we can get more information about your usage. All common libs have been and we do not plan on publishing them again. If you were using part of them, please reach out to us so that we can get more information about your usage. The `blue-jeans` theme has been replaced by the default theme of `@ovhcloud/ods-themes`. ### ODS dependencies upgrade The new version comes with the following upgrade on major library: - Stencil bumps from `4.12.0` to `4.16.0` - `node-sass` is not supported anymore and was replaced by `sass` (`1.71.0`) - Typescript bumps from `4.7.4` to `5.3.3` - Storybook bumps from `6.4.19` to `8.0.4` ### Style customization Although the ODS component comes with the expected design, you can now apply your own style directly on some part of the web-component shadow DOM, thanks to the [part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). For example, you can add style on the native `input` element of an `ods-input` component through the following code: ```html ``` Most of the component exposes one or more part like this, you can find more information on each component documentation page. ### Sass helpers In addition to the easier customization, we're also exposing the "basic" style of some core component as Sass mixins that you can use to apply on a native element to get the same ODS rendering. For example, if you need to make an anchor tag looks like an `ods-link`: ```css @import '@ovhcloud/ods-components/style'; .my-link { @include ods-link(); @include ods-link-color('primary'); } ``` ```html ... ``` This can be useful when you can't manage some part of the DOM as you want, for example using a library that will always render an anchor and that provide no custom templating. Be careful though, this does only provide basic style, not all the feature of an ODS component, so we do recommend to use the web-component by default. ### New components **File Upload** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/file-upload) **Timepicker** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/timepicker) ### Component changes Please check the [migration guide](https://ovh.github.io/design-system/v20.0.0/guides/migration-17-to-18) regarding all the component changes. ## What's new in v17 --- title: "What's new in v17" slug: ovhcloud-design-system-upgrade-what-s-new-v17 category: generic type: overview version: 20.0.0 tokens: 1593 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v17.txt --- # What's new in v17 *Release notes of v17. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v17.2.2 This update brings a few bug fixes across components, ensuring a smoother and more accessible user experience. ### Bug fixes **Button** - Fix the issue where the button was still clickable on the border while disabled. ### Feature updates **Radio-button** - Add 'XS' size to radio button. ## v17.2.1 This update brings a few bug fixes across components, ensuring a smoother and more accessible user experience. ### Bug fixes **Clipboard** - A white background is now properly displayed on the `Popover`. **Menu** - A minimal height is now forced in the `Menu` component, giving proper styling on the bottom margin. ## v17.2.0 This update introduces our new `Table` component, enhances various features and improves documentation. It also brings numerous bug fixes across components, ensuring a smoother and more accessible user experience. ### New component **Table** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/table) ### Documentation improvements **Form Field** - Added an accessibility label. - Updated Storybook Usage Guidelines. ### Feature updates **Clipboard** - `Tooltip` now features a `3 seconds` closing delay. - `Tooltip` won't be displayed if `success-message` OR `error-message` is not defined. **Datepicker** - `Datepicker` days are now displayed with 2 letters. **Pagination** - New attribute `defaultCurrentPage` has been added. - New method `getCurrentPage()` has been added. - Old attribute `current` has been removed. - Navigation will be hidden if `totalItems` is lower than `itemPerPage` ### Bug fixes **Breadcrumb** **Link** - Multiple active states issue on Safari browsers has been fixed. **Datepicker** - Error color on `Datepicker`'s border has been fixed. **Input** - Clearing the `Input` now properly focuses it afterwards. **Modal** - Overlaying elements can now overflow from the `Modal`. - Pressing the `ESCAPE` key when a `Select` is open inside a `Modal` no longer displays an unwanted backdrop. - Width value has been fixed on breakpoint. **Popover** - Overlaying elements can now overflow from the `Popover`. **Textarea** - `Textarea` style has been fixed to match the `Input`. **Tile** - Checked `Tile` styling has been fixed on Safari. **Search Bar** - `odsSearchSubmit` event is now properly triggered on `KEY_DOWN` input. ## v17.1.0 As we're working towards a massive uniformization of all ODS form elements (events, nav behavior, required state, validity state, ...), the amount of changes is too important to be released immediately. This release brings the expected form-association of form elements, so that they act as native one for formData submit and reset. It also fixes the missing types of event (`odsBlur`, `odsFocus`, `odsValueChange`). ### Documentation improvements Documentation usage guidelines have been completed with almost all components properties and slots: - tons of new components examples - dark background when `contrasted` prop is set - shortcuts have been disabled due to issue with some input preview ### Feature update **Pagination** - A new `defaultItemsPerPage` has been added, which allows to define the initial value of `itemsPerPage` on first render ### Bug fixes **Button / Checkbox / Radio / Range / Tile** - Prevent click event on click when disabled on Chromium & Safari. **Modal** - Modal is now correctly cleaned up on disconnect **Tile** - Ensure position stays consistent regarding end/start slot emptiness ### Miscellaneous - Upgrade to StencilJS 4.12 ## v17.0.3 ### Bug fixes **Input** * Icon size are now displayed at the expected size **Quantity** * Native arrow are now hidden on Safari **Radio / Radio group** * Remove logger issue on documentation example page **Toggle** * Toggle now shrink correctly when slot content are very large **Tile** * Tile borders are now correctly rounded on Safari ## v17.0.2 ### Bug fixes **Modal** * Added `enter` and `space` keys binding on the close button + cancel button on Storybook * Fixed display problems within the modal that could lead to some elements getting shrunk * Scroll is now prevented when a modal is open ## v17.0.1 ### Bug fixes **Pagination** * Next & previous buttons have been fixed on Chrome & Safari where they could allow the user to go out of bound. **Radio-Button** * Smaller text has been fixed and is now aligning vertically as well. **Fonts** * Fonts have been fixed to display the correct font on Safari. ## v17.0.0 As it is a major version, you'll have to follow the [migration guide 16.x to 17.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-16-to-17) ### Project changes Main focus on this version has been on simplifying ODS integration in existing projects (React, Vue, JS, ...). We now only publish one `ods-components` library that embed all the ODS components. What this means for your code: * `ods-component-xxx` are no longer published and should be removed * only one dependency to add to your `package.json` ```text "ods-components": "17.0.0" ``` ODS components can then be either imported using lazy-loading (the code of each component is loaded on demand) or as a module (the code of the component is tree-shaked by your own bundling system). For more details on how to import ODS components, see: * the updated [Get Started documentation](https://ovh.github.io/design-system/v20.0.0/guides/get-started) * the 16.x to 17.x [Migration guide](https://ovh.github.io/design-system/v20.0.0/guides/migration-16-to-17) ### Documentation improvements We went through each component to update: * the Demo controls to be more relevant * the Usage Guidelines, with more examples and the missing properties * with React example when relevant (ex: `datagrid` reactFormatter with React 18 or `tabs` with React Router) ### Component changes **Pagination** * Add `odsItemPerPageChange` when the item per page select change ### Bug fixes **Datagrid** * Overflowing elements can now correctly be displayed (see updated documentation) **Menu** * Ellipsis is now correctly displayed on Safari **Modal** * Inner element with overlay are now correctly displayed **Tabs** * Fix hover rendering ## What's new in v16 --- title: "What's new in v16" slug: ovhcloud-design-system-upgrade-what-s-new-v16 category: generic type: overview version: 20.0.0 tokens: 2294 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v16.txt --- # What's new in v16 *Release notes of v16. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v16.6.0 ### Feature update **Breadcrumb** * Add attributes on `breadcrumItem` : `disabled`, `rel`, `referrerpolicy`, `target` * Add event on `breadcrumItem` : `odsBreadcrumbItemClick` * Update `OdsHTMLAnchorElementRel` type **Chip** * Added `odsChipRemoval` event * If `OsdsChip` is removable and is clicked, it will emit event `odsChipRemoval` * If `OsdsChip` is removable, focused on and key Enter is pressed, it will emit event `odsChipRemoval` ### Bug fixes **Button** * Fix position of end slot when start slot is empty in `OsdsButton` **Datagrid** * If the `OsdsDatagrid` contains an overflowing on-interaction element (such as `OsdsMenu`, `OsdsTooltip`, `OsdsSelect` or `OsdsPopover`), the element is either being displayed at the top left corner of the `OsdsDatagrid` (native) or beneath the element, making it unvisible (React). This fix intends to correct this problem in both environments. **Pagination** * Add `itemPerPage` in payload event `odsChange` * Watch `totalPages` & update it **Phone Number** * Fix shadow of flag icon in the select that was cut behind overflow **Components** * Some components were missing from package.json of components: `medium`, `range`, `toggle` ## v16.5.0 ### Feature update **Documentation** * Multiple updates to clarify documentation. (Welcome page, Get started, Design tokens, Code, Contributing & libraries) * Removing Starter documentation, as it is deprecated for now. ### Bug fixes **Datagrid** * `OsdsDatagrid` now emits the event `onBottomScroll`. * `OsdsDatagrid` now supports React Formatters. * Row change has been fixed. **Modal** * `OsdsModal` is now using a `HTMLDialogElement`, **Phone Number** * Flags have been fixed to be displayed with proper width & height. **Select** * Enhanced React support for `OsdsSelect`. **Storybook** * Storybook errors with displaying `OsdsPhoneNumber` & `OsdsSearchBar` inputs has been fixed. ## v16.4.0 ### New component **Datagrid** * See Documentation using version selector ### Bug fixes **Phone number** * Now consistently triggers `odsValueChange` event on type. **Storybook** * The release list now correctly displays the name of the latest version. ### Feature update **Component Generator** * Component Generator has been upgraded to align with the new architecture (introduced in version 16.0.0). ## v16.3.2 ### New component **Medium** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/medium) ### Bug fixes **Phone number** * Emit event when the value is valid **Accordion** * Can't open when the component is disabled **Quantity** * Change the value onblur to be valid with step **Modal** * Add event open & close (odsModalOpen, odsModalClose) ## v16.3.1 ### Bug fixes **Datepicker** * The siblings months days are now updated after the datepicker was updated **Select** * Keyboard navigation correction ## v16.3.0 ### Component changes **Button** * Each variant now display correctly when using circle button > **Breaking change** * Circle button may render differently regarding the variant you're using **Datepicker** * Component now close itself when value is selected * You can now hide adjacent month days with the attributes `showSiblingsMonthDays` **Flag** * Component has been refactored internally, but this should not have any impacts **Icon** * Component has been refactored internally, but this should not have any impacts ### Bug fixes **Menu** * Now correctly work when used with React **Select** * On Safari the component is displayed correctly when using flex **Textarea** * On Safari the component is displayed correctly when using flex **Tile** * On Safari the component is displayed correctly when using flex ### Project changes * The whole project is now built using Stenciljs v4.7 > **Breaking change** * We don't generate the bundle `custom-elements-bundle` anymore ## v16.2.1 ### Component changes **Datepicker** * New attribute `locale` to manage internationalization, accepted locales are for now: - French - English - German - Spanish - Italian - Polish - Portuguese - Dutch **Text** * Component has been refactored internally, but this should not have any impacts ### Bug fixes **Datepicker** * Add missing constants and types exports **Modal** * Is now correctly destroyed on page change **Popover** * Now correctly work when used with React **Select** * Selected value is now correctly updated on cnange (ex: translation change) ## v16.2.0 ### New component **Datepicker** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/datepicker) ### Component changes **Clipboard** * Added tooltip confirmation message on paste ### Bug fixes **Textarea** * Correctly emit `odsValueChange` event on value change. ### Documentation changes * Improve typedoc documentation ## v16.1.1 ### Documentation fixes * Component specification pages now displays correct information * Tile sandbox now uses correct list of commands ## v16.1.0 ### New component **Phone Number** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/phone-number) ### Component changes **Input** * New attribute `prefixValue` that allow to display a fixed prefix in front of the input value. **Progress Bar** > **Breaking change** * `max` and `value` attributes are now `number` and won't accept `string` anymore. ### Bug fixes **Code** * Contrasted version have now the right color. ### Project changes * The whole project is now built using node 18. ## v16.0.1 Fixes CI build issues when deploying Storybook. ## v16.0.0 As it is a major version, you'll have to follow the [migration guide 15.x to 16.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-15-to-16) > We're aware that not all the documentation is up-to-date with the latest technical changes. We're currently working on improving the storybook but didn't want to delay the release much more. If you have any issue migrating, reach us directly and we'll help you. ### Project changes This version embed the whole new project architecture (initiated with the v15). We now have seperations between: * `cdk` (@ovhcloud/ods-cdk) which provides public non component related utilities. * `common` libs (@ovhcloud/ods-common-\[core|stencil|testing|theming]) which provides internal helpers. * `components` (@ovhcloud/ods-components or @ovhcloud/ods-component-``) which provide the agnostic components and their React, Vue wrapped versions. * `examples` (@ovhcloud/ods-starter-\[react|react-vite|vue-vite]) which contains application examples that use some ODS components. * `shared-dependencies` to share common dependencies internally accross projects. * `storybook` (@ovhcloud/ods-storybook) which tends to centralize all the ODS documentation content. * `themes` (@ovhcloud/ods-theme-blue-jeans) which provides all existing themes that can be applied to ODS. ### Component changes **All Components** * `@ovhcloud/ods-stencil` package does not exists anymore. * Components are now accessible by adding either `@ovhcloud/ods-component-` or `@ovhcloud/ods-components` dependency. * All `@ovhcloud/ods-stencil-` libs have been replaced by `@ovhcloud/ods-component-`. * All `@ovhcloud/ods-stencil--react` libs have been replaced by `@ovhcloud/ods-component--react`. * All `@ovhcloud/ods-stencil--vue` libs have been replaced by `@ovhcloud/ods-component-- vue`. * Constants/Enums have been renamed to follow new naming convention: * All constants are now in UPPER\_SNAKE\_CASE. * All objects are now in singular form. * All lists are now in plural form. Ex: `OdsSpinnerSize` is now `ODS_SPINNER_SIZE`. `OdsSpinnerSizeList` is now `ODS_SPINNER_SIZES`. `OdsSpinnerSizeUnion` has been removed. * Exported types follow also the same naming convention, thus most of them are now in singular form. Ex: `OdsSpinnerAttributes` is now `OdsSpinnerAttribute`. * A lot of empty types who were exported previously have been removed. Ex: `OdsSpinnerEvents` have been removed, as the component does not handle any events. `OdsSpinnerMethods` have been removed, as the component does not expose any methods. ### New component **Clipboard** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/clipboard) **Menu** See documentation using version selector **Modal** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/modal) **Search Bar** See documentation using version selector ### Features changes **Button** * Add a new attribute `textAlign` which allows to choose the button text alignement between `center`, `end` and `start`. ### Bug fixes **Button** * Main slot is now correctly aligned vertically (visible when using icon). **Flag** * Flags are now correctly displayed in the documentation. **Link** * Outline is now correctly updated on viewport change. ## What's new in v15 --- title: "What's new in v15" slug: ovhcloud-design-system-upgrade-what-s-new-v15 category: generic type: overview version: 20.0.0 tokens: 880 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v15.txt --- # What's new in v15 *Release notes of v15. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v15.0.1 * Fix new packages release process. * Update documentation. ## v15.0.0 As it is a major version, you have to do the [migration guide 14.x to 15.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-14-to-15) ### Project changes This version is the first step towards the new ODS internal architecture. The goal of this refactoring is to simplify and improve the whole project to: * provide a better developer experience and thus reduce development time * normalize all components behavior / design / attributes * have better control on dependencies and lib version upgrade * have better control on what ODS expose (through component or CDK) * ... This first step only impact two components `osds-text` and `osds-textarea`. All other components will follow on next version. Then common ODS lib and theming will be refactored on next version. ### Features changes * **Text** * `OsdsText` is no longer part of `@ovhcloud/ods-stencil` package. * `OsdsText` is now accessible by adding either `@ovhcloud/ods-component-text` or `@ovhcloud/ods-components` dependency. * `@ovhcloud/ods-stencil-text` lib has been replaced by `@ovhcloud/ods-component-text`. * `@ovhcloud/ods-stencil-text-react` lib has been replaced by `@ovhcloud/ods-component-text-react`. * `@ovhcloud/ods-stencil-text-vue` lib has been replaced by `@ovhcloud/ods-component-text- vue`. * `OdsTextSize` has been removed from `@ovhcloud/ods-core` and has been replaced by `ODS_TEXT_SIZE` from `@ovhcloud/ods-component-text`. * `OdsTextSizeList` has been removed from `@ovhcloud/ods-core` and is replaced by `ODS_TEXT_SIZES` from `@ovhcloud/ods-component-text`. * `OdsTextSizeUnion` has been removed from `@ovhcloud/ods-core`. * `OdsTextLevel` has been removed from `@ovhcloud/ods-core` and has been replaced by `ODS_TEXT_LEVEL` from `@ovhcloud/ods-component-text`. * `OdsTextLevelList` has been removed from `@ovhcloud/ods-core` and is replaced by `ODS_TEXT_LEVELS` from `@ovhcloud/ods-component-text`. * `OdsTextLevelUnion` has been removed from `@ovhcloud/ods-core`. * `@ovhcloud/ods-component-text` exports only `OdsTextAttribute` as component interface. * **Textarea** * `OsdsTextarea` is no longer part of `@ovhcloud/ods-stencil` package. * `OsdsTextarea` is now accessible by adding either `@ovhcloud/ods-component-textarea` or `@ovhcloud/ods-components` dependency. * `@ovhcloud/ods-stencil-textarea` lib has been replaced by `@ovhcloud/ods-component-textarea`. * `@ovhcloud/ods-stencil-textarea-react` lib has been replaced by `@ovhcloud/ods-component-textarea-react`. * `@ovhcloud/ods-stencil-textarea-vue` lib has been replaced by `@ovhcloud/ods-component-textarea- vue`. * `OdsTextAreaSize` has been removed from `@ovhcloud/ods-core` and is replaced by `ODS_TEXTAREA_SIZE` from `@ovhcloud/ods-component-textarea`. * `OdsTextAreaSizeList` has been removed from `@ovhcloud/ods-core` and is replaced by `ODS_TEXTAREA_SIZES` from `@ovhcloud/ods-component-textarea`. * `OdsTextAreaSizeUnion` has been removed from `@ovhcloud/ods-core`. * `@ovhcloud/ods-component-textarea` exports only `OdsTextAttribute`, `OdsTextAreaEvent` and `OdsTextAreaValueChangeEvent` as component interfaces. * `OsdsTextarea` is now displayed as flex by default. * `OsdsTextarea` `flex` attribute has been removed. * `OsdsTextarea` `inline` attribute has been added. ## What's new in v14 --- title: "What's new in v14" slug: ovhcloud-design-system-upgrade-what-s-new-v14 category: generic type: overview version: 20.0.0 tokens: 831 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v14.txt --- # What's new in v14 *Release notes of v14. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v14.1.0 ### New features * **CDK** * Manage surface position when located on the edge. * The surface can now be centered at the top or bottom of the trigger. See CDK Documentation using version selector. We added the following components: **Form Field** [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/form-field) **Switch** Removed in v20, see the [Migration guide](https://ovh.github.io/design-system/v20.0.0/guides/migration-19-to-20) ### Features changes * **Pagination** * Add tooltip to the arrows. * Can now show pages according to a numbers of items shown by page. > For more information, check our documentation [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/pagination) * **Location-tile** * Component is now deprecated and won't be supported anymore. It will be deleted in a future release. > For more information, check our replacement guide using version selector. ### Bug fixes * **Radio**: * Radio button is now unfocusable when disabled * **Input**: * cursor is set to not-allowed when disabled ## v14.0.0 As it is a major version, you have to do the [migration guide 13.x to 14.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-13-to-14) ### New features We added the following components: * **Progress Bar**: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/progress-bar) * **Popover**: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/popover) * **Tooltip**: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/tooltip) Components version 2: * **Input V2**: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/input) * new properties have been added * `loading`: it displays a Spinner * `clearable`: it clears the input value on click * `masked`: it indicates if the input value is hidden or not (to be used with password type) * new types have been added: `date`, `email`, `password`, `search`, `tel`, `text`, `time` and `url` * **Select V2**: it is now connected to our CDK and keyboard navigation has been added [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/select) **Quantity** component accepts four digits in the input field: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/quantity) **CDK** (Component Development Kit): new symmetry strategies have been added (left and right): See CDK Documentation using version selector. ### Bug fixes * **Tile**: * `hoverable` attribute has been added to avoid double focus * `interactive` attribute has been removed > **Breaking change**: for more information, check our migration guide. * **Link**: * add missing color for active state * fix Link host container size to match its content * **Icon**: add `hoverable` attribute so component color can change when in selectable parent * **Checkbox Button**: aspect ratio has been added * **Quantity**: icons alignment has been fixed * **Textarea**: when component is resized and `flex` attribute is set to `true` and then, set back to `false`, Textarea width is no more blocked to 100% ## What's new in v13 --- title: "What's new in v13" slug: ovhcloud-design-system-upgrade-what-s-new-v13 category: generic type: overview version: 20.0.0 tokens: 345 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v13.txt --- # What's new in v13 *Release notes of v13. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v13.0.0 As it is a major version, you have to do the [migration guide 12.x to 13.x](https://ovh.github.io/design-system/v20.0.0/guides/migration-12-to-13) ### New features We added the following components: * Breadcrumb: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/breadcrumb) * Collapsible: See Documentation using version selector * Pagination: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/pagination) * Spinner: [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/spinner) Circle-shaped button has been added to Button Component (circle attribute) ### Bug fixes * Button: `button' and `link`roles have been added (switching to`link\` role when Button has a href property) * Chip: expected style on Chip focus has been applied * Icon: missing download icon has been added * Input: odsValueChange event won't emit on component init * Link: * all content in Link is now aligned as expected * href and target attributes are optional * Select : * check for outside click target inside its DOM * fixed width on non flex Select has been removed > **Breaking change**: for more information, check our migration guide. ## What's new in v12 and earlier --- title: "What's new in v12 and earlier" slug: ovhcloud-design-system-upgrade-what-s-new-v12 category: generic type: overview version: 20.0.0 tokens: 1397 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-what-s-new-v12.txt --- # What's new in v12 and earlier *Release notes of v12 and earlier. For the current major version, see [What's new](https://ovh.github.io/design-system/v20.0.0/guides/whats-new).* ## v12.1.0 ### New features We added the Tabs component.
[See Documentation](https://ovh.github.io/design-system/v20.0.0/components/tabs) A component generator has been added. Now, you can use that tool to generate a new component easily.
A coding Style has also been added so you can check our guidelines and how to write code for OVHcloud Design System project.
The Contributing Documentation has been updated: * How to use a component in an other one * Theming: how to customize a style * some warning about pushing any sensitive content ### Bug fixes Range component color when in error has been fixed. Some width issue on Button component has been fixed.
When in flex, a Button can now display an ellipsis for text content when necessary. ## v12.0.5 ### Bug fixes Button component of type submit in a form will now submit the form as expected (by click or Enter / Space keys). Quantity component issue has been fixed regarding minus control that should be disabled when the input `min` attribute is equal to 0 and its value has reached 0 too. ## v12.0.0 First release on GitHub. There is no new feature in this version. It is now open source ## v11.0.0 Flag component has been modified; you’ll need to update as explained in the migration guide. For more details about assets, see [Installation](https://ovh.github.io/design-system/v20.0.0/guides/get-started) page. New attributes are available on this component: `lazy`, `assetPath` and `src`. Before importing any component you now have to setup ods. Dual range is now available for Range component; It offers two handles to set a min and max value. To build resilient infrastructure and promote sustainable industrialization, we moved code that could be agnostic. Now, ODS components logic has been moved into controllers. If you want to contribute to ODS by developing new components, please refer to the how-to section for controllers in our Storybook. Now, Button component has `download` and `rel` new attributes available when it is used as a link (href). We had blur events on Quantity component to set the correct value regarding the Quantity bounds. It means when the user set manually a value that is out of bounds for Quantity, the value will be automatically reset to a correct value. When Quantity is out of bounds, the field value is now in error state. ## v10.2.0 A new library called `CDK` for `Component Development Kit` is available. The main objective is to make the development to be easier thanks to helpers. The first integrated feature is an overlay system that allows manipulating and displaying content on foreground of the page. We added a new entire section for `contributions` in the storybook. Feel free to read the Contributing Documentation if you want to contribute. We simplified our developer environment with a `global.dev.ts` file in order to make the developer tests isolated from the production build. We optimized our CI/CD workflow for a more reactive and efficient build time and release time. We fixed some issue about automated screenshot testing with some timeout. ## v10.1.0 We added the select component (version 1). [See Documentation](https://ovh.github.io/design-system/v20.0.0/components/select) ## v10.0.0 We updated a lot of third dependencies (stencilJs, typescript, jest, puppeteer, ...): ```text @stencil/core ~2.6.0 to ~2.18.1 @stencil/sass ~1.4.1 to ~2.0.0 jest ~26.6.3 to ~27.4.5 @types/jest ~26.0.24 to ~27.5.2 jest-cli ~26.6.3 to ~27.4.5 jest-puppeteer ^5.0.4 to ~6.1.1 jest-puppeteer-preset ^5.0.4 to ~6.1.1 ts-jest ~26.5.6 to ~27.1.5 typescript 4.2.3 to 4.7.4 puppeteer ~5.5.0 to ~10.0.0 yarn-2.4.2 to yarn-3.2.4 node-fetch ~2.6.6 to ~2.6.7 ts-node ~9.1.1 to ~10.7.0 ``` > If you are an `ODS` contributor, you may need to do some changes We now build all of our components for `React` and `Vue` frameworks. They allow to use all the potential and features of your high-end JS framework. You can read the updated [Getting Started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) to initialize an App with ODS and see how it works depending the framework. Also, `ods-cart` is no more impacted by a parent container with `text-align:center`. `ods-textarea` had an incorrect `spellcheck` property than could be equal to `spellcheck="false'` which is incorrect in HTML. Now it is in DOM only if it is `true`. You can now disable animation on `ods-toggle` by defining a CSS value `--ods-toggle-transition-slider: none`. Css variables `--ods-size-squish-n-*` and `--ods-size-stretch-n-*` are no more incorrect. It was previously set with only one number instead of two, accordingly with CSS3. ## v9.1.0 Adding 2 new components : * accordion: display a content that can be collapsed * code: display a snippet of code and copy it into the clipboard If you already have customized themes, you have to declare the variables for this 2 new components. see more in the migration guide 9.x ## February 2022 The V1 **Design System** graphical charter is finalized. This charter contains : * Multiple color palettes (blue, gray, red, orange, green, availability & promotion extra colors) * A Typography system * All spacing options * Components: * **Buttons** * **Form items** (inputs, dropdowns, checkboxes, radios, radio buttons, toggle buttons, range, textarea, etc.) * **Chips & Badges** * **Cards** * **Cart** ## Migration 19.x to 20.x --- title: "Migration 19.x to 20.x" slug: ovhcloud-design-system-upgrade-migration-19-x-to-20-x category: generic type: overview version: 20.0.0 tokens: 21088 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-migration-19-x-to-20-x.txt --- # Migration 19.x to 20.x Version 20 adds support for [React 19](https://react.dev/blog/2024/12/05/react-19) **while keeping support for React 18**. The peer dependency range is unchanged: ```json "peerDependencies": { "react": ">=18.2.0", "react-dom": ">=18.2.0" } ``` The component API has **breaking changes**, each listed with its migration in **Breaking changes**. The other props, refs and composition keep working, but several components render differently with no prop set: see **Default rendering**. Moving to React 19 requires no ODS-related code change. Form fields also lose their stretch-to-container default: see **Form fields share one default width** below if your layout relied on it. The theme has **breaking changes**: the `--ods-theme-*` and `--ods-color-*` tokens are replaced by a semantic layer, without alias, and the default theme gets a new look. Any CSS, Sass or custom theme that reads the old tokens has to migrate: start with **Default theme** and follow the sections after it. The inventory of every change, with a detection command and a codemod status for each, is [BREAKING-CHANGES-V20.md](https://github.com/ovh/design-system/blob/master/BREAKING-CHANGES-V20.md). ## Automate the migration with ods-migrate `@ovhcloud/ods-migrate` applies most of this guide to your code: it renames the props, constants, types and design tokens that have a v20 equivalent, and marks every place that needs a decision with a `TODO(ods-v20)` comment that says what to do. Run it first, then use the sections below for what it marks or reports. It is published with ODS v20. ```sh npx @ovhcloud/ods-migrate . # dry run: prints what it would change, writes nothing npx @ovhcloud/ods-migrate . --write # applies the changes npx @ovhcloud/ods-migrate . --check # for CI: fails while something is left ``` Run it on a clean git branch, before you bump `@ovhcloud/ods-react` and `@ovhcloud/ods-themes` to 20: it reads the ODS version of your code from your `package.json`. Then bump, install, run your type check and resolve the markers. It also finds your own modules built on ODS, the UI kits of your repository and your components whose props take ODS values, so the places that use them follow too. The full procedure, step by step, with what each line of its report means, is in [its migration guide](https://github.com/ovh/design-system/blob/master/packages/ods-migrate/MIGRATION.md). ## If you stay on React 18 Nothing to do for React. Installation and types keep working as before. The component API changes apply whatever your React version: migrate the removed `color` props and `toast.primary()`, the Message `variant` and the Table `variant`, and review the Button default rendering (see **Breaking changes**). The theme changes below apply whatever your React version too. See also **Behavior changes** below. ## If you move to React 19 **1. Bump React and its types** to a matching major: ```shell npm install react@^19 react-dom@^19 npm install -D @types/react@^19 @types/react-dom@^19 ``` `@types/react` and `@types/react-dom` **must share the same major** (both `19`). The React team ships codemods that automate most of the app-side migration — run them on your own code (they never need to touch ODS usage): ```shell npx codemod@latest react/19/migration-recipe npx types-react-codemod@latest preset-19 ./src ``` For anything beyond ODS, follow the official [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide). **2. Make sure you have a single `@types/react` version.** This is the one real pitfall — and it is **not** specific to ODS. If a transitive dependency still pulls `@types/react@18` while your app is on `19`, TypeScript reports errors such as: ```text Type 'bigint' is not assignable to type 'ReactNode'. 'Xxx' cannot be used as a JSX component. ``` This is the classic "two copies of `@types/react`" conflict. Deduplicate to a single version: ```json // npm — package.json "overrides": { "@types/react": "^19", "@types/react-dom": "^19" } // yarn — package.json "resolutions": { "@types/react": "^19", "@types/react-dom": "^19" } // pnpm — package.json "pnpm": { "overrides": { "@types/react": "^19", "@types/react-dom": "^19" } } ``` With pnpm you can also declare it in `pnpm-workspace.yaml` (top-level key, no `pnpm` wrapper): ```yaml overrides: "@types/react": ^19 "@types/react-dom": ^19 ``` Then reinstall and verify a single version is resolved: ```shell npm ls @types/react # or: pnpm why @types/react ``` ## Form fields share one default width Every form field now ships the same default width, so mixed fields line up in a form out of the box: - **Input** (including the password type) - **Password** - **Textarea** - **Clipboard** - **Select** - **Combobox** - **Datepicker** (input and calendar trigger together) - **PhoneNumber** (country select and input together) - **Timepicker** (time input and timezone select together) The default is **280px**, capped at **100%** of the container so narrow layouts never overflow. In v19, **Select** and **Combobox** filled their container, and any field placed inside a **FormField** stretched to its width. This is no longer the case. No prop, ref or composition has changed. **To get the v19 behavior back**, set `width: 100%` on the **root** of the field. Never set it on `SelectControl`, `ComboboxControl` or `PhoneNumberControl`: the root now carries the width and the control only fills it. ```css [data-ods="select"]:not([data-ods="pagination-page-size-selector"] *), [data-ods="combobox"], [data-ods="phone-number"], [data-ods="timepicker"], [data-ods="clipboard"]:has(input), [data-ods="textarea"] { width: 100%; } ``` The two exclusions keep the fields ODS sizes by their content as they are: the page size Select of **Pagination**, and a **Clipboard** made of its trigger alone. Without them, this rule, declared outside the ODS layers, would override their own sizing. For **Input** and **Password**, pass a `className` that sets `width: 100%` to the component instead: their root carries no `data-ods` attribute (`[data-ods="input"]` and `[data-ods="password"]` target the native ``, not the root). For **Datepicker**, pass it to both `Datepicker` and `DatepickerControl`: the `Datepicker` root is an inline block sized by its content, so a percentage on the control alone does not fill the container (and `[data-ods="datepicker-control"]` also targets the native ``). To change the default width of every field at once, override the theme token: ```css :root { --ods-semantic-size-inline-size-field: 320px; } ``` **Quantity** and **QueryFilter** keep their own size and are not affected. `PhoneNumberControl` no longer declares `width: inherit`: it flexes into the space the country select leaves, so an explicit width set on the control is now overridden by its `flex-grow`. Size the **PhoneNumber** root instead. ## Bundler & framework notes These are unchanged by the React version — they apply the same way on React 18 and 19: - **Vite**: works out of the box, CSS is handled natively. - **Webpack 5**: configure `css-loader` (and `style-loader`) so the CSS shipped by ODS is bundled. - **Next.js (App Router)**: Next 15 already requires React 19. Use ODS inside client components (`'use client'`). They are server-side rendered like any client component, the Markdown component included: no `next/dynamic` with `{ ssr: false }` is needed. ## Default theme `@ovhcloud/ods-themes/default/css` now ships a neutral look: a grey page, and an accent ramp on navy for selection, text, headings and form controls. The OVHcloud look is a theme of its own, `@ovhcloud/ods-themes/blue-jeans/css`, to load **instead of** the default theme. To find the imports in your code: ```sh grep -rn "ods-themes/default/css" src/ ``` **before** ```ts import '@ovhcloud/ods-themes/default/css'; ``` **after**, to keep the OVHcloud look ```ts import '@ovhcloud/ods-themes/blue-jeans/css'; ``` Load a single theme. Every theme declares all its tokens on `:root`, and the last one loaded wins: a copy of the default theme loaded later, for instance by a micro-frontend that ships its own, brings the neutral look back. If you import `@ovhcloud/ods-themes/default`, the theme with its fonts, it is removed (see **Typography**). To keep the OVHcloud look, replace it with both lines below: ```ts import '@ovhcloud/ods-themes/blue-jeans/css'; import '@ovhcloud/ods-themes/default/fonts'; ``` If you load the theme files by path rather than through the package exports (a `` to a copied `dist` folder, a CDN URL, a bundler alias), the files moved: - `dist/default/index.css` is `dist/aluminium/light.css`. - `dist/default/fonts.css` is `dist/fonts.css`. - `dist/default/default.css` is `dist/aluminium/light.css` with `dist/fonts-base64.css`. - `dist/default/tokens.json` is `dist/aluminium/light.tokens.json`. An old path returns a 404, and the page renders without a theme, with no build error. Prefer the export paths (`@ovhcloud/ods-themes/default/css`), which did not change. To find the paths: ```sh grep -rnE "ods-themes(@[^/]+)?/(dist|src)/" . ``` ## Theme tokens The `--ods-theme-*`, `--ods-color-*` and remaining legacy tokens (`--ods-border-radius-*`, `--ods-border-width-*`, `--ods-outline-*`, `--ods-font-family-*`, `--ods-form-element-input-height`) are removed, without alias. A `var()` that reads one of them silently resolves to nothing: the property falls back to its inherited or initial value. To find them in your code: ```sh grep -rnE -- '--ods-(theme|color|border-radius|border-width|outline|font-family|form-element)-' src/ ``` **before** ```css .my-panel { background-color: var(--ods-theme-background-color); color: var(--ods-theme-text-color); border-radius: var(--ods-border-radius-md); } ``` **after** ```css .my-panel { background-color: var(--ods-semantic-color-surface-raised); color: var(--ods-semantic-color-content-text); border-radius: var(--ods-semantic-size-radius-container); } ``` The tables of the inventory give the destination of every token. Most are a 1:1 rename; a few depend on the site: - `--ods-theme-background-color` becomes `--ods-semantic-color-surface-page` for the page, `-surface-raised` for a card or a panel, `-surface-overlay` for a popover, a modal or a drawer, and `-surface-control` for a field. - `--ods-theme--color` splits by property: `--ods-semantic-color-surface-` in a `background`, `-border-` in a `border-color`, `-content-` in a `color`. `primary` becomes `brand`. - A `--ods-color--` has no name to rename to: the role depends on the property, and on the state when the custom property that reads it ends with `-hover` or `-active`. - The disabled colors (`*-disabled`) have no replacement: a disabled component is now dimmed with an opacity. - `--ods-theme-overlay-z-index` becomes `--ods-semantic-z-index-dropdown`, and its value goes from 99 to 200 (see **Layers**). The `--ods-palette-*` ramps are published, but a rung number does not give back the v19 color: blue and gray `100` to `400` are lighter, gray `500` is darker, and green, orange and red are new ramps. Point at the semantic role rather than at the palette. If you read the Sass variables of `@ovhcloud/ods-themes` by path, most are gone: read the custom properties instead. The breakpoints are still exported by `@ovhcloud/ods-react/style`. The path was the only way to these variables, and it is gone too: the Sass sources moved out of `src/default`. The import finds every file that reads them: ```sh grep -rnE "ods-themes/src/default/_?variables" src/ ``` **before** ```scss @use '@ovhcloud/ods-themes/src/default/variables' as theme; .my-banner { background-color: theme.$ods-color-primary-100; @media (width >= theme.$ods-breakpoint-tablet) { padding: 16px; } } ``` **after** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-banner { background-color: var(--ods-semantic-color-surface-selected); @media (width >= ods.$ods-breakpoint-tablet) { padding: 16px; } } ``` ## Tailwind CSS The v19 Tailwind guide had you copy a configuration that read the tokens removed above: its `ods-primary`, `ods-success`, `ods-critical`, `ods-xs` to `ods-lg` and `ods-default` keys (`ods-color-primary-500`, `ods-border-radius-md`… in a Tailwind v3 configuration) now resolve to nothing. Tailwind gives no error for a class it no longer knows: the property silently falls back. In v20, `@ovhcloud/ods-tailwind` maps the Tailwind v4 utilities to the semantic tokens, with no configuration to copy (see [Tailwind CSS Integration](https://ovh.github.io/design-system/v20.0.0/guides/tailwind)). Remove the ODS keys of your configuration, and the `.vscode/tailwind.json` list of the v19 guide, then rename the classes: v19 class v20 class bg-ods-primary, text-ods-primary, border-ods-primary bg-ods-surface-brand, text-ods-content-brand, border-ods-border-brand bg-ods-success, text-ods-success, border-ods-success bg-ods-surface-success, text-ods-content-success, border-ods-border-success bg-ods-critical, text-ods-critical, border-ods-critical bg-ods-surface-critical, text-ods-content-critical, border-ods-border-critical rounded-ods-xs (2px) no 2px radius in v20: rounded-ods-control (4px), or rounded-xs rounded-ods-sm (4px) rounded-ods-control rounded-ods-md (8px) rounded-ods-container rounded-ods-lg (16px) rounded-ods-pill font-ods-default font-ods-body, or nothing: it is the page font As for the tokens, a color depends on the property: a `bg-` reads a surface, a `text-` a content color, a `border-` a border color. `bg-ods-brand` is the logo color, not a surface. To find the classes: ```sh grep -rnE -- '[a-z-]+-ods-(primary|success|warning|critical|xs|sm|md|lg|default)\b|ods-(color-[a-z]+-[0-9]+|border-radius-[a-z]+|font-family-default)' src/ ``` ## Custom themes A v19 custom theme, including any Theme Generator export, declares `--ods-theme-*` and `--ods-color-*`. v20 neither declares nor reads these names, so such a theme has **no effect**, without any warning. To find them in your code: ```sh grep -rnE -- "--ods-(theme|color)-[a-z0-9-]+[\"']?[[:space:]]*:" src/ ``` In v20, a theme re-declares the brand and accent ramps (`--ods-palette-brand-*` and `--ods-palette-accent-*`, from 50 to 900) on `:root`, in a stylesheet loaded after the theme it builds on. **before** ```css :root { --ods-color-primary-500: #7a00cc; --ods-theme-primary-color: var(--ods-color-primary-500); } ``` **after** ```css :root { --ods-palette-brand-500: #7a00cc; /* and the other brand and accent rungs, from 50 to 900 */ } ``` The ramps do not reach every role. The focus ring (`--ods-semantic-color-focus`), the status families and the chart series keep their default values, on purpose. Over the default theme alone, the brand ghost and outline Buttons take their text from the accent ramp (`--ods-semantic-color-content-brand-minor` and `--ods-semantic-color-content-on-brand`, on accent `800`) and their border from gray (`--ods-semantic-color-border-brand-minor`): the brand ramp reaches neither, and the border follows no ramp. Re-declare these `--ods-semantic-*` roles to change them. `@ovhcloud/ods-themes/blue-jeans/css` points the three at the brand ramp instead (`500`, `700` and `500`), so a theme loaded after it repaints them through that ramp. The ramps also only take effect on `:root`: a theme scoped to a container, such as the root of a micro-frontend, re-declares the `--ods-semantic-*` roles themselves. Load a single theme, then your stylesheet after it: a theme loaded after your stylesheet overrides every token it declares, palette ramps included. ## Design tokens JSON `@ovhcloud/ods-themes/default/tokens` keeps its shape, but every key changes: it lists the `--ods-semantic-*` and `--ods-palette-*` tokens. `root` gives the value each token resolves to, and `refs` the `var()` reference of the tokens that point at another one. To find the imports in your code: ```sh grep -rn "ods-themes/default/tokens" src/ ``` **before** ```ts import tokens from '@ovhcloud/ods-themes/default/tokens'; const brand = tokens.root['--ods-theme-primary-color']; ``` **after** ```ts import tokens from '@ovhcloud/ods-themes/default/tokens'; const brand = tokens.root['--ods-semantic-color-surface-brand']; ``` Each theme ships its own JSON: `@ovhcloud/ods-themes/blue-jeans/tokens`, `aluminium-dark/tokens` and `blue-jeans-dark/tokens`. They share the `--ods-semantic-*` keys; the `--ods-palette-*` keys belong to each theme. If you move to Blue Jeans to keep the OVHcloud look, read `blue-jeans/tokens`: `default/tokens` gives the Aluminium values. ## Theme names in JavaScript The JavaScript entry point of `@ovhcloud/ods-themes` is removed, with the `ODS_THEME` enum and the `ODS_THEMES` list it exported. They only ever held `default`. Importing them now fails at build time. To find them in your code: ```sh grep -rnE "ODS_THEMES?\b" src/ ``` **before** ```ts import { ODS_THEME, ODS_THEMES } from '@ovhcloud/ods-themes'; const theme = ODS_THEME.default; const themes = ODS_THEMES; ``` **after** ```ts const theme = 'default'; const themes = ['default', 'aluminium-dark', 'blue-jeans', 'blue-jeans-dark'] as const; ``` Keep the list of themes in your application: list the ones it offers, each loaded through its export path, `@ovhcloud/ods-themes//css`. ## Component tokens and style variables The `--ods--*` custom properties keep their names, with the exceptions below. An override of a removed name is ignored without any warning; a read of a removed SCSS variable fails the build with "Undefined variable". - `--ods-button-border-radius-width` is renamed `--ods-button-border-width`, and the SCSS variable `$ods-button-border-radius-width` of `@ovhcloud/ods-react/style` is renamed `$ods-button-border-width`. - On Code, `--ods-code-primary-color` is renamed `--ods-code-text-color`, `--ods-code-secondary-color` is renamed `--ods-code-background-color`, and `--ods-code-trigger-background-color` is renamed `--ods-code-trigger-color`. - The tokens that only painted a disabled state are removed, since a disabled component is now dimmed with an opacity: `--ods-button-group-item-background-color-checked-disabled`, `--ods-switch-item-background-color-checked-disabled`, `--ods-tab-background-color-selected-disabled-switch`, `--ods-tab-border-color-disabled`, `--ods-tab-border-color-selected-disabled`, `--ods-tab-border-color-selected-disabled-switch`, `--ods-tile-background-color-disabled`, and the SCSS variables `$ods-state-is-disabled-background-color`, `$ods-state-is-disabled-border-color` and `$ods-state-is-disabled-text-color`. For a grey disabled state, style `:disabled` or `[data-disabled]` yourself. - The tokens that nothing read in 19.7.3 are removed: `--ods-tile-background-color`, `--ods-tile-border-color` and `--ods-tile-border-width` (the Tile renders a Card: override the `--ods-card-*` tokens instead), and the six `--ods-modal-header-background-color-*`. - `--ods-tab-border-color-selected` and `--ods-tab-text-color-selected` are removed: the selected Tab reads `--ods-semantic-color-border-selected-solid` and `--ods-semantic-color-content-on-selected`, so override those on `[data-ods="tab"]`. - `--ods-message-close-button-text-color-primary` is removed: the close button of the Message is a neutral ghost Button, so override `--ods-button-text-color-neutral-low` on `[data-ods="message"] [data-ods="button"]`. - `--ods-toggle-control-background-color-hover` is removed: the unchecked Toggle no longer changes its background on hover. `--ods-toggle-control-border-color` is removed too: the Toggle border reads `--ods-semantic-color-border-control`, so override that one on `[data-ods="toggle"]`. - The status custom properties of Badge, Button, Card, Message and Tag are renamed after the status and the emphasis they paint, and the Button and Tag ones that nothing read are removed: see **The Sass mixins and CSS custom properties follow the status and the emphasis** in **Breaking changes**, and the Button and Message entries. - The SCSS variables deprecated in v19 are removed: `$ods-modal-z-index` (read `$ods-overlay-modal-z-index`), `$ods-modal-border-radius` (read `var(--ods-semantic-size-radius-overlay)`), `$ods-modal-margin` (read `$ods-modal-margin-horizontal` or `$ods-modal-margin-vertical`), `$ods-overlay-arrow-background-color` (read `var(--ods-semantic-color-surface-overlay)`) and `$drawer-max-size` (read `$drawer-max-width` or `$drawer-max-height`). So are the unused `ods-modal-color()` mixin and `$ods-overlay-select-z-index` (read `$ods-overlay-base-z-index`). To find them in your code: ```sh grep -rnE -- 'ods-button-border-radius-width|ods-code-(primary-color|secondary-color|trigger-background-color)([^-a-z]|$)|(checked|selected)-disabled|tab-border-color-disabled|ods-tile-(background-color|border-color|border-width)(-disabled)?([^-a-z]|$)|ods-modal-header-background-color|close-button-text-color-primary|ods-tab-(border|text)-color-selected([^-a-z]|$)|toggle-control-(background-color-hover|border-color)([^-a-z]|$)|\$ods-state-is-disabled-|\$ods-modal-(z-index|border-radius|margin)([^-a-z]|$)|ods-overlay-(arrow-background-color|select-z-index)|drawer-max-size|ods-modal-color\(' src/ ``` **before** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-button { --ods-button-border-radius-width: 2px; } .my-code { --ods-code-secondary-color: #f5f5f5; } .my-layer { z-index: ods.$ods-modal-z-index; } ``` **after** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-button { --ods-button-border-width: 2px; } .my-code { --ods-code-background-color: #f5f5f5; } .my-layer { z-index: ods.$ods-overlay-modal-z-index; } ``` Six SCSS variables of `@ovhcloud/ods-react/style` held a number in 19.7.3 and now hold a `var()`: `$ods-button-size-xs` (`24px`), `$ods-button-size-sm` (`32px`), `$ods-button-size-md` (`40px`), `$ods-badge-height-md` (`24px`), `$animation-duration` (`0.3s`) and `$ods-link-font-weight` (`600`). A plain use renders as before, but Sass cannot compute with them: `ods.$animation-duration * 2` fails the build with "Undefined operation", and `ods.$ods-badge-height-md + 4px` compiles without an error to an invalid value. Move the operation into `calc()`. To find them in your code, with a namespace or without one (`@use ... as *`). The search also lists an `$animation-duration` that your own code declares: ```sh grep -rnE '\$(ods-badge-height-md|ods-button-size-(xs|sm|md)|animation-duration|ods-link-font-weight)([^-a-z0-9]|$)' src/ ``` **before** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-panel { min-height: ods.$ods-button-size-md + 8px; transition: opacity ods.$animation-duration * 2; } ``` **after** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-panel { min-height: calc(#{ods.$ods-button-size-md} + 8px); transition: opacity calc(#{ods.$animation-duration} * 2); } ``` Two more changes need no code change: `$ods-input-actions-padding-right` goes from `4px` to `2px`, so the action buttons of a field sit as close to its border as its block inset, and `./style` gains the `ods-highlight-indicator()` mixin. ## Layers Each kind of overlay now has its own layer, and a modal is always above a drawer. In v19 they all sat around the same value, so the one opened last was on top: - lists, popovers, tooltips and toasts: `99` in v19, `--ods-semantic-z-index-dropdown` (`200`) in v20; - drawers: `101` in v19, `--ods-semantic-z-index-drawer` (`300`, backdrop `299`) in v20; - modals: `101` (backdrop `100`) in v19, `--ods-semantic-z-index-modal` (`400`, backdrop `399`) in v20; - `$ods-overlay-modal-z-index` and `$ods-overlay-drawer-z-index` go from `100` and `101` to `400` and `300`: their order flips. A layer of yours stacked on `--ods-theme-overlay-z-index` or on these SCSS variables, or with a literal z-index between `102` and `399` meant to clear the ODS overlays, now lands somewhere else. To find them in your code: ```sh grep -rnE -- '--ods-theme-overlay-z-index|\$ods-overlay-[a-z]+-z-index|z-index:|zIndex' src/ ``` **before** ```css .my-floating-panel { z-index: calc(var(--ods-theme-overlay-z-index) + 2); } ``` **after** ```css .my-floating-panel { z-index: calc(var(--ods-semantic-z-index-modal) + 1); } ``` To have a drawer win over a modal, pass a higher `z-index` to the drawer through its `positionerStyle`. ## Default rendering These changes need no code change: the new rendering is intended. To keep the v19 one, set the prop given below, or add the rule given below to your own stylesheet, outside any `@layer`, so that it wins over the ODS styles. - **Badge**: a pill with a colored border and colored text on the raised surface (the new `medium` emphasis), where v19 had 4px corners, no border and a tinted background (filled for `primary`). Every size keeps its v19 height, but the pill takes 8px on each side (12px in `lg`) where v19 took 4px (6px). To get closer to v19, use `emphasis="high"` for the tinted background and `[data-ods="badge"] { --ods-badge-border-radius: 4px; --ods-badge-padding-horizontal-sm: 3px; --ods-badge-padding-horizontal-md: 3px; --ods-badge-padding-horizontal-lg: 5px; }` for the corners and the widths, border included; the colors stay those of v20. The blue-jeans theme keeps the 4px corners and the v19 widths, and its `high` emphasis is the v19 tinted background without border (see Badge). - **Card and Tile**: a `--ods-semantic-color-surface-raised` background, where v19 had none. Keep v19: `[data-ods="card"], [data-ods="tile"] { --ods-card-background-color: transparent; }`. - **Card without `status`**: neutral, where v19 was primary. Keep v19: `status="accent"`. - **Button without `emphasis`**: outlined (`medium`), where a Button without `variant` was filled in v19. Keep v19: `emphasis="high"` (see **Button**). - **Message without `emphasis`**: the raised surface with a light colored border (`medium`), where a Message without `variant` had a tinted background in v19. Keep v19: `emphasis="high"` (see **Message**). - **Accordion**: a `--ods-semantic-color-surface-raised` background and 8px outer corners, where v19 had no background and 4px corners. Keep v19: `[data-ods="accordion"] { --ods-accordion-background-color: transparent; --ods-accordion-border-radius: 4px; }`. - **Button**: 4px corners at every size, where v19 had 2px (`xs`), 4px (`sm`) and 8px (`md`). Keep v19: `[data-ods="button"] { --ods-button-border-radius-xs: 2px; --ods-button-border-radius-sm: 4px; --ods-button-border-radius-md: 8px; }`. - **Input, Quantity, Textarea and the fields built on them**: a `--ods-semantic-color-surface-control` background, where v19 was transparent. Keep v19: `--ods-semantic-color-surface-control: transparent` on the container of the fields, never on `:root`, where it would also clear the open lists of Select, Combobox and Query Filter. In that container, it also clears the Checkbox, the Select control, the outline Button (a Cancel or Back button next to the fields), and a list rendered with `createPortal={ false }`, which sits inside the container. - **Tabs**: the selected tab fills with `--ods-semantic-color-surface-selected`, where v19 left it transparent, and the selected segment of a switch gets an outline. Keep v19: `[data-ods="tab"] { --ods-semantic-color-surface-selected: transparent; --ods-tab-border-color-selected-switch: transparent; }`. Hovering a switch segment now paints `--ods-tab-background-color-hover`, the same token as the hover of the default tabs, so no rule removes it without changing those too. - **Combobox**: the tags of a multiple Combobox are `accent`, where v19 rendered the default `information` Tag, and the focused tag reads the accent hover tokens of the Tag. An override of the information Tag tokens no longer reaches these tags: override `--ods-tag-*-accent*` instead. - **Query Filter**: the tags are `accent`, where v19 rendered the default `information` Tag. An override of the information Tag tokens no longer reaches them: override `--ods-tag-*-accent*` instead. - **Link**: the hover color is the rest color, `--ods-semantic-color-content-brand`, where v19 darkened it. The colors are read from `--ods-link-text-color`, `--ods-link-text-color-hover` and `--ods-link-text-color-visited`, also declared by the `ods-link()` mixin. Keep the v19 hover: `:where([data-ods="link"], [data-ods="breadcrumb-link"], [data-ods="breadcrumb"] li > button) { --ods-link-text-color-hover: var(--ods-semantic-color-interaction-brand-hover); }` (the last selector is the `Breadcrumb` ellipsis, which has no `data-ods`). An element styled with `ods-link()` declares the property itself: set it in the same rule, after the `@include`. The link is also underlined at rest: see **Link underline** below. - **Modal**: the content draws `--ods-semantic-shadow-overlay`, as the Drawer and the other overlays, where v19 drew no shadow. In the dark themes, this shadow is what sets the modal off its backdrop. Keep v19: `[data-ods="modal-content"] { box-shadow: none; }`. - **Motion**: the Toggle thumb goes from `0.4s ease` to 300ms `ease-in-out`, its checked background and border from `0.2s ease` to 200ms `ease-in-out`, the Radio dot from 120ms to 150ms, and the TreeView and TabList transitions from `ease` to `ease-in-out`. When the user asks for reduced motion, the default theme also brings `--ods-semantic-motion-duration-fast`, `-medium` and `-slow` down to `0.01s`. Keep the full durations: `@media (prefers-reduced-motion: reduce) { :root { --ods-semantic-motion-duration-fast: 150ms; --ods-semantic-motion-duration-medium: 200ms; --ods-semantic-motion-duration-slow: 300ms; } }`, loaded after the theme. - **Disabled components**: dimmed with an opacity, where v19 repainted them grey. Keep v19: style `:disabled` or `[data-disabled]` yourself. - **Modal and Drawer**: a modal is always above a drawer (see **Layers**). ### Link underline A link is underlined at rest, 1px in its own color, so that it is not told from the surrounding text by its color alone (RGAA 10.6, WCAG 1.4.1), and the underline turns 2px on hover: the thicker underline is the hover signal. v19 only drew it on hover, 1px, with a left-to-right sweep. It applies to `Link`, the `Breadcrumb` links, the `Markdown` links and the elements styled with the `ods-link()` mixin. An icon-only link made of ODS icons and the `Breadcrumb` ellipsis have no underline at rest, the page links and the chevrons of a `Pagination` keep a 1px hover underline, and a disabled link keeps its rest underline, dimmed with it. The thicknesses are read from `--ods-link-underline-thickness` and `--ods-link-underline-thickness-hover`. To keep the links of a navigation, a menu or a footer without an underline at rest, set them on that container only, so that the links within your text keep theirs: ```css .my-app-nav { --ods-link-underline-thickness: 0; --ods-link-underline-thickness-hover: 1px; } ``` A `Link` restyled as a button or as a full-width menu item now draws its 1px line along its bottom edge at rest, and a `Link` that wraps a `Button` or an image draws it under that element: set `--ods-link-underline-thickness: 0` on that `Link`, or, when it runs an action rather than a navigation, render a `Button` instead. Keep the underline on a link placed within a sentence: without it, the link is told by its color only. The underline is a pseudo-element, not a `text-decoration`: `text-decoration: none`, or the Tailwind `no-underline` class, does not remove it. Set the variable instead, for instance `[--ods-link-underline-thickness:0]` in Tailwind. The content of a `Menu` or a `Popover` renders in a portal, outside your container: set the variables on `MenuContent` or `PopoverContent`, through their `className`. The icon-only case is detected on the ODS `Icon` component itself: a component of yours that renders it is not, and that link keeps its underline. Set `--ods-link-underline-thickness: 0` on it. A rule of yours on the `::after` of a link (`[data-ods="link"]`, `[data-ods="breadcrumb-link"]` or an element styled with `ods-link()`) was written for a line hidden at rest. A `height` now shows at rest and gives way to the 2px of the hover, so the link gets thinner on hover. A current-page indicator made with `transform: scaleX(1)` no longer stands out. Replace these rules with the custom properties: ```css .my-link { --ods-link-underline-thickness: 0; --ods-link-underline-thickness-hover: 3px; } .my-nav [aria-current="page"] { --ods-link-underline-thickness: 2px; --ods-link-underline-thickness-hover: 2px; } ``` To find the cases above: ```sh rg -U -l '<(Ods)?Link\b[^>]*>\s*<(Button|img)\b' -g '*.tsx' src rg -U -l '<(MenuItem|PopoverContent)\b[^<]*>[\s\S]{0,400}?<(Ods)?Link\b' -g '*.tsx' src grep -rnE -A8 'ods-link\(\)|data-ods=.(breadcrumb-)?link' src/ | grep -E '::after|scaleX|height' ``` Closest to v19 for every link, without the sweep: `:root { --ods-link-underline-thickness: 0; --ods-link-underline-thickness-hover: 1px; }`. With the v19 sweep on `Link` and the `Breadcrumb` links too: ```css :root { --ods-link-underline-thickness: 0; --ods-link-underline-thickness-hover: 1px; } :where([data-ods="link"], [data-ods="breadcrumb-link"]) { --ods-link-underline-thickness: 1px; } :where([data-ods="link"], [data-ods="breadcrumb-link"])::after { transform: scaleX(0); transform-origin: left center; transition: transform var(--ods-semantic-motion-duration-medium) var(--ods-semantic-motion-easing-enter); } :where([data-ods="link"], [data-ods="breadcrumb-link"]):is(:hover, :focus-visible):not([aria-disabled="true"])::after { transform: scaleX(1); } ``` The sweep only reaches `Link` and the `Breadcrumb` links: the ellipsis and the elements styled with `ods-link()` have no `data-ods`, and keep the thicknesses with no sweep. ## Typography The default font family is renamed from `'Source Sans Pro'` to `'Source Sans 3'`, the current name of the font. The font files shipped by ODS were already Source Sans 3, so the rendering is unchanged: only the CSS family name changes. `--ods-semantic-font-family-body` and `--ods-semantic-font-family-heading` start with `'Source Sans 3'`, and the `@font-face` rules of `@ovhcloud/ods-themes/default/fonts` and `@ovhcloud/ods-themes/fonts-base64` declare the font under that name only: there is **no** `'Source Sans Pro'` alias. If you only use the theme tokens, with the fonts loaded by ODS, there is nothing to do, except in the cases below. If your CSS or a custom theme writes `'Source Sans Pro'`, it no longer matches any font loaded by ODS and the text falls back to the next font of your stack: use `var(--ods-semantic-font-family-body)`, or `'Source Sans 3'`, instead. In particular: - **A theme exported from the v19 Theme Generator** contains `--ods-theme-font-family` and `--ods-font-family-default` with `'Source Sans Pro'`. v20 reads neither, nor any other name of such a theme (see **Custom themes**). To change the font, set `--ods-semantic-font-family-body` and `--ods-semantic-font-family-heading`. - **If you load `@ovhcloud/ods-themes/default/css` with your own `@font-face`** declared as `'Source Sans Pro'`, rename it `'Source Sans 3'`, or load `@ovhcloud/ods-themes/default/fonts` instead. - `@ovhcloud/ods-themes/default/tokens` exposes the font under its new name, in `--ods-semantic-font-family-body` (see **Design tokens JSON**). **before** ```css body { font-family: 'Source Sans Pro', 'Trebuchet MS', arial, 'Segoe UI', sans-serif; } ``` **after** ```css body { font-family: var(--ods-semantic-font-family-body); } ``` To find the occurrences in your code: ```sh grep -rniE "source.?sans.?pro" src/ ``` If you reference the theme Sass sources or font files directly (Sass imports, copied assets, CDN URLs, ``), the `assets/fonts/source-sans-pro/` folder is renamed `assets/fonts/source-sans-3/`, and the `source-sans-pro-font-face` and `source-sans-pro-italic-font-face` mixins are renamed `source-sans-3-font-face` and `source-sans-3-italic-font-face`. The `@ovhcloud/ods-themes/default` import, the default theme with its fonts inlined as base64, is removed: it reloaded every font with the theme. Load the theme and the fonts separately. The base64 fonts remain, as a fallback for a setup that cannot serve the font files, in `@ovhcloud/ods-themes/fonts-base64`: the same fonts as `default/fonts`, those of the themes ODS ships, to load instead of it. **before** ```typescript import '@ovhcloud/ods-themes/default'; ``` **after** ```typescript import '@ovhcloud/ods-themes/default/css'; import '@ovhcloud/ods-themes/default/fonts'; ``` Or, if your setup cannot serve the font files: ```typescript import '@ovhcloud/ods-themes/default/css'; import '@ovhcloud/ods-themes/fonts-base64'; ``` In Sass, `@import '@ovhcloud/ods-themes/default';` becomes the same two imports, `default/css` and `default/fonts`. The build fails on the old import: Sass reports that it cannot find the stylesheet, and the bundler that the package does not export `./default` (`"./default" is not exported`, or `Missing "./default" specifier` with an older Vite). The import ends with `default`, so this search finds it in a JavaScript or a Sass file: ```sh grep -rnE "ods-themes/default['\"]" src/ ``` ## Behavior changes These apply whichever React version you use. - **Drawer** without backdrop, focus on close: when the Drawer is closed while the focus is inside it (Escape, a close button inside it, or `open` set to `false` by your code), or after its focused element was removed, the focus now returns to the trigger it was opened from or, for a Drawer without trigger, to the element that had the focus before it opened. The page scrolls that element back into view if it has left the screen. In v19, the focus stayed on an element of the closed Drawer. A focus moved elsewhere in the page is never taken back, so code that focuses another element when the Drawer closes keeps working, and code that only focuses the trigger again can be removed. A layer opened from the Drawer (a confirmation Modal, a Menu) that gives the focus back inside the closed Drawer hands it to the trigger too. A Drawer unmounted while open (`{ isOpen && }`) gives nothing back: keep it mounted and drive `open` instead. - **Drawer** with a custom `id` on `DrawerContent`: Escape, `closeOnInteractOutside` and the focus on open now work, and the trigger `aria-controls` points to the content. In v19, they silently did nothing. ## Breaking changes These changes require a code update: each one comes with its before and after. **The `color` prop is removed** from Badge, Button, Card, Divider, Message, ModalContent, Spinner and Tag (on Divider and ModalContent, it was deprecated since v19), with the `XXX_COLOR` and `XXX_COLORS` constants and the `XxxColor` types of these components and of the Toaster, and with `toast.primary()`. Where the component has a `status` prop, use it instead (`XXX_STATUS`, `XXX_STATUSES` and the `XxxStatus` type): the `primary` value is renamed `accent` (`brand` on Button), the other values keep their name, except Button `information`, `success` and `warning`, which have no `status` (see Button). Divider, ModalContent and Spinner have no `status`: see their own entry. - TypeScript reports each removed usage, even through a spread object: `color` is typed `never` on these components, so not even the HTML `color` attribute is accepted. - In untyped JavaScript, a `color` attribute is no longer read by these components: it is forwarded to the DOM as the obsolete HTML `color` attribute. Remove it. - If one of your wrappers declares its own `color` prop on top of `BadgeProp` (or the props of the other components above), TypeScript reports that it incorrectly extends it: remove the prop and map its values to `status`, or keep it under an `Omit` if it serves another purpose. - If one of your wrappers takes the HTML props of an element (`ComponentPropsWithRef<'span'>`…) and spreads them into one of these components, TypeScript reports that `color` is not assignable to `undefined`: omit it from the wrapper props (`Omit, 'color'>`). - If one of your wrappers declares its own `status` prop on top of `BadgeProp` (or the Button, Card, Message or Tag props), TypeScript reports a conflict, often as `Type '…' is not assignable to type 'never'` at the call sites or `Rest types may only be created from object types` in the wrapper: add `'status'` to the `Omit` (`Omit`) or rename your prop, and destructure it before spreading the other props into the ODS component. In untyped JavaScript, a `status` attribute forwarded to these components is now interpreted as the status preset. - The Sass mixins and the CSS custom properties follow the status and the emphasis too: see **The Sass mixins and CSS custom properties follow the status and the emphasis** below. To find the usages to migrate in your code: ```sh grep -rnE "\b(BADGE|BUTTON|CARD|MESSAGE|SPINNER|TAG|TOAST|DIVIDER|MODAL)_COLORS?\b|\b(Badge|Button|Card|Message|Spinner|Tag|Toast|Divider|Modal)Color\b|toast\.primary\(|[[:space:]]color=" src/ ``` `color=` also matches native and third-party elements: review each match. Props passed through an object or a spread (`{ color: 'primary' }`) are not matched, but TypeScript reports them. In a codebase that also uses other libraries, limit the search to the files that import ODS: `grep -rl "@ovhcloud/ods-react" src | xargs grep -nE ""`. A library built on ODS (a UI kit wrapping Badge or Button) must migrate too before you can move to v20. **The Sass mixins and CSS custom properties follow the status and the emphasis.** The styles behind the props now use the same names: - Badge: the status custom properties take their emphasis, and `primary` becomes `accent`: `--ods-badge-background-color-primary` becomes `--ods-badge-background-color-accent-high`, `--ods-badge-text-color-critical` becomes `--ods-badge-text-color-critical-high` (see Badge), and `ods-badge-color('primary')` becomes `ods-badge-color('accent')`. The decorative statuses keep their names. - Card and Tag: `primary` becomes `accent` in their custom properties and in the `ods-tag-color` mixin: `--ods-tag-border-color-primary-hover` becomes `--ods-tag-border-color-accent-hover`, `--ods-card-border-color-primary` becomes `--ods-card-border-color-accent`. The other statuses keep their names. - Message: `primary` becomes `accent` too, and every name also takes its emphasis: `--ods-message-background-color-primary` becomes `--ods-message-background-color-accent-high`, not `--ods-message-background-color-accent` (see Message). - Button: every status custom property and mixin takes its emphasis, and `primary` becomes `brand`: `--ods-button-background-color-primary-hover` becomes `--ods-button-background-color-brand-high-hover` (see Button). - The text colors of a hovered or pressed Tag are removed: `--ods-tag-text-color--hover` and `-active` held the rest value and nothing read them. Some Button ones are removed for the same reason (see Button). - These mixins now fail to compile on a value they do not know: `'primary'` names its new value, and any other value lists the accepted ones. An override or a `var()` of a custom property under its old name is silently ignored: search for them. ```sh grep -rnE -- '--ods-(badge|card|tag)-[a-z-]*primary|--ods-badge-(background|text)-color-(critical|information|neutral|success|warning)([^-a-z]|$)|--ods-tag-text-color-[a-z]+-(hover|active)([^-a-z]|$)|ods-(badge-color|tag-color)[a-z-]*\(.{0,3}primary' src/ ``` On Badge, Card and Tag, the renames are 1:1. To apply them to the files found, then add `emphasis="high"` to the Badges these overrides target and remove the overrides of the Tag text colors by hand: ```sh sed -E -i.bak 's/(--ods-badge-(background|text)-color-)primary/\1accent-high/g; s/(--ods-badge-(background|text)-color-(critical|information|neutral|success|warning))([^-a-z]|$)/\1-high\4/g; s/(--ods-(card|tag)-[a-z-]*)primary/\1accent/g; s/(ods-(badge-color|tag-color)[a-z-]*\([[:space:]]*["'"'"']?)primary/\1accent/g' ``` These searches miss a status passed through a variable or a list, and a name built by interpolation: ```scss @each $status in primary, information, success { .my-button--#{$status} { @include ods.ods-button-variant-default($status); } } ``` The build reports a leftover mixin value, one value at a time. Nothing reports an interpolated custom property (`--ods-tag-background-color-#{$status}` in Sass, `` `--ods-tag-background-color-${status}` `` in TypeScript): search them too. ```sh grep -rnE -- '--ods-(badge|button|card|message|tag)-[a-z-]*(#\{|\$\{)' src/ grep -rlE "@ovhcloud/ods-react/style" src | xargs grep -nwE "primary|information|success|warning" ``` **before** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-badge { @include ods.ods-badge-color('primary'); } .my-tags { --ods-tag-background-color-primary-hover: #e0f0ff; } ``` **after** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-badge { @include ods.ods-badge-color('accent'); } .my-tags { --ods-tag-background-color-accent-hover: #e0f0ff; } ``` **The APIs deprecated in v19 are removed**: the Switch component (see Switch), the Pagination and the Toggle used without children (see Pagination and Toggle), the `renderTotalItemsLabel` and `withPageSizeSelector` props of Pagination, the positioning props replaced by `overlayConfig` (see Menu, Popover, Select and Tooltip) and the `uploadSuccessLabel` prop of FileUploadItem (see File Upload). - **Fastest path**: upgrade, then run `tsc --noEmit`. Each removed usage is a type error, even passed through a spread object: `children` missing on a Pagination or a Toggle, a removed prop elsewhere. The `grep` commands of each section are a fallback for untyped code. - **On a v19 release older than 19.7.0**, `overlayConfig`, `PaginationPages` and `PaginationPageSizeSelector` do not exist yet: upgrade to the latest 19.x first, which breaks nothing, migrate, then upgrade to v20. - **If you publish a library built on ODS**, release its v20-compatible version first: its compiled JavaScript gets no type error, and a removed prop it still passes is silently ignored. ### Accordion **New `emphasis` prop** (`ACCORDION_EMPHASIS`, `ACCORDION_EMPHASES` and the `AccordionEmphasis` type): `high`, `medium` or `low`, set on the root for every item. `medium` is the default, so an Accordion without `emphasis` only gets the changes listed in **Default rendering**: nothing to migrate. Only a wrapper is affected: if it declares its own `emphasis` prop on top of `AccordionProp`, add `'emphasis'` to its `Omit` or rename it. In untyped JavaScript, an `emphasis` attribute forwarded to Accordion is now read as the emphasis preset. **before** ```tsx import { type AccordionProp } from '@ovhcloud/ods-react'; interface FaqProp extends AccordionProp { emphasis?: boolean; } ``` **after** ```tsx import { type AccordionProp } from '@ovhcloud/ods-react'; interface FaqProp extends Omit { emphasis?: boolean; } ``` ### Badge **The `color` prop is removed**, with `BADGE_COLOR`, `BADGE_COLORS` and the `BadgeColor` type (see above): - `color` (or `BADGE_COLOR`): use `status` (or `BADGE_STATUS`). - `color="primary"`: use `status="accent"`. - `color="alpha"`, `beta`, `critical`, `information`, `neutral`, `new`, `promotion`, `success`, `warning`: use `status` with the same value. `information` stays the default. - `BADGE_COLORS` and `BadgeColor`: use `BADGE_STATUSES` and `BadgeStatus`. **New `emphasis` prop** (`BADGE_EMPHASIS`, `BADGE_EMPHASES`, `BadgeEmphasis`): `high`, `medium` or `low`. `medium` is the default: a colored border and colored text on the raised surface, which is not the v19 look (see **Default rendering**). Use `high` for a tinted background with a light border, the closest to v19, and `low` for colored text only. In the blue-jeans theme, `high` is the tinted background without border, as in v19, and `medium` sits on the raised surface with the light status border: add `emphasis="high"` to keep the v19 look. If one of your wrappers declares its own `emphasis` prop on top of `BadgeProp`, add `'emphasis'` to its `Omit` or rename it; in untyped JavaScript, an `emphasis` attribute forwarded to Badge is now read as the emphasis preset. **The status custom properties take the emphasis.** In v19, `--ods-badge-background-color-` and `--ods-badge-text-color-` painted the tinted Badge, which is the `high` emphasis in v20: they become `--ods-badge-background-color--high` and `--ods-badge-text-color--high`, and apply once you add `emphasis="high"`. The default `medium` Badge reads the new `--medium` names. No unsuffixed name is left for `accent`, `critical`, `information`, `neutral`, `success` and `warning`, so an old override is ignored rather than applied to another emphasis. The decorative `alpha`, `beta`, `new` and `promotion` keep their names. To find the usages to migrate: `grep -rnE "\bBADGE_COLORS?\b|\bBadgeColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { BADGE_COLOR, Badge } from '@ovhcloud/ods-react'; New feature Active ``` **after** ```tsx import { BADGE_STATUS, Badge } from '@ovhcloud/ods-react'; New feature Active ``` **optional, new in v20** ```tsx import { BADGE_EMPHASIS, BADGE_STATUS, Badge } from '@ovhcloud/ods-react'; Expired Active ``` ### Button **The `color` prop is removed**, with `BUTTON_COLOR`, `BUTTON_COLORS` and the `ButtonColor` type (see above): - `color` (or `BUTTON_COLOR`): use `status` (or `BUTTON_STATUS`). - `color="primary"`: use `status="brand"`, or nothing, as `brand` is the default. - `color="critical"` and `color="neutral"`: use `status` with the same value. - `color="information"`, `success` and `warning` are removed **without** `status` equivalent: a Button does not convey a status. Use a `brand`, `neutral` or `critical` Button, and a Badge or a Message to convey the status. - With them, their CSS custom properties are removed (see **The Sass mixins and CSS custom properties are named after the status and the emphasis** below). - `BUTTON_COLORS` and `ButtonColor`: use `BUTTON_STATUSES` and `ButtonStatus`. **The `variant` prop is replaced by `emphasis`**, with `BUTTON_VARIANT`, `BUTTON_VARIANTS` and the `ButtonVariant` type (use `BUTTON_EMPHASIS`, `BUTTON_EMPHASES` and `ButtonEmphasis`): - `variant="default"`: use `emphasis="high"`. - `variant="outline"`: use `emphasis="medium"`, or nothing, as `medium` is the new default. - `variant="ghost"`: use `emphasis="low"`. - The Sass mixins and the CSS custom properties take the emphasis too (see **The Sass mixins and CSS custom properties are named after the status and the emphasis** below). **The default rendering changes.** In v19, a Button without `variant` was filled (the `default` variant). In v20, a Button without `emphasis` is `medium`, which renders as the v19 `outline` variant. The ODS components built on Button (Pagination, ButtonGroup, Cart…) keep their v19 rendering. - To keep the filled rendering, add `emphasis={ BUTTON_EMPHASIS.high }` (or `emphasis="high"`) to each Button that set no `variant`, including in your own components that render or wrap a Button. - If one of your wrappers declares its own `emphasis` prop on top of `ButtonProp`, add `'emphasis'` to its `Omit` or rename it; in untyped JavaScript, an `emphasis` attribute forwarded to Button is now read as the emphasis preset. To find the Buttons to review in your code: ```sh grep -rnE "|$)|\bBUTTON_(VARIANT|COLOR)S?\b|\bButton(Variant|Color)\b" src/ ``` TypeScript reports every remaining `variant` and `color` on a Button. Review each `` written without a space and Buttons imported under another name (`import { Button as OdsButton }`): search for those names too. **before** ```tsx import { BUTTON_COLOR, BUTTON_VARIANT, Button } from '@ovhcloud/ods-react'; // filled in v19, medium (outlined) in v20 ``` **after** ```tsx import { BUTTON_EMPHASIS, BUTTON_STATUS, Button } from '@ovhcloud/ods-react'; ``` **The Sass mixins and CSS custom properties are named after the status and the emphasis**, `` being `brand` (`primary` in v19), `critical` or `neutral`, and `` being `background`, `border` or `text`: - `ods-button-variant-default()`: use `ods-button-emphasis-high()`. - `ods-button-variant-outline()`: use `ods-button-emphasis-medium()`. - `ods-button-variant-ghost()`: use `ods-button-emphasis-low()`. - `--ods-button--color-`, with its `-hover` and `-active` states: use `--ods-button--color--high` (`--ods-button-background-color-primary-hover` becomes `--ods-button-background-color-brand-high-hover`). - `--ods-button--color--outline`, with its states: use `--ods-button--color--medium`. - `--ods-button--color--ghost`, with its states: use `--ods-button--color--low`. - No v19 name keeps another meaning: the names without emphasis, which painted the filled Button, are gone, so an override left under an old name paints nothing rather than another emphasis. - Removed, as nothing read them and they held the rest value: `--ods-button-text-color--hover` and `-active` (a high Button keeps its text color), and `--ods-button-border-color--ghost` with its states (a low Button draws no border). - The `information`, `success` and `warning` custom properties are removed, and the mixins accept `brand`, `critical` and `neutral` only. A `var()` of one of them reads the semantic role it held instead, `` being `information`, `success` or `warning`: `--ods-semantic-color-surface-` for the high background, `--ods-semantic-color-border-` for the high and medium border, `--ods-semantic-color-interaction--hover` and `-active` for their hover and active background and border, `--ods-semantic-color-content-on--solid` for the high text, `--ods-semantic-color-surface-control` for the medium background, `--ods-semantic-color-interaction--subtle-hover` and `-active` for the medium and low hover and active background, `--ods-semantic-color-content-` for the medium and low text and `--ods-semantic-color-content-on-` for their hover and active text. An override of one of them paints nothing: remove it. - The mixins fail to compile on a value they do not know: `'primary'` names `'brand'`, and a removed status says it is removed. To find them in your code, this search matches every v19 name and no v20 one: ```sh grep -rnE -- '--ods-button-(background|border|text)-color-[a-z]+(-ghost|-outline)?(-hover|-active)?([^-a-z]|$)|ods-button-variant-' src/ ``` Outside the removed names, the renames are 1:1. To apply them to the files found, in this order: ```sh sed -E -i.bak 's/(--ods-button-(background|border|text)-color-)primary/\1brand/g; s/(--ods-button-(background|border|text)-color-(brand|critical|neutral))-ghost/\1-low/g; s/(--ods-button-(background|border|text)-color-(brand|critical|neutral))-outline/\1-medium/g; s/(--ods-button-(background|border|text)-color-(brand|critical|neutral))(-hover|-active)?([^-a-z0-9]|$)/\1-high\4\5/g; s/ods-button-variant-default/ods-button-emphasis-high/g; s/ods-button-variant-outline/ods-button-emphasis-medium/g; s/ods-button-variant-ghost/ods-button-emphasis-low/g; s/(ods-button-emphasis-[a-z]+\([[:space:]]*["'"'"']?)primary/\1brand/g' ``` The removed names come out of it as names that do not exist, and the `information`, `success` and `warning` ones are left as they were: search for them, then replace each `var()` by its semantic role and remove each override. ```sh grep -rnE -- '--ods-button-text-color-[a-z]+-high-(hover|active)|--ods-button-border-color-[a-z]+-low|--ods-button-[a-z-]*(information|success|warning)' src/ ``` **before** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-action { @include ods.ods-button-variant-default('primary'); } .my-toolbar { --ods-button-background-color-primary-hover: #003a8f; --ods-button-text-color-neutral-ghost: #4d5592; } .my-status { color: var(--ods-button-text-color-success-outline); } ``` **after** ```scss @use '@ovhcloud/ods-react/style' as ods; .my-action { @include ods.ods-button-emphasis-high('brand'); } .my-toolbar { --ods-button-background-color-brand-high-hover: #003a8f; --ods-button-text-color-neutral-low: #4d5592; } .my-status { color: var(--ods-semantic-color-content-success); } ``` ### Card **The `color` prop is removed**, with `CARD_COLOR`, `CARD_COLORS` and the `CardColor` type (see above): - `color` (or `CARD_COLOR`): use `status` (or `CARD_STATUS`). - `color="primary"`: use `status="accent"`. - No `color`: the default is now `neutral`. Set `status="accent"` to keep the v19 color; the card also paints a background now (see **Default rendering**). - `color="critical"`, `information`, `neutral`, `success`, `warning`: use `status` with the same value. - `CARD_COLORS` and `CardColor`: use `CARD_STATUSES` and `CardStatus`. To find the usages to migrate: `grep -rnE "\bCARD_COLORS?\b|\bCardColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { CARD_COLOR, Card } from '@ovhcloud/ods-react'; ... ``` **after** ```tsx import { CARD_STATUS, Card } from '@ovhcloud/ods-react'; ... ``` ### Divider **The `color` prop is removed** (it was deprecated since v19), with `DIVIDER_COLOR`, `DIVIDER_COLORS` and the `DividerColor` type. The Divider has no `status`. - `color="primary"` (or `DIVIDER_COLOR.primary`): remove the prop, it is the default rendering. - `color="neutral"` (or `DIVIDER_COLOR.neutral`): remove the prop and override the `background-color` in CSS. To find the usages to migrate: `grep -rnE "\bDIVIDER_COLORS?\b|\bDividerColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { DIVIDER_COLOR, Divider } from '@ovhcloud/ods-react'; ``` **after** ```tsx import { Divider } from '@ovhcloud/ods-react'; ``` ### File Upload **The `uploadSuccessLabel` prop of FileUploadItem is removed** (deprecated since v19.3.0). A successful upload has shown an icon instead of this label since then: the prop had no effect. Remove it. To find the usages to migrate: `grep -rn "uploadSuccessLabel" src/`. **before** ```tsx import { FileUploadItem } from '@ovhcloud/ods-react'; ``` **after** ```tsx import { FileUploadItem } from '@ovhcloud/ods-react'; ``` ### Menu **The `position` prop is removed** (deprecated since v19.7.0): use `overlayConfig={{ position }}`, which takes the same values (`'bottom-end'`, `'top'`…). If the Menu already sets `overlayConfig.position`, remove `position`: `overlayConfig` already won. In untyped JavaScript, a `position` prop is ignored and the Menu opens at its default position. To find the usages to migrate: `grep -rnE "]|=>)*)?[[:space:]]position=" src/`. A `position` written on its own line is not matched: TypeScript reports it. **before** ```tsx import { Menu, MenuContent, MenuItem, MenuTrigger } from '@ovhcloud/ods-react'; Actions Edit ``` **after** ```tsx import { Menu, MenuContent, MenuItem, MenuTrigger } from '@ovhcloud/ods-react'; Actions Edit ``` ### Message **The `color` prop is removed**, with `MESSAGE_COLOR`, `MESSAGE_COLORS` and the `MessageColor` type (see above): - `color` (or `MESSAGE_COLOR`): use `status` (or `MESSAGE_STATUS`). - `color="primary"`: use `status="accent"`. - `color="critical"`, `information`, `neutral`, `success`, `warning`: use `status` with the same value. `information` stays the default. - `MESSAGE_COLORS` and `MessageColor`: use `MESSAGE_STATUSES` and `MessageStatus`. **The `variant` prop of the Message is removed, replaced by `emphasis`, and every Message changes rendering.** `MESSAGE_VARIANT`, `MESSAGE_VARIANTS` and the `MessageVariant` type are removed with it, without deprecation period: TypeScript reports each usage, and in untyped JavaScript a `variant` attribute is ignored (and forwarded to the DOM). - `variant="default"` (or `MESSAGE_VARIANT.default`): use `emphasis="high"` (or `MESSAGE_EMPHASIS.high`). - `variant="light"` (or `MESSAGE_VARIANT.light`): use `emphasis="medium"`, or nothing, as `medium` is the default. - No `variant`: the Message rendered as `default` (tinted background) in v19; it now renders as `medium` (untinted background, the raised surface, with a light colored border). The `medium` border adds its thickness on each side: such a Message is slightly taller and wider than in v19. Add `emphasis={ MESSAGE_EMPHASIS.high }` to keep a tinted background. A `high` Message keeps the v19 `default` size: its padding gives up the thickness of its border. - `MESSAGE_VARIANTS` and `MessageVariant`: use `MESSAGE_EMPHASES` and `MessageEmphasis`. - New `low` emphasis: colored text and icon only, without background nor border. - Toaster: toasts render as `medium` (formerly `light`), with the new colors below. Nothing to change in your code. - If one of your wrappers declares its own `emphasis` prop on top of `MessageProp`, add `'emphasis'` to its `Omit` or rename it; in untyped JavaScript, an `emphasis` attribute forwarded to Message is now read as the emphasis preset. **The colors change in every emphasis**, `high` included: it is close to, but not the same as, the v19 `default` variant, and `medium` is not the same as the v19 `light` variant. The **Accent** status reads the accent roles (in v19 `default`, it was filled blue with white text). The close button keeps the same neutral look in every emphasis and status. Each emphasis reads these semantic roles, `` being `accent`, `critical`, `information`, `neutral`, `success` or `warning`: - **High**: background `--ods-semantic-color-surface--subtle`, border `--ods-semantic-color-border--subtle`, text and icon `--ods-semantic-color-content-on-`. In v19 `default`: a `075` background, no border and a `700` text. - **Medium**: background `--ods-semantic-color-surface-raised`, border `--ods-semantic-color-border--subtle`, text and icon `--ods-semantic-color-content-`. In v19 `light`: the border had the text color, a `600` step. - **Low**: transparent background and border, the **Medium** text and icon role. In the blue-jeans theme, `high` has no border. The dark themes give the three emphases the `content-on-` text. **Sass mixins and CSS custom properties are renamed**, `` being `critical`, `information`, `neutral`, `success` or `warning`, the same in both names, and `primary`, which becomes `accent` in the new names (`ods-message-variant-default('primary')`: use `ods-message-emphasis-high('accent')`): - `ods-message-variant-default()`: use `ods-message-emphasis-high()`. - `ods-message-variant-light()`: use `ods-message-emphasis-medium()`. - New `ods-message-emphasis-low()`. - `--ods-message-background-color-` and `--ods-message-text-color-`: use `--ods-message-background-color--high` and `--ods-message-text-color--high`. - `--ods-message-background-color--light` and `--ods-message-text-color--light`: use `--ods-message-background-color--medium` and `--ods-message-text-color--medium`. - The `medium` border has its own `--ods-message-border-color--medium` custom property (it used the text color in v19), and `low` its `--ods-message-text-color--low` one. To find the usages to migrate in your code: ```sh grep -rnE "\bMESSAGE_(VARIANT|COLOR)S?\b|\bMessage(Variant|Color)\b|ods-message-variant-|--ods-message-(background|text)-color-" src/ grep -rnE "|$)" src/ ``` Review each match of the second search that sets neither `variant` nor `emphasis`, on its first line or on the following ones: its rendering changes from a tinted background to `medium`. This search misses Messages imported under another name (`import { Message as OdsMessage }`): search for those names too. **before** ```tsx import { MESSAGE_COLOR, MESSAGE_STATUS, MESSAGE_VARIANT, Message, MessageBody } from '@ovhcloud/ods-react'; // tinted background in v19, medium (raised surface with a border) in v20 Your changes have been saved. Your session will expire soon. A new version is available. ``` **after** ```tsx import { MESSAGE_EMPHASIS, MESSAGE_STATUS, Message, MessageBody } from '@ovhcloud/ods-react'; Your changes have been saved. Your session will expire soon. A new version is available. ``` ### Modal **The `color` prop of `ModalContent` is removed** (it was deprecated since v19), with `MODAL_COLOR`, `MODAL_COLORS` and the `ModalColor` type. It had no visual effect: its only effect was to give the dialog the `alertdialog` role when set to `critical`. - `color="critical"` (or `MODAL_COLOR.critical`): replace it with `role="alertdialog"`. - Any other value: remove the prop. - A computed `color`: replace it with `role={ isCritical ? 'alertdialog' : undefined }`; an `undefined` role keeps the default `dialog` role. - `MODAL_COLOR` used outside `ModalContent` (in your own wrappers or maps): replace it with your own constant or a boolean such as `isCritical`. To find the usages to migrate: `grep -rnE "\bMODAL_COLORS?\b|\bModalColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { MODAL_COLOR, Modal, ModalBody, ModalContent } from '@ovhcloud/ods-react'; Are you sure you want to delete this item? ``` **after** ```tsx import { Modal, ModalBody, ModalContent } from '@ovhcloud/ods-react'; Are you sure you want to delete this item? ``` ### Pagination **A Pagination renders its children only**, and `children` is required (rendering it without children is deprecated since v19.7.0). In v19, a Pagination without children rendered a `PaginationPages`, preceded by a `PaginationPageSizeSelector` when `withPageSizeSelector` was set. `withPageSizeSelector` and `renderTotalItemsLabel` are removed with this default rendering. - A Pagination without children: add `` as its child. - `withPageSizeSelector`: add `` before ``. - `renderTotalItemsLabel`: pass what it returned as the `label` of the `PaginationPageSizeSelector`. Without `label`, the selector reads `of results`, as in v19. - In untyped JavaScript, a Pagination without children renders an empty `nav`, and the two removed props are forwarded to it. A Pagination with empty children (`null`, `undefined`) compiles and renders the same: it logs a warning once. To find the usages to migrate: ```sh grep -rnE "]|=>)*)?/>|renderTotalItemsLabel|withPageSizeSelector" src/ ``` This search misses a Pagination written over several lines that closes itself: TypeScript reports each one. **before** ```tsx import { Pagination } from '@ovhcloud/ods-react'; `of ${totalItems} servers` } totalItems={ 500 } withPageSizeSelector /> ``` **after** ```tsx import { Pagination, PaginationPageSizeSelector, PaginationPages } from '@ovhcloud/ods-react'; ``` ### Popover **The `position`, `gutter` and `sameWidth` props are removed** (deprecated since v19.7.0): move them into `overlayConfig`, under the same names and values. If the Popover already sets the same key in `overlayConfig`, remove the prop: `overlayConfig` already won. The default position stays `top`. In untyped JavaScript, these props are ignored. To find the usages to migrate, shorthand booleans (``) included: ```sh grep -rnE "(^|[[:space:]])(gutter|sameWidth)([[:space:]]*=|[[:space:]]*/?>|[[:space:]]*$|[[:space:]]+[A-Za-z])|position=\{ ?POPOVER_POSITION|]|=>)*)?[[:space:]]position=" src/ ``` A `position` written as a string on its own line is not matched: TypeScript reports it. **before** ```tsx import { POPOVER_POSITION, Popover, PopoverContent, PopoverTrigger } from '@ovhcloud/ods-react'; Show popover Popover content ``` **after** ```tsx import { POPOVER_POSITION, Popover, PopoverContent, PopoverTrigger } from '@ovhcloud/ods-react'; Show popover Popover content ``` ### Select **The `fitControlWidth` prop is removed** (deprecated since v19.7.0): use `overlayConfig={{ sameWidth }}`. The default does not change, the list takes the width of the control. - `fitControlWidth` or `fitControlWidth={ true }`: remove it. - `fitControlWidth={ false }`: use `overlayConfig={{ sameWidth: false }}`, merged into the `overlayConfig` the Select may already set. - In untyped JavaScript, `fitControlWidth` is forwarded to the DOM and the list takes the width of the control. To find the usages to migrate: `grep -rn "fitControlWidth" src/`. **before** ```tsx import { Select, SelectContent, SelectControl } from '@ovhcloud/ods-react'; ``` **after** ```tsx import { Select, SelectContent, SelectControl } from '@ovhcloud/ods-react'; ``` ### Spinner **The `color` prop is removed**, with `SPINNER_COLOR`, `SPINNER_COLORS` and the `SpinnerColor` type. The Spinner has no `status`: its color is set by the `--ods-spinner-color` CSS custom property, accent by default (the v19 primary rendering), so a Spinner without `color` renders as before. - No `color`: nothing to do, the Spinner keeps its v19 color. - `color="primary"` (or `SPINNER_COLOR.primary`): remove the prop, it is the default rendering. - `color="neutral"` (or `SPINNER_COLOR.neutral`): remove the prop and set `--ods-spinner-color: var(--ods-semantic-color-content-neutral)` in CSS. - To make the Spinner follow the text color around it, set `--ods-spinner-color: currentColor`. - Set the custom property on the Spinner, through its `className`, or on a container of yours, rather than on a global `[data-ods="spinner"]` selector: that selector would also reach the Spinners displayed by Button, Input and FileUpload. A container also reaches the loading Spinners of the Input and FileUpload placed inside it; only the Button Spinner keeps its own color, the text color of the button. - In TypeScript, setting it through the `style` prop requires a cast (`style={ { '--ods-spinner-color': 'currentColor' } as CSSProperties }`); a `className` avoids it. To find the usages to migrate: `grep -rnE "\bSPINNER_COLORS?\b|\bSpinnerColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { SPINNER_COLOR, Spinner } from '@ovhcloud/ods-react'; ``` **after** ```tsx import { Spinner } from '@ovhcloud/ods-react'; ``` ```css .my-spinner { --ods-spinner-color: var(--ods-semantic-color-content-neutral); } ``` ### Switch **The Switch component is removed** (deprecated since v19.4.0), with `SwitchItem` (and `Switch.Item`), `SWITCH_SIZE`, `SWITCH_SIZES`, the `SwitchProp`, `SwitchItemProp`, `SwitchSize` and `SwitchValueChangeDetail` types, the `@ovhcloud/ods-react/switch` entry point and the `--ods-switch-*` CSS custom properties. Replace it according to its use: - To move between views: [Tabs](https://ovh.github.io/design-system/v20.0.0/components/tabs) with the `switch` variant, which renders the same segmented control. `Switch` becomes `Tabs` with `variant={ TABS_VARIANT.switch }` around a `TabList`, each `SwitchItem` becomes a `Tab`, and the views shown under the Switch move into one `TabContent` per `Tab`, so that each tab controls its panel. `value`, `defaultValue`, `onValueChange` (which receives `{ value }`) and `size` (`sm` or `md`) keep their shape. Tabs has no `disabled` prop: set `disabled` on each `Tab`. The inactive panels stay mounted by default: set `mountStrategy="unmount"` on the Tabs to keep a view rendered only while it is shown. - To pick a mode or turn an option on or off with an immediate effect, with no view to hold: [Button Group](https://ovh.github.io/design-system/v20.0.0/components/button-group). With a single selection, it renders a radio group: give it an `aria-label`. Its `value` is an array: `value={ [value] }`, and `onValueChange` receives `{ value: [value] }`, or an empty array when the selected item is clicked again: ignore it to keep the selection. - To pick a value in a form: [Radio Group](https://ovh.github.io/design-system/v20.0.0/components/radio-group). - An override of a `--ods-switch-*` custom property has no element left to style: remove it, and style the replacement through its own custom properties. To find the usages to migrate (other libraries export a `Switch` too, so the second search is limited to the files that import ODS): ```sh grep -rnE "@ovhcloud/ods-react/switch|--ods-switch-" src/ grep -rlE "@ovhcloud/ods-react" src | xargs grep -nwE "Switch|SwitchItem|SWITCH_SIZES?|SwitchProp|SwitchItemProp|SwitchSize|SwitchValueChangeDetail" ``` **before** ```tsx import { SWITCH_SIZE, Switch, SwitchItem } from '@ovhcloud/ods-react'; setView(value) } size={ SWITCH_SIZE.sm } value={ view }> List Grid { view === 'list' ? : } ``` **after** ```tsx import { TABS_SIZE, TABS_VARIANT, Tab, TabContent, TabList, Tabs } from '@ovhcloud/ods-react'; setView(value) } size={ TABS_SIZE.sm } value={ view } variant={ TABS_VARIANT.switch }> List Grid ``` **after, for a mode with no view to hold** ```tsx import { BUTTON_GROUP_SIZE, ButtonGroup, ButtonGroupItem } from '@ovhcloud/ods-react'; value[0] && setUnit(value[0]) } size={ BUTTON_GROUP_SIZE.sm } value={ [unit] }> GB GiB ``` ### Table The `variant` prop is removed in favor of a `striped` boolean prop (default `false`): `variant` only ever had two values (`default` and `striped`). `TABLE_VARIANT`, `TABLE_VARIANTS` and the `TableVariant` type are removed with it. - `variant="default"` (or `TABLE_VARIANT.default`): remove the prop. - `variant="striped"` (or `TABLE_VARIANT.striped`): use `striped`. - `TableVariant` (e.g. in the props of a wrapper component): use `TableProp['striped']`. To find the usages to migrate: `grep -rnE "TABLE_VARIANTS?\b|TableVariant\b|]*variant=" src/`. **before** ```tsx import { TABLE_VARIANT, Table } from '@ovhcloud/ods-react'; ...
``` **after** ```tsx import { Table } from '@ovhcloud/ods-react'; ...
``` ### Tag **The `color` prop is removed**, with `TAG_COLOR`, `TAG_COLORS` and the `TagColor` type (see above): - `color` (or `TAG_COLOR`): use `status` (or `TAG_STATUS`). - `color="primary"`: use `status="accent"`. - `color="critical"`, `information`, `neutral`, `success`, `warning`: use `status` with the same value. `information` stays the default. - `TAG_COLORS` and `TagColor`: use `TAG_STATUSES` and `TagStatus`. To find the usages to migrate: `grep -rnE "\bTAG_COLORS?\b|\bTagColor\b" src/`. The `color` props are found by the shared search at the top of **Breaking changes**, which also catches a `color` written on its own line. **before** ```tsx import { TAG_COLOR, Tag } from '@ovhcloud/ods-react'; Cloud ``` **after** ```tsx import { TAG_STATUS, Tag } from '@ovhcloud/ods-react'; Cloud ``` ### Toaster **`toast.primary()` is removed**, with `TOAST_COLOR`, `TOAST_COLORS` and the `ToastColor` type (see above): - `toast.primary()`: use `toast.accent()`. - `toast.critical()`, `toast.information()`, `toast.neutral()`, `toast.success()`, `toast.warning()`: unchanged. - A `color` passed in the toast options (`toast('…', { color: 'primary' })`): use the matching helper (`toast.accent('…')`). - `TOAST_COLOR`, `TOAST_COLORS` and `ToastColor`: use `TOAST_STATUS`, `TOAST_STATUSES` and `ToastStatus`. - The `ToastController` type (the type of `toast`) has an `accent` key instead of `primary`: an object of yours typed with it, or a map of helpers keyed by status (`{ primary: … }`), renames the key. To find the usages to migrate: `grep -rnE "\bTOAST_COLORS?\b|\bToastColor\b|\bToastController\b|toast\.primary\(" src/`. **before** ```tsx import { toast } from '@ovhcloud/ods-react'; toast.primary('Your export is ready'); ``` **after** ```tsx import { toast } from '@ovhcloud/ods-react'; toast.accent('Your export is ready'); ``` ### Toggle **A Toggle renders its children only**, and `children` is required (rendering it without children is deprecated since v19.1.0). In v19, a Toggle without children rendered a `ToggleControl` and gave it its own `className`. - A Toggle without children: add `` as its child. The other props stay on the Toggle. - A `className` on a Toggle without children styled the control: move it onto the `ToggleControl`. On a Toggle with children, `className` styles the root, as in v19. - In untyped JavaScript, a Toggle without children renders an empty `label`: no control, no focusable element and no hidden `input`, so the field is no longer submitted with its form. A Toggle with empty children (`null`, `undefined`) compiles and renders the same: it logs a warning once. To find the usages to migrate: `grep -rnE "]|=>)*)?/>" src/`. This search misses a Toggle written over several lines that closes itself: TypeScript reports each one. **before** ```tsx import { Toggle } from '@ovhcloud/ods-react'; ``` **after** ```tsx import { Toggle, ToggleControl } from '@ovhcloud/ods-react'; ``` ### Tooltip **The `position` prop is removed** (deprecated since v19.7.0): use `overlayConfig={{ position }}`, which takes the same values (`TOOLTIP_POSITION`). If the Tooltip already sets `overlayConfig.position`, remove `position`: `overlayConfig` already won. The default position stays `top`. In untyped JavaScript, a `position` prop is ignored. To find the usages to migrate: `grep -rnE "position=\{ ?TOOLTIP_POSITION|]|=>)*)?[[:space:]]position=" src/`. A `position` written as a string on its own line is not matched: TypeScript reports it. **before** ```tsx import { TOOLTIP_POSITION, Tooltip, TooltipContent, TooltipTrigger } from '@ovhcloud/ods-react'; Show tooltip Tooltip content ``` **after** ```tsx import { TOOLTIP_POSITION, Tooltip, TooltipContent, TooltipTrigger } from '@ovhcloud/ods-react'; Show tooltip Tooltip content ``` ## Need help? If you hit an issue while upgrading, [open an issue on GitHub](https://github.com/ovh/design-system/issues) — especially if you see a type error that the `@types/react` deduplication above does not solve. ## Migration to v19 --- title: "Migration to v19" slug: ovhcloud-design-system-upgrade-migration-to-v19 category: generic type: overview version: 20.0.0 tokens: 443 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-migration-to-v19.txt --- # Migration to v19 Version 19 of ODS is not the direct follow-up of previous versions, it is a new library built 100% on top of [React](https://react.dev). Previous versions were providing a React version of each component too, but it was in fact a wrapper around the Web Component. Thus it was designed with the constraints related to Web Component (no virtual DOM, relying on DOM selector, ...). With this new version we got rid of those constraints, which gave us some benefits like: - component composition. - easier style customization. - easier React integration (no more `ref` needed, nor literal templates). We've also alleviated a lot of previous component restrictions, as most of them now accept React nodes instead of fixed property. For example, Button will now accept any node (text, text + icon, triple icon, ...) and won't force you to set only a label and an optional icon. Moving out of Web Component also means getting rid of the Shadow DOM. This means you now have direct access to the component DOM and it's easier to add your own style. Though this also means it is easier to break the component rendering, and some custom selectors may break from version to version (see [style customization documentation](https://ovh.github.io/design-system/v20.0.0/guides/style-customization) to know more). Regarding components, we tried to stay as close as possible to their previous interface while keeping them easy to integrate. Though, the way you'll integrate them in your React app should be rethought, to ensure you use them as real React components and not wrapped Web Components anymore. To check how to start with this new version, please follow the [Get Started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) documentation. ## 12.x to 13.x --- title: "12.x to 13.x" slug: ovhcloud-design-system-upgrade-previous-migrations-12-x-to-13-x category: generic type: overview version: 20.0.0 tokens: 138 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-12-x-to-13-x.txt --- # 12.x to 13.x # [12.1.3](https://ovh.github.io/design-system/v12.1.3/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [13.0.0](https://ovh.github.io/design-system/v13.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/12.1...release/13.0)) ## Select width The Select component fixed width when non flex has been removed. ```css width: calc(var(--ods-size-stack-08) * 11) ``` Should you need any width, you will have to set it on your component. ## 13.x to 14.x --- title: "13.x to 14.x" slug: ovhcloud-design-system-upgrade-previous-migrations-13-x-to-14-x category: generic type: overview version: 20.0.0 tokens: 142 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-13-x-to-14-x.txt --- # 13.x to 14.x # [13.0.1](https://ovh.github.io/design-system/v13.0.1/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [14.0.0](https://ovh.github.io/design-system/v14.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/13.0...release/14.0)) ## Tile interactive attribute The Tile component `interactive` attribute has been removed. ```typescript interactive?: boolean; ``` If you are using `interactive` attribute on a Tile in your project, you should remove it. ## 14.x to 15.x --- title: "14.x to 15.x" slug: ovhcloud-design-system-upgrade-previous-migrations-14-x-to-15-x category: generic type: overview version: 20.0.0 tokens: 838 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-14-x-to-15-x.txt --- # 14.x to 15.x # [14.1.1](https://ovh.github.io/design-system/v14.1.1/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [15.0.0](https://ovh.github.io/design-system/v15.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/14.0...release/15.0)) ## Text ### Dependency Add a dependency to `@ovhcloud/ods-component-text` or `@ovhcloud/ods-components`. ### Import Replace any imports like the followings: ```typescript // Component import { OsdsText } from '@ovhcloud/ods-stencil/components/text' import { OsdsText } from '@ovhcloud/ods-stencil/components/text/react' import { OsdsText } from '@ovhcloud/ods-stencil/components/text/vue' // Enums import { OdsTextLevel } from '@ovhcloud/ods-core' import { OdsTextLevelList } from '@ovhcloud/ods-core' import { OdsTextSize } from '@ovhcloud/ods-core' import { OdsTextSizeList } from '@ovhcloud/ods-core' // Interfaces import { OdsTextAttributes } from '@ovhcloud/ods-core' ``` to: ```typescript // Component import { OsdsText } from '@ovhcloud/ods-component-text' import { OsdsText } from '@ovhcloud/ods-component-text/react' import { OsdsText } from '@ovhcloud/ods-component-text/vue' // Enums import { ODS_TEXT_LEVEL } from '@ovhcloud/ods-component-text' import { ODS_TEXT_LEVELS } from '@ovhcloud/ods-component-text' import { ODS_TEXT_SIZE } from '@ovhcloud/ods-component-text' import { ODS_TEXT_SIZES } from '@ovhcloud/ods-component-text' // Interfaces import type { OdsTextAttribute } from '@ovhcloud/ods-component-text' ``` Following interfaces has been removed: * `OdsText` * `OdsTextEvents` * `OdsTextMethods` * `OdsTextLevelUnion` * `OdsTextSizeUnion` ## Textarea ### Dependency Add a dependency to `@ovhcloud/ods-component-textarea` or `@ovhcloud/ods-components`. ### Import Replace any imports like the followings: ```typescript import { OsdsTextarea } from '@ovhcloud/ods-stencil/components/textarea' import { OsdsTextarea } from '@ovhcloud/ods-stencil/components/textarea/react' import { OsdsTextarea } from '@ovhcloud/ods-stencil/components/textarea/vue' // Enums import { OdsTextAreaSize } from '@ovhcloud/ods-core' import { OdsTextAreaSizeList } from '@ovhcloud/ods-core' // Interfaces import { OdsTextAreaAttributes } from '@ovhcloud/ods-core' import { OdsTextAreaEvents, OdsTextAreaChangeEventDetail } from '@ovhcloud/ods-core' import { OdsTextAreaMethods } from '@ovhcloud/ods-core' ``` to: ```typescript // Component import { OsdsTextarea } from '@ovhcloud/ods-component-textarea' import { OsdsTextarea } from '@ovhcloud/ods-component-textarea/react' import { OsdsTextarea } from '@ovhcloud/ods-component-textarea/vue' // Enums import { ODS_TEXT_LEVEL } from '@ovhcloud/ods-component-textarea' import { ODS_TEXT_LEVELS } from '@ovhcloud/ods-component-textarea' import { ODS_TEXT_SIZE } from '@ovhcloud/ods-component-textarea' import { ODS_TEXT_SIZES } from '@ovhcloud/ods-component-textarea' // Interfaces import type { OdsTextAreaAttribute } from '@ovhcloud/ods-component-textarea' import type { OdsTextAreaEvent, OdsTextAreaChangeEvent } from '@ovhcloud/ods-component-textarea' import type { OdsTextAreaMethod } from '@ovhcloud/ods-component-textarea' ``` Following interfaces has been removed: * `OdsTextArea` * `OdsTextAreaBehavior` * `OdsTextAreaSizeUnion` ## 15.x to 16.x --- title: "15.x to 16.x" slug: ovhcloud-design-system-upgrade-previous-migrations-15-x-to-16-x category: generic type: overview version: 20.0.0 tokens: 561 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-15-x-to-16-x.txt --- # 15.x to 16.x # [15.0.1](https://ovh.github.io/design-system/v15.0.1/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [16.0.0](https://ovh.github.io/design-system/v16.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/15.0...release/16.0)) Presenting all changes, components per components will cause a very long and hard to use changelog. Instead we'll present you the fundamental changes that have been applied for all of the existing components. The same logics has been applied to each components. If you have any issue finding a specific change, feel free to contact us directly and we'll help you migrate. ## All Components ### Dependency To use the component add a dependency to either: * `@ovhcloud/ods-component-` to import only the specific component. * `@ovhcloud/ods-components` to import all components. ### Import Replace any imports like the followings: ```typescript // Previously component were imported using one of: import { OsdsSpinner } from '@ovhcloud/ods-stencil/components/spinner' import { OsdsSpinner } from '@ovhcloud/ods-stencil/components/spinner/react' import { OsdsSpinner } from '@ovhcloud/ods-stencil/components/spinner/vue' // Enums were imported from the ods-core library import { OdsSpinnerSize, OdsSpinnerSizeList } from '@ovhcloud/ods-core' // Interfaces were imported from the ods-core library import { OdsSpinnerAttributes } from '@ovhcloud/ods-core' ``` to: ```typescript // Component are now imported using one of: import { OsdsSpinner } from '@ovhcloud/ods-component-spinner' import { OsdsSpinner } from '@ovhcloud/ods-component-spinner/react' import { OsdsSpinner } from '@ovhcloud/ods-component-spinner/vue' // Enums are now imported directly from the component import { ODS_SPINNER_SIZE, ODS_SPINNER_SIZES } from '@ovhcloud/ods-component-spinner' // Interfaces are now imported directly from the component import type { OdsSpinnerAttribute } from '@ovhcloud/ods-component-spinner' ``` Some types have been removed from ODS, as they were empty or not used, if you can't find a type you were using, please contact us to see where it has been moved or how to replace it. ## 16.x to 17.x --- title: "16.x to 17.x" slug: ovhcloud-design-system-upgrade-previous-migrations-16-x-to-17-x category: generic type: overview version: 20.0.0 tokens: 555 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-16-x-to-17-x.txt --- # 16.x to 17.x # [16.6.0](https://ovh.github.io/design-system/v16.6.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [17.0.0](https://ovh.github.io/design-system/v17.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/16.0...release/17.0)) Main focus on this version has been on simplifying ODS integration in existing projects (React, Vue, JS, ...). If you have any issue finding a specific change, feel free to contact us directly and we'll help you migrate. ## All Components ### Dependency We now only publish one `ods-components` library that embed all the ODS components. You need to remove any component specific dependencies, ex: ```text "ods-component-button": "16.6.0" // should be removed ``` Instead use only one dependency: ```text "ods-components": "17.0.0" ``` ### Import You can see more details in the updated [Get Started documentation](https://ovh.github.io/design-system/v20.0.0/guides/get-started) #### Native webcomponents Using lazy-loading: ```typescript import { defineCustomElements } from '@ovhcloud/ods-components/dist/loader'; defineCustomElements(); ``` As module: ```typescript import { defineCustomElement as defineButton } from '@ovhcloud/ods-components/dist/components/osds-button'; defineButton(); ``` #### React components ```typescript import { OsdsButton, OsdsText } from '@ovhcloud/ods-components/react'; ``` #### Vue components ```typescript import { OsdsButton, OsdsText } from '@ovhcloud/ods-components/vue'; ``` #### Types and constants All types and constants are accessible from the `ods-components` library: ```typescript import type { OdsButtonAttribute } from '@ovhcloud/ods-components' import { ODS_BUTTON_SIZE, ODS_BUTTON_SIZES } from '@ovhcloud/ods-components'; ``` ### About `ods-common-xxx` libs We're trying to remove the need to add any `ods-common-xxx` lib to any project using ODS. For now, you will still need to add `ods-common-theming` as a dependency to access the `ODS_THEME_COLOR_INTENT` values. If you still ended up adding `ods-common-core` in your project, please give us the feedback so that we work on removing that need. ## 17.x to 18.x --- title: "17.x to 18.x" slug: ovhcloud-design-system-upgrade-previous-migrations-17-x-to-18-x category: generic type: overview version: 20.0.0 tokens: 390 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-upgrade-previous-migrations-17-x-to-18-x.txt --- # 17.x to 18.x # [17.2.2](https://ovh.github.io/design-system/v17.2.2/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) to [18.0.0](https://ovh.github.io/design-system/v18.0.0/?path=/story/ovhcloud-design-system-what-s-new-changelog--page) ([compare](https://github.com/ovh/design-system/compare/release/17.0...release/18.0)) If you have any questions or issues regarding the new version, feel free to reach us directly. ## Libraries The following libs have been removed: - @ovhcloud/ods-cdk - @ovhcloud/ods-common-core - @ovhcloud/ods-common-stencil - @ovhcloud/ods-common-testing - @ovhcloud/ods-common-theming - @ovhcloud/ods-theme-blue-jeans If you were using part of them, please reach out to us so that we can get more information about your usage. To use the new theme, replace `ods-theme-blue-jeans` with the following: ```typescript import '@ovhcloud/ods-themes/default'; ``` ## Design tokens Design tokens are now accessible through the `@ovhcloud/ods-themes` lib. The list of available tokens has been updated with the latest design changes and match what you may find on the Figma screens. ## Components As each component was refactored, there are too many changes to list everything here. The main common breaking change is the following: `osds-xxx` component is now `ods-xxx` A complete list of changes and a guide about how to migrate is available per component in the v18 documentation. Use the top-left version selector to move to the latest v18.x documentation where you'll find the latest up-to-date information. ## Troubleshooting --- title: "Troubleshooting" slug: ovhcloud-design-system-troubleshooting category: generic type: overview version: 20.0.0 tokens: 912 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-troubleshooting.txt --- # Troubleshooting *Common issues met when integrating ODS, and how to fix them. If yours is not listed, check the [F.A.Q.](https://ovh.github.io/design-system/v20.0.0/guides/faq) or [open an issue on GitHub](https://github.com/ovh/design-system/issues).* ## TS2307: Cannot find module '@ovhcloud/ods-react' or its corresponding type declarations. Check that you're using the `bundler` [module resolution](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#--moduleresolution-bundler) in your `tsconfig.json`. ```typescript "moduleResolution": "bundler" ``` ## My popover/tooltip is not displayed correctly Check that you're not using a `Fragment` as your trigger. The following will **not** work properly: ```tsx <> ... ``` Replace the `Fragment` with an actual node: ```tsx ... ... ``` ## Overlay elements are not displayed correctly in a drawer/modal `Modal` and `Drawer` components have a `z-index` greater than other overlay components. This is to prevent those to appear behind an open modal/drawer. To allow overlay elements to correctly render inside a modal/drawer, add the `createPortal={ false }` attribute to the `Content` component of the overlay element. See [Drawer example](https://ovh.github.io/design-system/v20.0.0/components/drawer) and [Modal example](https://ovh.github.io/design-system/v20.0.0/components/modal). ## Icons are not displayed Ensure you did import the fonts in your application, check the [get started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) page to read more about how to achieve this. ## Warning: Function components cannot be given refs With React 18, when using components enabling dynamic component (through the `as` attribute), you may encounter the following error message in the console: ```text Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()? ``` This means you're passing a function component to the `as` attribute and it needs to be wrapped by a `forwardRef` to be able to manage the `ref` correctly. With React 19, `ref` is a regular prop and no warning is shown, but your component still has to pass the `ref` it receives down to its DOM element, as the example below does. ```tsx import { Link } from '@ovhcloud/ods-react'; import { forwardRef, useRef } from 'react'; const DummyLink = forwardRef(({ children, ...props }, ref) => { return ( { children } ); }); const MyApp = () => { const linkRef = useRef(null); return (
... ...
); }; ``` ## Error during server-side rendering (Next.js App Router) ODS components rely on React state, effects and browser APIs, so they cannot render as React Server Components. Use them from client components, marked with the `'use client'` directive, and keep the theme imports in your root layout. If the error is `document is not defined` and the page renders a `Toaster`, it comes from its default portal into `document.body`: pass `createPortal={ false }`, or render the `Toaster` only once the page is mounted in the browser. See [Get Started](https://ovh.github.io/design-system/v20.0.0/guides/get-started) for the full setup. ## FAQ --- title: "FAQ" slug: ovhcloud-design-system-f-a-q category: generic type: overview version: 20.0.0 tokens: 975 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-f-a-q.txt --- # FAQ *Welcome to the F.A.Q. section of the OVHcloud Design System (ODS).* *Here, we aim to address common questions and provide helpful guidance for developers.* ## How can I contribute? OVHcloud Design System is an evolving project, and we welcome contributions from the community. By keeping our repository open source, we aim to make it easier for anyone to suggest improvements, fix issues, or share ideas. Whether it’s a small fix or a new feature, every contribution helps improve the quality and usability of the system. We appreciate the time and effort of anyone who chooses to take part. Please note that while we welcome contributions, we encourage you to discuss major changes with our team to ensure alignment with the project's goals and overall quality. Additionally, if you're interested in proposing a new feature, please reach out to us first to avoid duplicating effort, as we may already be working on a similar development. Refer to our project [README](https://github.com/ovh/design-system?tab=contributing-ov-file#contributing-to-ods-project) to learn more about installation and pre-requisites. ## How are releases managed? The OVHcloud Design System follows a structured release process to deliver improvements regularly while letting teams adopt updates at their own pace. **Patch releases** deliver critical fixes or small improvements and can be adopted immediately. **Minor releases** introduce new non-breaking features, and can deprecate an element when a replacement exists. **Major releases** contain breaking changes and their migration guide. Releases are published several times a year based on user needs and product evolution. We support two major versions at the same time: - The current major version receives full support (features, improvements, fixes). - The previous major version receives maintenance support for six months (critical fixes only). - Older versions are no longer supported. Breaking changes follow these rules: - An element deprecated in a minor release is marked as "Deprecated" in the documentation, paired with migration guidance, and removed in the next major release. - A major release can also remove or rename an element that was not deprecated before. - Every removal or rename comes with a before/after example in the migration guide of the major release. Teams may upgrade at their own pace and can skip versions. We recommend pinning a specific ODS version in your project to ensure consistent behavior. ## I can't find a component I need ODS provides base components that you can build on top of and implement in various contexts. If you need a new component, we recommend working with the design team to request and design the component to ensure it aligns with the ODS guidelines. ## Is my browser supported? ODS supports the latest 2 versions of the following browsers: - Google Chrome - Microsoft Edge - Mozilla Firefox - Opera - Safari ## Can I use another CSS framework on top of ODS? You can use any CSS framework on top of ODS. Note that some imperative CSS frameworks like Bootstrap may override ODS styling. Ensure compatibility by testing the integration in your project. ## What about Web Components and Vue? Starting from v19, ODS has moved to fully React-based components. Web Components and the Vue wrapper are only available in v18.x, which is no longer supported: it receives neither new features nor fixes. If you still need to access documentation about Web Components or Vue, use the version selector at the top left to switch to the latest 18.x documentation, where you'll find the most up-to-date information. ## Something does not work as expected Common integration issues (TypeScript resolution, overlays, icons, refs, server-side rendering) and their fixes are gathered in the [Troubleshooting](https://ovh.github.io/design-system/v20.0.0/guides/troubleshooting) guide. ## formatPrice --- title: "formatPrice" slug: helpers-formatprice category: generic type: overview version: 20.0.0 tokens: 109 source: https://ovh.github.io/design-system/v20.0.0/llms/helpers-formatprice.txt --- # formatPrice Format a numeric value to a price matching given locale format with expected currency. ## Arguments | Argument | Type | Default | Description | |---|---|---|---| | `value` | `number` | - | The numeric value to format. | | `locale` | `string` | 'fr-FR' | The locale to use. | | `currency` | `string` | 'EUR' | The currency expected. | ## Documentation pages - [Documentation](./helpers-formatprice--documentation.txt) ## formatPrice --- title: "formatPrice" slug: helpers-formatprice category: generic type: documentation version: 20.0.0 tokens: 253 source: https://ovh.github.io/design-system/v20.0.0/llms/helpers-formatprice--documentation.txt --- # formatPrice ## Specifications Format a numeric value to a price matching given locale format with expected currency. | Argument | Type | Default | Description | |---|---|---|---| | `value` | `number` | - | The numeric value to format. | | `locale` | `string` | 'fr-FR' | The locale to use. | | `currency` | `string` | 'EUR' | The currency expected. | - [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) ## Examples ### Default ```tsx <>{ formatPrice(123456.789) } ``` ### Locales ```tsx <>

France: { formatPrice(123456.789, 'fr-FR') }

Germany: { formatPrice(123456.789, 'de-DE') }

Arabic: { formatPrice(123456.789, 'ar-EG') }

India: { formatPrice(123456.789, 'en-IN') }

``` ### Currencies ```tsx <>

Euro: { formatPrice(123456.789, 'fr-FR', 'EUR') }

Dollar: { formatPrice(123456.789, 'fr-FR', 'USD') }

Yen: { formatPrice(123456.789, 'fr-FR', 'JPY') }

``` ## formatRelativeTime --- title: "formatRelativeTime" slug: helpers-formatrelativetime category: generic type: overview version: 20.0.0 tokens: 113 source: https://ovh.github.io/design-system/v20.0.0/llms/helpers-formatrelativetime.txt --- # formatRelativeTime Format a date to a human readable relative time (like 'a month ago'). ## Arguments | Argument | Type | Default | Description | |---|---|---|---| | `date` | `Date` | - | The date to format. | | `locale` | `string` | 'en-GB' | The locale to use. | | `option` | `RelativeTimeFormatOptions` | - | Language-sensitive formatting options. | ## Documentation pages - [Documentation](./helpers-formatrelativetime--documentation.txt) ## formatRelativeTime --- title: "formatRelativeTime" slug: helpers-formatrelativetime category: generic type: documentation version: 20.0.0 tokens: 283 source: https://ovh.github.io/design-system/v20.0.0/llms/helpers-formatrelativetime--documentation.txt --- # formatRelativeTime ## Specifications Format a date to a human readable relative time (like 'a month ago'). | Argument | Type | Default | Description | |---|---|---|---| | `date` | `Date` | - | The date to format. | | `locale` | `string` | 'en-GB' | The locale to use. | | `option` | `RelativeTimeFormatOptions` | - | Language-sensitive formatting options. | - [Intl.RelativeTimeFormatOptions](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) ## Examples ### Default ```tsx <>{ formatRelativeTime(new Date()) } ``` ### Locales ```tsx <>

France: { formatRelativeTime(new Date(), 'fr-FR') }

Germany: { formatRelativeTime(new Date(), 'de-DE') }

Arabic: { formatRelativeTime(new Date(), 'ar-EG') }

India: { formatRelativeTime(new Date(), 'en-IN') }

``` ### Format option ```tsx <>

Long: { formatRelativeTime(new Date(), 'en-US', { style: 'long'}) }

Short: { formatRelativeTime(new Date(), 'en-US', { style: 'short'}) }

Narrow: { formatRelativeTime(new Date(), 'en-US', { style: 'narrow'}) }

``` ## Components --- title: "Components" slug: recipes-components category: generic type: overview version: 20.0.0 tokens: 680 source: https://ovh.github.io/design-system/v20.0.0/llms/recipes-components.txt --- # Components Proven UI patterns (recipes) combining several ODS components. Each recipe ships copyable source code in the online documentation: https://ovh.github.io/design-system/v20.0.0/recipes/components ## Chat Tags: ai, interactive ODS components used: Avatar, Button, Clipboard, ClipboardTrigger, FileThumbnail, Icon, MessageBubble, Text, PromptInput, PromptInputControls, PromptInputFileUploadButton, PromptInputFiles, PromptInputSendButton, PromptInputTextControl ## Config Tile Tags: interactive ODS components used: Badge, Icon, Quantity, QuantityControl, QuantityInput, Radio, RadioControl, RadioGroup, RadioLabel, Select, SelectContent, SelectControl, Text, Tile, formatPrice ## Dashboard Card Tags: interactive, presentation ODS components used: Badge, Button, Card, Clipboard, ClipboardControl, ClipboardTrigger, Divider, Editable, EditableActions, EditableDisplay, EditableDisplayEmpty, EditableInput, Icon, Input, Link, Menu, MenuContent, MenuItem, MenuTrigger, Text, Tooltip, TooltipContent, TooltipTrigger ## Data Grid Tags: interactive, presentation ODS components used: Button, Clipboard, ClipboardControl, ClipboardTrigger, DataTable, DataTableBody, DataTableEmpty, DataTableHead, Icon, Input, Menu, MenuContent, MenuGroup, MenuItem, MenuTrigger, Pagination, PaginationPageSizeSelector, PaginationPages, Popover, PopoverContent, PopoverTrigger, TreeView, TreeViewNode, TreeViewNodes, ## Data Grid With Query Filter Tags: interactive, presentation ODS components used: DataTable, DataTableBody, DataTableEmpty, DataTableHead, Pagination, PaginationPages, QueryFilter, QueryFilterClear, QueryFilterContent, QueryFilterControl, QueryFilterTags, formatRelativeTime, ## Email Field Tags: form, interactive ODS components used: FormField, FormFieldHelper, FormFieldLabel, FormFieldLabelSubLabel, Input, Select, SelectContent, SelectControl, Text ## Feature List Tags: presentation ODS components used: Icon, Text, Tooltip, TooltipContent, TooltipTrigger ## Feature List Product Card Tags: cart, interactive, presentation, product ODS components used: Badge, Card, Icon, Link, Select, SelectContent, SelectControl, Text, Tooltip, TooltipContent, TooltipTrigger, formatPrice ## Media Product Card Tags: product, presentation ODS components used: Card, Icon, Link, Medium, Text ## Order Button Tags: cart, interactive ODS components used: Icon ## Range Input Tags: form, interactive ODS components used: Input, Range ## Status Message Tags: interactive, status ODS components used: Button, Message, MessageBody, MessageIcon ## Status Modal Tags: dialog, interactive, status ODS components used: Button, Modal, ModalBody, ModalContent, ModalHeader, ModalTrigger, Text