MenuItem

Menu item component A brief, introductory couple of sentences about the component. This is a second sentence just so that there’s a second line in this document. Think of this a teaser for the When/How to Use section.

Examples #

Basic Menu Item #

MenuItems can be used to trigger an action or navigate to a new location.

Note: MenuItems normally occupy the full available width of their container. The MenuItems here are width-constrained for illustration purposes. Slightly longer text to explain what’s so special about this particular example.

Light years

Star stuff

Encyclopaedia galactica

<DemoLayout>
	<Menu>
		<MenuItem>
			Light years
		</MenuItem>
		<MenuItem>
			Star stuff
		</MenuItem>
		<MenuItem>
			Encyclopaedia galactica
		</MenuItem>
	</Menu>
</DemoLayout>

Secondary Text #

A MenuItem can render secondary text, which will wrap when necessary. Text to explain what’s special about this example. Text to explain what’s special about this example. Text to explain what’s special about this example.

Light yearsStar stuff

Harvesting onlyDistant epochs

Encyclopaedia galacticaCosmic ocean

<DemoLayout>
	<Menu>
		<MenuItem secondaryText="Star stuff">
			Light years
		</MenuItem>
		<MenuItem secondaryText="Distant epochs">
			Harvesting only
		</MenuItem>
		<MenuItem secondaryText="Cosmic ocean">
			Encyclopaedia galactica
		</MenuItem>
	</Menu>
</DemoLayout>

Variants #

Available variants to help communicate purpose, which automatically insert a startIcon. Text to explain what’s special about this example.

Danger

Success

Warning

<DemoLayout>
	<Menu>
		<MenuItem variant="danger">
			Danger
		</MenuItem>
		<MenuItem variant="success">
			Success
		</MenuItem>
		<MenuItem variant="warning">
			Warning
		</MenuItem>
	</Menu>
</DemoLayout>

Menu Items with Icons #

MenuItems can contain Icons at their start, end, or both. If both startIcon and variant props are provided, startIcon will be used. Text to explain what’s special about this example.

Start icon

End icon

Both icons

Danger

Success

Warning

Disabled

() => {
	const icon = <IconCloud />;

	return (
		<DemoLayout>
			<Menu>
				<MenuItem iconStart={icon}>Start icon</MenuItem>
				<MenuItem iconEnd={icon}>End icon</MenuItem>
				<MenuItem iconStart={icon} iconEnd={icon}>Both icons</MenuItem>
			</Menu>
			<Menu>
				<MenuItem iconStart={icon} variant="danger">Danger</MenuItem>
				<MenuItem iconStart={icon} variant="success">Success</MenuItem>
				<MenuItem iconStart={icon} variant="warning">Warning</MenuItem>
				<MenuItem iconStart={icon} disabled>Disabled</MenuItem>
			</Menu>
		</DemoLayout>
	);
}

Disabled #

MenuItems can be disabled. Slightly longer text to explain what’s so special about this particular example.

Light years

Star stuff

Encyclopaedia galactica

<DemoLayout>
	<Menu>
		<MenuItem disabled onClick={event => { console.log(event) }}>
			Light years
		</MenuItem>
		<MenuItem disabled onClick={event => { console.log(event) }}>
			Star stuff
		</MenuItem>
		<MenuItem disabled onClick={event => { console.log(event) }}>
			Encyclopaedia galactica
		</MenuItem>
	</Menu>
</DemoLayout>

Custom Rendering #

MenuItem can use a custom function for its rendering. This allows you to render any item data you might need (like an avatar, below). To help match the other MenuItems, you have access to its theme variables. The CustomRender component source below might be a helpful template. Some things to keep in mind:

Remember to include :focus, :hover, and :active styles.
1. If this is to be used for a Dropdown, also apply your focus/hover styles when props.isHighlighted === true.
Remember to accommodate the disabled state (props.disabled === true).
If your app supports RTL languages, you can use theme.direction to conditionally apply the necessary styles. Text to explain what’s special about this example. Text to explain what’s special about this example. Text to explain what’s special about this example.

Captain Steve ZissouBill Murray

Dr. Peter VenkmanBill Murray

Bob HarrisBill Murray

() => {
	function CustomRender(item, props, theme) {
		const { isHighlighted, disabled } = props;

		const Root = createStyledComponent(
			'div',
			{
				backgroundColor: isHighlighted && theme.color_theme_20,
				display: 'flex',
				padding: theme.MenuItem_padding,
				textDecoration: 'none',

				'&:focus': {
					backgroundColor: !disabled && theme.color_theme_20,
					outline: 0
				},

				'&:hover': {
					backgroundColor: !disabled && theme.color_theme_20
				},

				'&:active': {
					backgroundColor: !disabled && theme.color_theme_40
				}
			},
			{
				includeStyleReset: true
			}
		);
		const Actor = createStyledComponent('span', {
			color: theme.color_text_caption,
			display: 'block',
			fontSize: theme.fontSize_mouse,
			marginTop: theme.spacing_half
		});
		const Avatar = createStyledComponent('img', {
			borderRadius: pxToEm(18),
			display: 'block',
			flex: '0 0 auto',
			height: pxToEm(36),
			marginLeft: theme.direction === 'rtl' && theme.spacing_single,
			marginRight: theme.direction === 'ltr' && theme.spacing_single,
			padding: theme.MenuItemIcon_padding,
			width: pxToEm(36)
		});
		const Content = createStyledComponent('span', function() {
			const fontSize = theme.MenuItemContent_fontSize;
			const paddingHorizontal = getNormalizedValue(
				theme.MenuItemContent_padding,
				fontSize
			);

			return {
				flex: '1 1 auto',
				fontSize,
				padding: '0 ' + paddingHorizontal,
				whiteSpace: 'normal',
				wordBreak: 'break-all'
			};
		});

		const rootProps = {
			disabled,
			...props
		};

		return (
			<Root {...rootProps}>
				{item.avatar && <Avatar alt={'Photo of ' + item.character} src={item.avatar} />}
				<Content>
					{item.character}
					{item.actor && <Actor>{item.actor}</Actor>}
				</Content>
			</Root>
		);
	}

	const data = [
		{
			items: [
				{
					actor: 'Bill Murray',
					avatar: 'http://www.fillmurray.com/102/100',
					character: 'Captain Steve Zissou',
					render: CustomRender
				},
				{
					actor: 'Bill Murray',
					avatar: 'http://www.fillmurray.com/101/100',
					character: 'Dr. Peter Venkman',
					render: CustomRender
				},
				{
					actor: 'Bill Murray',
					avatar: 'http://www.fillmurray.com/100/100',
					character: 'Bob Harris',
					render: CustomRender
				}
			]
		}
	];

	return (
		<DemoLayout>
			<Menu data={data} />
		</DemoLayout>
	)
}

RTL Support #

Slightly longer text to explain what’s so special about this particular example.

نص عنصر القائمة

نص عنصر القائمةنص ثانوي

رمز البدء

رمز النهاية

<DemoLayout dir="rtl">
	<ThemeProvider theme={{ direction: 'rtl' }}>
		<Menu>
			<MenuItem>نص عنصر القائمة</MenuItem>
			<MenuItem secondaryText="نص ثانوي">نص عنصر القائمة</MenuItem>
			<MenuItem iconStart={<IconCloud />}>رمز البدء</MenuItem>
			<MenuItem iconEnd={<IconCloud />}>رمز النهاية</MenuItem>
		</Menu>
	</ThemeProvider>
</DemoLayout>

MenuItem Props #

Name	Type	Default	Description
children	MnrlReactNode		Rendered content of the component
disabled	boolean		Disable the menu item
iconEnd	React$Element		Icon that goes after the children
iconStart	React$Element		Icon that goes before the children
isHighlighted	boolean		Display the item in an active style
item	{ iconEnd?: React$Element<>, iconStart?: React$Element<>, disabled?: boolean, divider?: boolean, onClick?: (event: Object) => void, render?: (item: Object, props: Object, theme: Object) => React$Element<*>, secondaryText?: MnrlReactNode, text?: MnrlReactNode, variant?: 'regular' \| 'danger' \| 'success' \| 'warning' }		Item data (see example below)
onClick	(event: Object) => void		Called with the click event
render	(item: Item, props: Object, theme: Object) => React$Element<*>		Custom render function
secondaryText	MnrlReactNode		Secondary text
tabIndex	number	0	Determines if the item can be focused
variant	'regular', 'danger', 'success', 'warning'	'regular'	Available variants

Undocumented properties will be applied to the root element.

MenuItem Theme Variables #

These variables can be used as hooks to override this component’s style at either a global or local level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
MenuItem_backgroundColor_active	theme.color_gray_40
MenuItem_backgroundColor_focus	theme.color_gray_20
MenuItem_backgroundColor_hover	theme.color_gray_20
MenuItem_color_text	theme.color_text
MenuItem_fontWeight	theme.fontWeight_regular
MenuItem_padding	0.5em
MenuItemContent_fontSize	theme.fontSize_ui
MenuItemContent_padding	0.375em
MenuItemIcon_padding	0.25em
MenuItemSecondaryText_color_text	theme.color_caption
MenuItemSecondaryText_fontSize	0.75em

When/How to Use #

An explanation of when to use this component and basics about how to use it. Could also include when not to use this component, and which component should be used instead. More detailed how-to-use info is under Best Practices, below. It might be a couple of short sentences, or it could be a full paragraph or two.

Best Practices #

DO this practice

Example Link Component

Some text to explain why you should do this and when.

DON’T do this other practice

Example Link Component

Some text to explain why you should not do this.

DO this other practice

Some text to explain why you should do this and when.

DO this third practice

Example Link Component

Some text to explain why you should do this and when.

We welcome feedback and contributions on GitHub