SideNav is deprecated, use NavList instead
The SideNav component is deprecated. Use NavList instead for vertical lists of navigational links.
deprecated
27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
SideNav migration from selected prop to aria-current
When migrating from SideNav to NavList, replace the `selected` prop on SideNav.Link with `aria-current="page"` on NavList.Item.
SideNav props table
SideNav component props: as (String, default 'nav') sets the HTML tag; bordered (Boolean, default false) renders with a border; variant (String, default 'normal') set to 'lightweight' for lightweight style; sx (SystemStyleObject, default {}) applies styles to the component.
SideNav.Link props table
SideNav.Link component props: as (String, default 'a') sets the HTML tag; href (String, no default) URL for the link; muted (Boolean, default false) uses less prominent color and default link shade on hover; selected (Boolean, default false) marks link as selected and sets aria-current attribute; underline (Boolean, default false) adds underline to link; variant (String, default 'normal') set to 'full' to spread child elements across the link for icons and labels; sx (SystemStyleObject, default {}) applies styles to the component.
SideNav full variant spreads child elements
The `variant='full'` prop on SideNav.Link spreads child elements across the full width of the link, useful for layouts with status icons, labels, avatars, or counters positioned on the right side.
SideNav lightweight variant
The `variant='lightweight'` prop renders SideNav with a more compact style where items have no borders and reduced spacing. It is suitable for nested or sub-navigation use cases.
SideNav with React Router NavLink
SideNav.Link can use the `as` prop with React Router's NavLink component (e.g., `as={NavLink} to="..."`). React Router automatically handles setting `aria-current="page"` for the active route.
Deprecated container width and grid gutter
Legacy SCSS variables are deprecated: $container-width to 980px (deprecated), $grid-gutter to 10px (deprecated), $width-xs to 0 (deprecated), $size-0 to 0 (deprecated).
details-dialog deprecation and migration to Primer::Alpha::Dialog
The <details-dialog> element is deprecated and should be replaced with the Primer::Alpha::Dialog component. The details-dialog uses the HTML details and summary elements to render a dialog, while Primer::Alpha::Dialog uses a container with role="dialog" attached.
details-dialog structure versus Primer::Alpha::Dialog structure
The <details-dialog> differs from Primer::Alpha::Dialog in three ways: (1) the trigger uses the summary element instead of a show_button slot; (2) the dialog body lives within the details-dialog element instead of a with_body slot; (3) the details wrapper contains both the trigger button (summary) and the dialog itself (details-dialog), whereas Primer::Alpha::Dialog separates these concerns.
Primer::Alpha::Dialog basic syntax
Primer::Alpha::Dialog is rendered using Ruby component syntax: render(Primer::Alpha::Dialog.new(title: 'Dialog Title', subtitle: 'Optional subtitle', size: :large)) do |d| d.with_show_button { "Open dialog" } d.with_body { "Modal content" } end
Primer::Alpha::Dialog requires accessible name via title argument
Primer::Alpha::Dialog requires an accessible name to be added via the title argument, which is referenced as the accessible name of the dialog. The details-dialog did not require an accessible name to be added.
Primer::Alpha::Dialog provides close button by default
Primer::Alpha::Dialog provides a close button by default, unlike details-dialog where the developer must add one themselves.
Styling differences between details-dialog and Primer::Alpha::Dialog
The details-dialog and Primer::Alpha::Dialog have minor style differences such as with padding and margins applied by default. The updated styles should be utilized and styles should not be overridden to make Primer::Alpha::Dialog appear like the previous design. Custom classes can be applied to Primer::Alpha::Dialog through available slots, but system_arguments should be preferred when applicable.
Primer::Alpha::Dialog show_button slot usage
The show_button slot can be used on Primer::Alpha::Dialog and supplied with text to render the trigger button. The slot accepts system_arguments for customization, such as color: :danger to set button scheme.
Primer::Alpha::Dialog with_body slot usage
The with_body slot is used to render content inside Primer::Alpha::Dialog. It accepts system_arguments such as p: 0 to control padding. The title and close button are rendered automatically by the component.
Using include-fragment in Primer::Alpha::Dialog
The <include-fragment> element can be added inside the dialog body of Primer::Alpha::Dialog. When migrating from details-dialog where src was applied on the details-dialog element itself, the src should be moved to the include-fragment element. Example: <% d.with_body do %> <include-fragment src="/robots"> Loading… </include-fragment> <% end %>
Primer::Alpha::Dialog visually_hide_title argument
The visually_hide_title argument can be used on Primer::Alpha::Dialog to hide the title visually while still providing an accessible name. This is useful when the dialog trigger button serves as the title.
Truncate migration: deprecated to Beta version
The deprecated Primer::Truncate component has been replaced by Primer::Beta::Truncate. To migrate, change the component name from Primer::Truncate to Primer::Beta::Truncate in ERB templates.
Truncate tag argument default changed from div to span
In Primer::Truncate, the tag argument defaulted to :div. In Primer::Beta::Truncate, the tag argument now defaults to :span. To maintain previous behavior, explicitly set tag: :div when migrating.
Truncate inline argument removed
The inline argument that existed in Primer::Truncate has been removed in Primer::Beta::Truncate.
Truncate priority argument added
Primer::Beta::Truncate introduces a new priority argument. When set to true, the text will be given priority by increasing flex-basis.
Truncate text slot added
The new Primer::Beta::Truncate component includes a text slot used for the truncated text.
Primer::LocalTime is deprecated
The Primer::LocalTime component is now deprecated and should be migrated to Primer::Beta::RelativeTime.
LocalTime to RelativeTime migration basic example
To migrate from Primer::LocalTime to Primer::Beta::RelativeTime, change <%= Primer::LocalTime(datetime: Time.now, initial_text: Time.now.iso8601) %> to <%= Primer::Beta::RelativeTime(datetime: Time.now, prefix: "", threshold: "PT0S") %>. Remove the initial_text parameter, set prefix to an empty string, and add threshold: "PT0S".
RelativeTime threshold parameter replaces LocalTime behavior
The RelativeTime component uses a threshold parameter (ISO-8601 duration format) to determine when to display absolute date/time instead of relative time. The value PT0S means switch to absolute time starting zero seconds ago, effectively always displaying absolute time. LocalTime used PT0S as the default threshold, but RelativeTime defaults to P30D and requires threshold: "PT0S" to always display absolute datetime.
RelativeTime parameters reference
Primer::Beta::RelativeTime accepts the following parameters: tense (one of :auto, :future, or :past; which tense to use), prefix (what to prefix the relative time display with), threshold (ISO-8601 duration format at which relative time displays become absolute), precision (elapsed time display precision: nil, :day, :hour, :minute, :month, :second, or :year), format (display format: one of :auto, :elapsed, or :micro), lang (the language to use), and title (custom title for the element). The initial_text parameter from LocalTime is no longer used. All other arguments remain the same between components.