Layout
Layer
Layers allow for the stacking of components and other elements, giving control over how they interact together and appear to users.
Overview
Control over how different layers appear and interact together is important when building reusable components, as most modern user interfaces use layers to manage how components and other elements appear to users.
Previously, the NewsKit design system utilised z-index to order component and element depth. However, we discovered that this approach did not work effectively when building and working with components due to the lack of control it afforded.
Our solution allows for greater user control via the LayerOrganizer and Layer components which rely on the stacking context and stacking order to achieve the same functionality, rather than the traditional z-index.
Layer organizer
The layer organizer is a provider-type component that needs to be added at the root level of your application. It creates a new stacking context and adds an extra div element to your application which will be used to host rendered layers. For example, the NewsKit Modal , Drawer , or Select components will render inside that div element.
You can nest multiple Layer organizers to create a new stacking context. Be aware that the Layer component will always render in the parent one.
If you use NewsKitProvider you do not need to add a LayerOrganizer since it is already part of the NewsKitProvider.
Layer
The layer component renders its children inside a host using createPortal. The host is the parent LayerOrganizer.
With layers, there is no need for the z-index CSS property as layers completely rely on the stacking order within a LayerOrganizer.
Usage
The following guidance describes how and when to use layers.
In general, try to avoid using
z-indexin your component-based application. If you need to have az-indexadded to an element, make sure it is within an ordered stacking context. Refer to MDN for more information on how to create a stacking context.In order to support applications that have stacking contexts with
z-indexset to a value other than auto,LayerOrganizerandNewsKitProvideraccept az-indexnumber. When az-indexvalue is passed, it will set it as az-indexvalue for all the layers within its context.When using
LayerOrganizeryou do not need to set a default value. However, in some cases, you might have third-party libraries or components that usez-indexwhere you may need to change the defaultz-indexvalue equal to or greater than the highestz-indexvalue of all top-level stacking contexts in your application (note this may be not the highestz-indexvalue across your application).
z-indexes within separate stacking contexts are not compared, and children within a stacking context that goes last will overlay those with a higher z-index, but within a separate stacking context that goes earlier in the stacking order.
API
The layer organizer has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
The layer has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|