A highly composable side navigation component that supports nested views.
yarn add @atlaskit/side-navigation#119150
5ae7ca716c848 -
Migrated from @emotion/react to @compiled/react in order to improve performance, align with
the rest of the Atlaskit techstack, and support React 18 Streaming SSR.
Please note, in order to use this version of @atlaskit/side-navigation, you will need to ensure
that your bundler is configured to handle .css imports correctly. Most bundlers come with
built-in support for .css imports, so you may not need to do anything. If you are using a
different bundler, please refer to the documentation for that bundler to understand how to handle
.css imports.
For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS.
#117363
10a0f7f6c2027 -
This package's peerDependencies have been adjusted for react and/or react-dom to reflect the
status of only supporting React 18 going forward. No explicit breaking change to React support has
been made in this release, but this is to signify going forward, breaking changes for React 16 or
React 17 may come via non-major semver releases.
Please refer this community post for more details: https://community.developer.atlassian.com/t/rfc-78-dropping-support-for-react-16-and-rendering-in-a-react-18-concurrent-root-in-jira-and-confluence/87026
5033cb80b3765 -
Updates internal animation logic to leverage static animation timing names, rather than arbitrary
values.55f6cfd027e9e -
Revert the Compiled migration introduced in v4.0.0, as it caused laggy animations in nested
navigation. The migration will be reintroduced once @atlaskit/motion has been updated to use
Compiled.4660ec858a305 -
Update React from v16 to v18#95255
155e525c3b156 -
Migrated from @emotion/react to @compiled/react in order to improve performance, align with
the rest of the Atlaskit techstack, and support React 18 Streaming SSR.
Please note, in order to use this version of @atlaskit/side-navigation, you will need to ensure
that your bundler is configured to handle .css imports correctly. Most bundlers come with
built-in support for .css imports, so you may not need to do anything. If you are using a
different bundler, please refer to the documentation for that bundler to understand how to handle
.css imports.
For more information on the migration, please refer to RFC-73 Migrating our components to Compiled CSS-in-JS.
910a3ef2381d3 -
Add isSSRPlaceholderEnabled prop for side and top nav v33aef43e98843a -
Internal change to how styles are applied. There is no expected visual change.5c96046203b6f -
Tag top and side navigation components for SSR placeholder replacement2dd22b00bedaa -
Add props for handling server rendered components and data-vc57f451bda8919 -
Adds side-effect config to support Compiled css extraction in third-party appsa4cb190f3a282 -
Side navigation, keyboard focus should appear on first interactive element which is Go back
button and when Go back control is activated, focus should appear on the triggered element.21bfb50836bad -
Migrated to use new iconography behind a feature flag.778c15c1d279a -
[ux] Removed feature flag
platform.design-system-team.side-navigation-tokenised-typography-styles resulting in minor
visual changes to typography.#127511
db30e29344013 -
Widening range of react and react-dom peer dependencies from ^16.8.0 || ^17.0.0 || ~18.2.0
to the wider range of ``^16.8.0 || ^17.0.0 || ^18.0.0` (where applicable).
This change has been done to enable usage of react@18.3 as well as to have a consistent peer
dependency range for react and react-dom for /platform packages.
a8bd419fd70b9 -
Explicitly set jsxRuntime to classic via pragma comments in order to avoid issues where jsxRuntime
is implicitly set to automatic.10ab455ab24b -
[ux] We are testing a visual change behind a feature flag. The letter spacing of side navigation
header title changes. If this change is successful it will be available in a later release.ba7dc54866b9 -
Update footer to use logical property for padding. Internal changes to tokenise typography values.7cce9cbf2f08 -
Internal changes to how text is rendered. There is no expected visual change.d100ca42f46 - Push
model consumption configuration done for these packages#41355
cd1c813da18 - Menu
items now have a secondary selected state (border or notch), this was previously feature flagged
for Atlassian experiences and is now available for everyone.
This change makes all menu items are now relatively positioned, if you had any child elements that leaned on this behaviour your experiences will now be broken!
For example the below code code previously the div would be positioned relatively to the menu
group element. Now, it is positioned relatively to the button item element.
<MenuGroup>
<ButtonItem>
<div style={{ position: 'absolute', top: '100%' }} />
</ButtonItem>
</MenuGroup>
As a path forward you should not be leaning on this behaviour. If you need a popup experience use
@atlaskit/dropdown-menu or @atlaskit/popup.
e3b28897c5f - Internal
code changes. There is no expected change in behaviour.cac6bbb702d - The
internal composition of this component has changed. There is no expected change in behavior.cf66b43d67a - Updated
spacing of Side Navigation components to ensure token values and fallbacks are matching. When used
with space tokens enabled, there is no visual difference with the previous release of Side
Navigation. When used without space tokens enabled there will be a slight visual difference; we
recommend enabling space tokens if they are not already enabled to resolve this.ee296a14a87 - Adds the
showTopScrollIndicator prop to the nestable navigation content component. This prop should be
used only when needed to distinctly separate the side navigation header from the side navigation
content.0af122e7d0f - [ux]
Prop isList in Section component allows to add <ul> and <li> elements around the items to
better semantic markup if it is a list of items967dd926bfc - Updates
all navigation components to use border/shape tokens. This is a no-op as these tokens are not
enabled in product.4757acc0f98 - Internal
change to use space tokens for spacing properties. There is no visual change.774ed69ecef - Internal
changes to use space tokens for spacing values. There is no visual change.e7ea6832ad2 - Bans the
use of React.FC/React.FunctionComponent type in ADS components as part of the React 18 migration
work. The change is internal only and should not introduce any changes for the component
consumers.d518f0e34b9 - [ux] We
are testing a selected indicator change to menu, dropdown-menu, and side-navigation packages
behind an internal feature flag. If successful this will be released in a later minor release.56507598609 - Skip
minor dependency bump2e01c9c74b5 - DUMMY
remove before merging to master; dupe adf-schema via adf-utilsf7f852b0a4f - Migrated
use of gridSize to space tokens where possible. There is no expected visual or behaviour change.3ca97be0c06 - Internal
change only. Replace usages of Inline/Stack with stable version from @atlaskit/primitives.#30362
62c9d42799c - [ux] The
Footer component will now warn a user if they are relying on a deprecated API. The cssFn,
onClick and component are all considered deprecated APIs for Footer.
Additionally, the space between icons and content has been shifted form 16px to 12px. This
matches @atlaskit/menu.
These APIs will be removed from Footer in a future major release. To suppress the warning you can
choose to use the useDeprecatedApi={false} prop which opts into the new API.
18aeca8c199 - Internal
change to update token references. There is no expected behaviour or visual change.eadbf13d8c0 - Updated
usages of Text, Box, Stack, and Inline primitives to reflect their updated APIs. There are
no visual or behaviour changes.#28090
caa68aad0fd - Internal
changes around styles:
f96f3ebd861 - [ux] Use
color.background.neutral.subtle token to represent transparent background.fbe4c12c94b - DTR-995
fix move page dialog bg color5c065ba2010 - Improve
state management to allow detection of invalid stack state. Add prop onUnknownNest to allow
handling of invalid stack state.5f36f2ce46d - Adds a
defensive css() function wrapping to many of the style calls in the side-navigation package.
This is expected to help fix an issue with certain styles in side navigation not appearing if
consumed when different versions of @emotion are present on the page.02e2f7aacef - Updates
@emotion/core to @emotion/react; v10 to v11. There is no expected behavior change.b2767947029 - Internal
code change turning on new linting rules.85ca75319b1 - Move
side-navigation docs to Constellation (atlassian.design)62edf20ab1e - Migrates
all usage of brand tokens to either selected or information tokens. This change is purely for
semantic reasons, there are no visual or behavioural changes.0f8fe0b80aa - Adds
deprecated status to cssFn prop. Please avoid using this prop as we intend to remove the prop
completely in a future release.19d72473dfb - The
no-unsafe-design-token-usage eslint rule now respects the new token naming conventions when
auto-fixing by correctly formatting token ids.f460cc7c411 - Builds
for this package now pass through a tokens babel plugin, removing runtime invocations of the
tokens() function and improving bundle size.#14777
213bfd77e61 - The DOM
structure of menu item components has been flattened. If you used CSS hacks (via className or
cssFn) that targetted specific DOM nodes you may be broken.
Previously the structure looked like:
<button>
<div> // <-- this intermediate div has been removed
<span>
<span />
</span>
</div>
</button>
Now it looks like:
<button>
<span>
<span />
</span>
</button>
e4f332d8697 - Internal
refactor to update style declarations to match menu changes.
#13864
0e1894c8eb0 -
Instrumented side navigation with the new theming package, @atlaskit/tokens.
New tokens will be visible only in applications configured to use the new Tokens API (currently in alpha). These changes are intended to be interoperable with the legacy theme implementation. Legacy dark mode users should expect no visual or breaking changes.
7c843858398 - [ux]
LinkItem and CustomItem now have correct blue text color when selected and the href has visited7727f723965 - Internal
change to the release model from continous to scheduled release. There are NO API CHANGES in
this release.#10255
4e72825fa89 -
JET-1156:
VAR_SEPARATOR_COLOR to override separator color when using custom backrounds in side
navigation.VAR_SCROLL_INDICATOR_COLOR to override menu scroll indicator color when using custom
backrounds in side navigation.240c4120435 - Side
navigation now uses the new common utility to calculate scrollbar width for offsetting keylines.101b102ed33 - Fix
disabled state; menu items with icons after the text should have height of 40px79a40dec30 -
Breaking Adjusts the API of the cssFn prop used in both menu and side-navigation. The prop now
no longer exposes the currentStyles to the user in the callback and instead only provides the
current state. Users no longer need to spread the currentStyles into their components when
overriding. This change also resolves a bug where cssFn overrides did not always take precedence
correctly over the default component styles.5f58283e1f - Export
types using Typescript's new "export type" syntax to satisfy Typescript's --isolatedModules
compiler option. This requires version 3.8 of Typescript, read more about how we handle Typescript
versions here: https://atlaskit.atlassian.com/get-started Also add typescript to
devDependencies to denote version that the package was built with.e55c4eb5a8 - [ux]
Earlier left sidebar was getting focus while clicking on it. We have removed focus ring to fix
this issue.#3885
6c525a8229 - Upgraded
to TypeScript 3.9.6 and tslib to 2.0.0
Since tslib is a dependency for all our packages we recommend that products also follow this tslib upgrade to prevent duplicates of tslib being bundled.
a3c91f82f6 - Add
tabindex=0 to nested container which makes it focusable when interacting with keyboard.308ad47024 - Passes
cssFn throught to NestingItem so that its styles can be customised159e0808a5 - Updates
the background color of NestingItem, ButtonItem and LinkItem so that it can work with the
Onboarding component. Hover and selected states will appear darker and they provide better
contrast against normal items.5b3383fe67 - Nesting
transitions will no longer occur if a modifier key such as Shift or Control is detected while
clicking on a nesting item in the side-navigation.c7e637753f - Removed
unused export of SIDEBAR_DEFAULT_WIDTH. It was added when page-layout wasn’t complete. Now
page-layout is fairly mature, that’s why this export isn’t required anymore.87f4720f27 - Officially
dropping IE11 support, from this version onwards there are no warranties of the package working in
IE11. For more information see:
https://community.developer.atlassian.com/t/atlaskit-to-drop-support-for-internet-explorer-11-from-1st-july-2020/395345217dcfa4d - Remove
opacity from side-navigation seperators that appear when the container scrolls. The color is the
same, just without the alpha channel.d674e203b3 - Previously
Menu items controlled their own margin spacing which caused issues when trying to use them outside
of Menu. Now we have moved Menu item margin styles into the Section component so now the Section
dictates the spacing around child items. We had to update Side Navigation to control its child
item margins as well.649f69b6d7 - Patch all
packages that are used by confluence that have a broken es2019 dist6ef13297b2 - Fixes
scroll indicator not being the correct width when lazy loading large amounts of nav items.07b2d8c491 - FIX:
NestedItem iconAfter will now display always and right arrow will show up and replace it on
hover[minor]7e408e4037:
BREAKING - renames elemBefore and elemAfter props to iconBefore and iconAfter on all
item components.-
[minor]d1ef176211:
BREAKING - renames section heading to heading item- [minor]41760ea4a6:
BREAKING: modifies custom item component to take only valid HTML attributes. This means
wrapperClass is now known as className.-
[minor]b3441cd210:
BREAKING - removes render go back item component from nesting item and nestable navigation content. Replaces with overrides equivalent.- [minor]e67a87dbf2:
BREAKING - renames customItemComponent prop on nesting item to component.
[patch]724935beab:
Adds loading section component to use when wanting lazy load menu items.- [patch]6453c8de48:
Exposes typescript types alongside components.- [patch]3bfb526c22:
Corrects disabled nesting item to not show the after element on hover.- [patch]7a9bf45e58:
Fixes section heading to correctly compose passed in css function.- [patch]d8dc3813c1:
Fixes section heading spacing.- [patch]684ee794d6:
Improves type safety with custom item by using TypeScript generics to pass on the custom component types to the parent.- Updated dependencies 7e408e4037:
Updated dependencies 5633f516a4:
Updated dependencies 6453c8de48:
Updated dependencies 168b5f90e5:
Updated dependencies e4dde0ad13:
Updated dependencies 41760ea4a6:
Updated dependencies 0c270847cb:
Updated dependencies 971e294b1e:
Updated dependencies 684ee794d6:
Updated dependencies 109004a98e:
Updated dependencies b9903e773a:
Updated dependencies 286770886d:
Updated dependencies 2c1b78027c:
Updated dependencies fb3ca3a3b2:
[minor]7ecbf8d0bd:
Breaking:
label prop.Accessibility Changes
navigation landmark for use with screen readers; this landmark is
further described by the label prop to differentiate it from AtlassianNavigation-
[minor]1fea6757c4:BREAKING - NavigationFooter component has been renamed to Footer.
[patch]7b230682c2:
Adds controlled component support. It is now possible to use the stack and onChange props on
the NestableNavigationContent component to dictate which view is active. This is useful for use
cases where nested views need to be changed programmatically.
const [stack, setStack] = useState([]);
<SideNavigation>
<NestableNavigationContent
onChange={setStack}
stack={stack}
>
...
</NestableNavigationContent>
</SideNavigation>
This is supported by a new hook called useShouldNestedElementRender(). All components that can
be composed with NestableNavigationContent use it out of the box, but if you want to compose
your own components you may have to opt into it else you will see your component rendering on
every view (which may or may not be what you want).
import { useShouldNestedElementRender } from '@atlaskit/side-navigation';
const MyCustomComponent = () => {
const { shouldRender } = useShouldNestedElementRender();
if (shouldRender) {
return <div>hello world!</div>;
}
// If your component takes children you'll probably want to return children here instead.
return null;
};
<SideNavigation>
<NestableNavigationContent>
<MyCustomComponent />
</NestableNavigationContent>
</SideNavigation>
Fixes horizontal alignment for item icons in relation to the app switcher in the horizontal navigation bar.- [patch]1a3192c1c1:
Introduces skeletons for heading and item components.- [patch]43353900f7:
Corrects and consolidates colors for item and side navigation components.- [patch]c60324c748:
Adds new Footer component. Ensures this and the Header component come with baked in styles for you to use out of the box.- [patch]c56d86d95c:
Adds scrolling indicators to the scrollable container component.
Updated dependencies ed8d8dea65:
Updated dependencies db2f869556:
Updated dependencies 81ea791176:
Updated dependencies 6e2dda87f4:
Updated dependencies e57c4aa96d:
Updated dependencies 8c9e4f1ec6:
Updated dependencies 89d35b919a:
Updated dependencies 083cfbaeb4:
Updated dependencies 46d95777ef:
Updated dependencies 9b264df34d:
[minor]dce5efb012:
Support forward ref on side-navigation primitives
[patch]4da717940e:
Refactor side-navigation nesting logic to support async components- [patch]93709ca7eb:
Adds testId to NestingItem- Updated dependencies
66dcced7a0:
Updated dependencies fd5292fd5a:
Updated dependencies fd5292fd5a:
Updated dependencies eea5e9bd8c:
Updated dependencies 7a6e5f6e3d:
Updated dependencies fd5292fd5a:
[minor]e1416630ed:
BREAKING: Renamed exported components
MainSection to NavigationContentNestingTransitionProvider to NestableNavigationContentNestableNavigationContent does not need to be wrapped by a MainSectionHeaderSection to NavigationHeaderFooter to NavigationFooterImprove behaviour of scrollabe sections:
ScrollableSection now shows an overflow indicator when items are scrolled off the top borderAPI changes and design changes for side-navigation
SectionHeader has been renamed to SectionHeadingSIDEBAR_DEFAULT_WIDTH has been exportedItem has been removed and replaced with CustomItem, ButtonItem, LinkItem which are thin
wrappers around their @atlaskit/menu counterpartsGoBackItem has been exportedtestId props have been added to more components with side-navigationCustomItem, ButtonItem and LinkItem themselves have a cssFn prop exposed which will
allow custom styles to be applied and combined with side-navigation defaultsHeading and Footer have been updated to allow consumers to pass in their own custom
componentsBREAKING: id prop is now required on NestingItems
The back button in nested views can now be customised
Go Back button will be shownrenderDefaultBackButton on the NestableNavigationContent to set a new defaultrenderBackButton on each NestingItem to specifically set a back trigger for exiting the
view it controlsThe link form of nested views can now be customised
customItemComponent to pass in a functional/class component that adds extra behaviour
around the link (see @atlaskit/menu for examples on how to configure CustomItems)[patch]babae63a7b:
NestingItem & GoBackItem when it is exitingNestingItem and GoBackItem resulting in an unwanted double
navigationNestingItem not calling back on clickid prop to NestingItem- Updated dependencies
1f9c4f974a:Updated dependencies b80c88fd26:
Updated dependencies 9ec1606d00:
Updated dependencies 0603860c07:
Updated dependencies 1b3069e06b:
[patch]6548261c9a:
Remove namespace imports from React, ReactDom, and PropTypes- Updated dependencies 6548261c9a:
[patch]f3433f2096:
NestingItem now has an extra prop isInitiallyOpen that allows the side-navigation to initially
render a particular nested view
isInitiallyOpen prop must be
set on all parent NestingItems in the navigation tree-
[patch]a806cde423:Iterative updates to side-navigation:
Updated dependencies e0e91e02a6:
Updated dependencies c0102a3ea2:
Updated dependencies 166d7b1626:
[patch]0e6929fbb9:
Fixes a broken internal omport- [patch]146ca7139a:
Bump package to enable branch deploys- Updated dependencies d2b8166208:
Updated dependencies 1d72045e6b: