Developing

You can start developing with Odyssey using our component code guidelines and our React library and tools. Odyssey’s React library supports everything in the Odyssey UI Kit’s Figma libraries.

Install the Odyssey-React-MUI package and peer dependencies


                                                        
                                                        
                                                            yarn add @okta/odyssey-react-mui @emotion/react
                                                        
                                                            

Include fonts:


                                                        
                                                        
                                                            <link rel="preconnect" href="https://fonts.googleapis.com" />
                                                        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
                                                        <link
                                                          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap"
                                                          rel="stylesheet"
                                                        />
                                                        
                                                            

Import named ESM exports:


                                                        
                                                        
                                                            import { PasswordField } from "@okta/odyssey-react-mui";
                                                        
                                                            

Add the Odyssey OdysseyProvider around your whole app:


                                                        
                                                        
                                                            import { OdysseyProvider } from "@okta/odyssey-react-mui";
                                                        
                                                        const YourAppRoot = ({ children }) => (
                                                          <OdysseyProvider>{children}</OdysseyProvider>
                                                        );
                                                        
                                                            

Add Material-UI components not exported from Odyssey with Odyssey styling or add your own theme to MUI:


                                                        
                                                        
                                                            $ yarn add @mui/material
                                                        
                                                            

                                                        
                                                        
                                                            import { OdysseyThemeProvider } from "@okta/odyssey-react-mui";
                                                        
                                                        import { myMaterialUiTheme } from "./myMaterialUiTheme";
                                                        
                                                        const YourAppRoot = ({ children }) => (
                                                          <OdysseyThemeProvider theme={myMaterialUiTheme}>{children}<OdysseyThemeProvider>
                                                        );
                                                        
                                                            

Odyssey packages

Package/README

Description

@okta/odyssey-design-tokens

Design tokens

@okta/browserslist-config-odyssey

Browserlist config

@okta/odyssey-babel-preset

Babel preset

@okta/odyssey-babel-loader

Babel webpack loader

@okta/odyssey-react-mui

React MUI components

Learn about Odyssey design tokens

Before starting to build with Odyssey, familiarize yourself with our design tokens to reduce ambiguity between design intentions and engineering reality.

Learn about Odyssey and MUI

Odyssey is built on MUI, a front-end React framework that provides a solid foundation for building modern, flexible, and accessible components. MUI is invisible from the design side, but understanding MUI is key to getting the most out of Odyssey in React.

Read Understanding MUI.

Components

Components are published in an ESM format transpiled for the modern browsers within the Okta supported browser list. These modules can be served directly to evergreen browsers for simple applications, or further transpiled, bundled, and polyfilled for advanced use cases and browser support targets.

Browser support

Odyssey browser support mirrors Okta supported platforms, browsers, and operating systems, with the exception of IE 11.

 

Migrating to Odyssey 1.0

Update to Odyssey 1.0 through our THI migration plan:

  • Migrate legacy Odyssey apps to 1.0
  • Migrate Gen3 to Gen4 (building tooling and runtime library)
  • Update the UI to Odyssey 1.0

Learn more about migration.

Have questions or need support?

Oktanauts can use the following resources when building with Odyssey componentsL

  • Check the Odyssey 1.0 FAQs.
  • Join #odyssey in Slack to ask questions and stay up to date about the design system.
  • Attend Odyssey Office Hours on Mondays and Wednesdays from 1-1:30 p.m. PT / 4-4:30 p.m. ET.
  • Submit bug reports and feature requests to the Odyssey Jira board
  • Request a new component using the Odyssey component proposal.