Types and constants
Type definitions
Since Codex is written in TypeScript, we often make use of special types for things like complex props. Below is documentation of all public types.
ButtonAction
See ButtonActions.
// Allowed values: 'default', 'progressive', 'destructive'
type ButtonAction = typeof ButtonActions[ number ];
ButtonGroupItem
interface ButtonGroupItem {
/** Button value or unique identifier */
value: string | number,
/**
* Display label for the button, or null to show no label (for icon-only buttons).
* If the label property is missing, the value property is used as the label.
*/
label?: string|null,
/** Icon to display before the label */
icon?: Icon,
/** ARIA label for the button. Used for accessibility for icon-only buttons. */
ariaLabel?: string,
/** Whether the button is disabled */
disabled?: boolean
}
ButtonSize
See ButtonSizes.
// Allowed values: 'medium', 'large'
type ButtonSize = typeof ButtonSizes[ number ];
ButtonType
See ButtonTypes.
// Allowed values: 'button', 'submit', 'reset'
type ButtonType = typeof ButtonTypes[ number ];
ButtonWeight
See ButtonWeights.
// Allowed values: 'normal', 'primary', 'quiet'
type ButtonWeight = typeof ButtonWeights[ number ];
ChipInputItem
interface ChipInputItem {
value: string,
icon?: Icon
}
DialogAction
interface DialogAction {
label: string,
disabled?: boolean
}
HTMLDirection
type HTMLDirection = 'ltr' | 'rtl';
Icon
Icons are a special type defined in the @wikimedia/codex-icons
package. The Icon
type is a union of several different other types.
type Icon = SimpleIcon | IconFlipForRtl | IconVariedByDir | IconVariedByLang;
SimpleIcon
Either an object with a path
property or a string.
interface PathIcon {
/**
* An SVG path string, e.g. 'M3 3H1v16h18v-2H3z'
*/
path: string
}
/**
* An SVG string, e.g. '<path d="M3 3H1v16h18v-2H3z"/>'. An SVG string may contain multiple tags,
* e.g. '<circle x="..." y="..." r="..."/><path d="..."/>'. SVG strings should not contain an
* <?xml ...?> tag or a wrapping <svg> tag.
*/
type SvgIcon = string;
type SimpleIcon = PathIcon | SvgIcon;
IconSize
See IconSizes.
// Allowed values: 'medium', 'small', 'x-small'
type IconSize = typeof IconSizes[ number ];
IconFlipForRtl
An icon with a single SVG that should flip horizontally in RTL mode.
export interface IconFlipForRtl {
/** LTR version of the icon. */
ltr: SimpleIcon,
/** Indicates that the icon should be flipped via CSS in RTL mode. */
shouldFlip: true,
/**
* Language codes that are exceptions to the above property (e.g. the help
* icon should flip in RTL mode, but not for Hebrew or Yiddish).
*/
shouldFlipExceptions?: string[]
}
IconVariedByDir
An icon that varies per text direction (but can't just be flipped).
interface IconVariedByDir {
/** Icon for RTL */
rtl: SimpleIcon,
/** Icon for LTR */
ltr: SimpleIcon
}
IconVariedByLang
An icon that varies per language.
interface IconVariedByLang {
/** HTMLElement.lang code with corresponding icon. */
langCodeMap: Record<string, SimpleIcon | IconFlipForRtl>,
/** The default icon. */
default: SimpleIcon | IconFlipForRtl
}
MenuConfig
interface MenuConfig {
/** The maximum number of items visible in an expanded menu. */
visibleItemLimit?: number | null
/** Whether to show thumbnails (or placeholder). */
showThumbnail?: boolean,
/** Whether to bold menu item labels. */
boldLabel?: boolean,
/** Whether to hide description text overflow via an ellipsis. */
hideDescriptionOverflow?: boolean
}
MenuItemData
interface MenuItemData {
/** Item value or unique identifier. */
value: string | number,
/** Display label for the menu item. */
label?: string,
/** Text to be appended to the result's label, e.g. text matching a search query. */
match?: string,
description?: string | null,
/** Lang attributes of text properties. */
language?: MenuItemLanguageData,
icon?: Icon,
thumbnail?: Thumbnail | null,
/** If URL is included, menu item will be wrapped in an anchor element. */
url?: string,
disabled?: boolean
}
MenuItemDataWithId
interface MenuItemDataWithId extends MenuItemData {
id: string
}
MenuItemLanguageData
interface MenuItemLanguageData {
/** lang attribute of the label. */
label?: string,
/** lang attribute of the match. */
match?: string,
/** lang attribute of the description. */
description?: string
}
MenuState
See MenuStates.
// Allowed values: 'selected', 'highlighted', 'active'
type MenuState = typeof MenuStates[ number ];
PrimaryDialogAction
See DialogAction.
interface PrimaryDialogAction extends DialogAction {
actionType: 'progressive' | 'destructive'
}
SearchResult
interface SearchResult extends MenuItemData {
/** Result link. */
url: string
}
SearchResultClickEvent
interface SearchResultClickEvent {
/** Search result that was clicked. */
searchResult: SearchResult|null,
/** Index of the search result within the array of results. */
index: number,
/** Number of search results. */
numberOfResults: number
}
StatusType
See StatusTypes.
// Allowed values: 'notice', 'warning', 'error', 'success'
type StatusType = typeof StatusTypes[ number ];
TextInputType
See TextInputTypes.
// Allowed values: 'text', 'search', 'number', 'email', 'password', 'tel', 'url', 'week', 'month', 'date', 'datetime-local', 'time'
type TextInputType = typeof TextInputTypes[ number ];
ValidationMessages
interface ValidationMessages {
error?: string
}
ValidationStatusType
// Allowed values: 'default', 'error'
type ValidationStatusType = typeof ValidationStatusTypes[ number ];
Thumbnail
interface Thumbnail {
url: string;
/** Image width in pixels. */
width?: number | null;
/** Image height in pixels. */
height?: number | null;
}
Constants
ButtonActions
const ButtonActions = [
'default',
'progressive',
'destructive'
];
ButtonSizes
const ButtonSizes = [
'medium',
'large'
];
ButtonTypes
const ButtonTypes = [
'button',
'submit',
'reset'
];
ButtonWeights
const ButtonWeights = [
'normal',
'primary',
'quiet'
];
IconSizes
const IconSizes = [
'x-small',
'small',
'medium'
];
MenuStates
const MenuStates = [
'selected',
'highlighted',
'active'
];
StatusTypes
const StatusTypes = [
'notice',
'warning',
'error',
'success'
];
TextInputTypes
const TextInputTypes = [
'text',
'search',
'number',
'email',
'password',
'tel',
'url',
'week',
'month',
'date',
'datetime-local',
'time'
];
ValidationStatusTypes
const ValidationStatusTypes = [
'default',
'error'
];
DebounceInterval
Default length of delay for debouncing, in milliseconds.
const DebounceInterval = 120;
PendingDelay
Default length of delay for displaying pending state, in milliseconds.
const PendingDelay = 500;
NoInvertClass
A utility class to indicate that certain elements (like thumbnail images) should be excluded from any invert-based "dark mode" theming applied downstream (by the DarkMode extension, for example). No styles are applied to this class within Codex.
const NoInvertClass = 'cdx-no-invert';
Any user of Codex applying an invert-based color theme can use this class to exclude certain elements from color inversion so that they appear in their natural colors.