Table of Contents

Utilities

Utility functions enable advanced theme usage. They let you customize components in a granular way.

Table of Contents

How to use them
- Menu and arrow styles
Configuration
API

How to use them

Use menu and arrow styling utilities to build Garden-styled menu components.

Configuration

Name8.76.4•View source•View on npm
Installnpm install @zendeskgarden/react-theming
Depsnpm install react react-dom styled-components
Importimport { arrowStyles, focusStyles, getColor, getFocusBoxShadow, getLineHeight, mediaQuery, menuStyles, retrieveComponentStyles, useText, withTheme } from '@zendeskgarden/react-theming'

API

arrowStyles

CSS for an arrow at the given position and with the given size. The arrow inherits the base element’s border, background, and box-shadow. For proper border and box-shadow styling, the element to which arrow styles are applied must be wrapped in a positioned box (relative, absolute, or fixed) that has a z-index greater than or equal to zero.

Parameter	Type	Default	Description
position	'top' \| 'top-left' \| 'top-right' \| 'right' \| 'right-top' \| 'right-bottom' \| 'bottom' \| 'bottom-left' \| 'bottom-right' \| 'left' \| 'left-top' \| 'left-bottom'	Required	Positions the arrow against the base element
[options.size]	string	'6px'	Expresses a CSS dimension as a distance from the base (hypotenuse) to point (right angle) of the arrow
[options.inset]	string	'0'	Tweaks arrow positioning by adjusting with a positive (in) or negative (out) CSS dimension
[options.animationModifier]	string	–	Indicates a CSS class or attribute selector which, when applied to the base element, animates the arrow's appearance

focusStyles

CSS for Garden standard box-shadow focus styling. The hue and shade are used to determine the color of the focus ring.

Parameter	Type	Default	Description
[options.theme]	DefaultTheme	DEFAULT_THEME	Provides values used to resolve the desired color
[options.hue]	Object \| string	'primaryHue'	Provides a theme object palette hue or color key, or any valid CSS color notation
[options.shade]	number	600	Selects a shade for the given `hue`
[options.shadowWidth]	string	'md'	Provides a theme object shadowWidth key for the cumulative width of the `box-shadow`
[options.spacerHue]	Object \| string	'background'	Provides a theme object palette hue or color key, or any valid CSS color notation
[options.spacerShade]	number	600	Selects a shade for the given `spacerHue`
[options.spacerWidth]	string	'sm'	Provides a theme object shadowWidth for the white spacer, or `null` to remove
[options.inset]	boolean	–	Determines whether the `box-shadow` is inset
[options.selector]	string	&:focus-visible, &[data-garden-focus-visible="true"]	Provides a subsitute pseudo-class CSS selector
[options.styles]	CSSObject	–	Adds CSS property values to be rendered on focus
[options.condition]	boolean	true	Supplies an optional condition that can be used to prevent the focus `box-shadow`

getColor

Get a color for the given hue, shade, and theme. The algorithm returns a valid color even if the particular shade doesn’t exist in the current theme.

Parameter	Type	Default	Description
hue	Object \| string	Required	Provides a theme object palette hue or color key, or any valid CSS color notation
shade	number	600	Selects a shade for the given hue
theme	DefaultTheme	DEFAULT_THEME	Provides values used to resolve the desired color
transparency	number	–	Sets an alpha channel between 0 and 1

getFocusBoxShadow

Get a CSS box-shadow property value for focus state styling. The hue and shade are used to determine the color of the focus ring. Use this function when focusStyles is not the right fit.

Parameter	Type	Default	Description
[options.theme]	DefaultTheme	DEFAULT_THEME	Provides values used to resolve the desired color
[options.hue]	Object \| string	'primaryHue'	Provides a theme object palette hue or color key, or any valid CSS color notation
[options.shade]	number	600	Selects a shade for the given `hue`
[options.shadowWidth]	string	'md'	Provides a theme object shadowWidth key for the cumulative width of the `box-shadow`
[options.spacerHue]	Object \| string	'background'	Provides a theme object palette hue or color key, or any valid CSS color notation
[options.spacerShade]	number	600	Selects a shade for the given `spacerHue`
[options.spacerWidth]	string	'sm'	Provides a theme object shadowWidth for the white spacer, or `null` to remove
[options.inset]	boolean	–	Determines whether the `box-shadow` is inset
[options.boxShadow]	string	–	Provides an existing `box-shadow` (a drop shadow, for example) to be retained along with the focus ring

getLineHeight

Derive a unitless line height based on the given pixel-valued height and font size.

Parameter	Type	Default	Description
height	string \| number	Required	Specifies the desired line height in pixels
fontSize	string \| number	Required	Specifies the font size (in pixels) of text contained within the line

mediaQuery

Get a CSS media query string for the given query specifier, breakpoint name, and theme. Use this function to build responsive UI that works well with Garden’s themed Grid.

Parameter	Type	Default	Description
query	'up' \| 'down' \| 'only' \| 'between'	Required	Specifies the query, one of: `'up'` match screen widths including the given breakpoint and up `'down'` match screen widths included within the given breakpoint and down `'only'` match screen widths included within the given breakpoint `'between'` match screen widths including the first breakpoint up through screen widths included within the second breakpoint
breakpoint	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| Array	Required	Specifies a theme object breakpoints key, or an array of two keys when`'between'` is the specified query
theme	DefaultTheme	DEFAULT_THEME	Provides values used to resolve the specified breakpoint

menuStyles

CSS for a menu at the given position. Apply these styles to an absolutely positioned wrapper (e.g. via Popper) which contains a child menu component.

Parameter	Type	Default	Description
position	'top' \| 'right' \| 'bottom' \| 'left'	Required	Specifies the menu position relative to the component that triggers menu expansion
[options.theme]	DefaultTheme	DEFAULT_THEME	Provides theming values used to style the menu component
[options.hidden]	boolean	–	Determines whether the menu is hidden
[options.margin]	string	–	Determines the amount of space, as a CSS dimension, between the menu and its trigger
[options.zIndex]	number	–	Specifies the `z-index` for the absolutely positioned menu wrapper
[options.childSelector]	string	'> *'	Indicates a CSS selector which, when applied to the wrapper, identifies the child menu component
[options.animationModifier]	string	–	Indicates a CSS class or attribute selector which, when applied to the wrapper, animates the menu's appearance

retrieveComponentStyles

Retrieve customized CSS for themable component styling overrides. This example demonstrates how to construct a custom styled component that permits customizations via the theme’s components object.

import styled from 'styled-components';import { retrieveComponentStyles } from '@zendeskgarden/react-theming';
const COMPONENT_ID = 'custom.component';
export const StyledCustomComponent = styled.div.attrs({  /* Render component ID attribute for reference */  'data-custom-id': COMPONENT_ID})`  display: flex;  align-items: center;
  /* CSS provided on the theme will be rendered inline */  ${props => retrieveComponentStyles(COMPONENT_ID, props)};`;

Parameter	Type	Default	Description
id	string	Required	Specifies the unique ID used to retrieve CSS styles from the theme's components object
props	Partial<ThemeProps<Partial<DefaultTheme>>>	Required	Provides component props which contain the context `theme` object

useText

A custom React hook that provides default text for aria-label or other critical attribute strings. If necessary, a development mode console warning prompts the consumer to provide customized, translated text.

Parameter	Type	Default	Description
component	string	Required	Specifies the React component to which the `props` belong
props	Record<string, any>	Required	Provides component props to check for `name`
name	string	Required	Determines the name of the component prop to set default text on
text	string	Required	Specifies default text to apply if the value of `props[name]` is `undefined`
condition	boolean		Supplies an optional condition that can be used to prevent evaluation

withTheme

Use this component factory to pass the context theme object to any React component. The React useContext hook may be used as a favorable alternative.

Parameter	Type	Default	Description
Component	Object	Required	Gets wrapped by a higher-order component with an added `theme` prop