How to Make a Website Work in Safari

To make a website work in Safari, build on standard HTML, CSS, and JavaScript, avoid plug-in dependencies, detect browser capabilities instead of guessing from the user-agent string, and test the exact layout and interaction that fails in Safari. Use Safari Web Inspector to find errors, check responsive layouts at multiple sizes, and confirm device-specific behavior on a real iPhone, iPad, or Mac when it matters.

A Safari-only issue is a symptom, not a diagnosis. The cause may be an unsupported or incorrectly used API, a CSS assumption, a JavaScript error, a failed resource, media encoding, or a difference in the actual device environment. Follow the steps below to identify the cause before adding a browser-specific workaround.

1. Reproduce and describe the failure

Start with the context in which the bug appears. Record the page URL, device and operating system, Safari version if available, viewport size, and the steps that trigger the issue. Classify what you see:

Visual: a layout overflows, overlaps, or appears in the wrong position.
Interactive: a button, menu, form, or other control does not respond as expected.
Media: audio or video does not load or play.
Loading: the page or a particular resource fails to finish loading.

Try to reproduce the same failure more than once. If it occurs only on a particular device, orientation, or interaction path, preserve that detail; it can point to the difference that matters.

2. Inspect the page in Safari Web Inspector

Safari Web Inspector helps you examine the DOM, CSS, JavaScript execution, errors, and page behavior. Open the inspector for the affected page and look for evidence tied to the failure:

Check the JavaScript console for errors, rejected promises, and warnings near the time of failure.
Inspect the affected element in the DOM and review the styles that apply to it. Look for unexpected dimensions, positioning, overflow, or inherited styles.
Review loaded resources for failed requests, incorrect paths, and unexpected responses.
Check whether the relevant script runs and whether its event handlers are attached.
If you suspect stale content, use the Develop menu’s cache-clearing options and reproduce the issue again.

Apple describes Web Inspector as a tool for inspecting and debugging HTML, CSS, and JavaScript. Its Develop menu also provides the JavaScript Console and cache controls. See Apple’s Web Inspector documentation and Develop menu documentation.

3. Fix compatibility at the feature level

Prefer standards-based markup and behavior. When a feature may not be available, detect that capability and provide a usable fallback. Apple’s current guidance says, “Use feature detection to make your website browser independent.” See Apple’s Safari optimization guidance.

For example, test for a specific API before using it:

if ('someFeature' in window) {
  // Use the feature when the browser provides it.
} else {
  // Provide a fallback or omit the optional enhancement.
}

Replace someFeature with the actual capability you need. For APIs exposed on other objects, test the relevant method or property on that object. A fallback should preserve the page’s essential function even if an enhancement is unavailable.

Avoid making a browser-name or version check your default fix. User-agent strings are not a reliable substitute for checking the feature your code depends on. Apple’s Develop menu documentation advises against relying on the browser name or version in the user-agent string.

4. Check HTML, CSS, and responsive behavior

Use well-formed semantic HTML and standards-based CSS.
Check the computed styles of the element that fails instead of changing unrelated global rules.
Test at multiple viewport widths and heights, in portrait and landscape where relevant, and at different pixel ratios.
Make touch controls easy to activate and leave enough space between nearby controls.
Use accessible labels and appropriate ARIA where needed; test keyboard and assistive-technology paths relevant to the page.
Use HTTPS and applicable security practices, including subresource integrity where appropriate.

Safari’s Responsive Design Mode is useful for quickly checking viewport and pixel-ratio layouts. Its device presets are approximations. Browser controls, the on-screen keyboard, and form-field behavior can change what a user sees, so confirm affected flows on the actual device. Apple explains these limits in its Responsive Design Mode documentation.

5. Check media and remove plug-in dependencies

Use HTML <audio> and <video> elements with media formats supported by the Safari platforms you target. If playback fails, inspect the media request and verify the source file’s encoding and response. Offer a suitable alternative when a format or feature is unavailable.

Avoid requiring a third-party browser plug-in for core site functionality. Apple’s archived Developing Web Content for Safari guide, updated December 12, 2016, identifies unsupported media compression and plug-in reliance among causes of Safari problems. Its specific format examples are historical and should not be treated as a current compatibility matrix. Apple’s archived guide says that sites following web standards and avoiding plug-ins generally do not need Safari-specific tweaks; that is a baseline, not a guarantee that every feature or implementation will work without debugging. See the 2016 archived guide.

6. Test important flows and devices

After the implementation change, repeat the original failure steps in the same Safari and device context. Then check the important paths that use the same component or API.

Use Responsive Design Mode for quick viewport checks.
Use manual testing on a real iPhone, iPad, or Mac for behavior affected by device controls, keyboards, or a specific operating system.
Use Safari WebDriver to automate repeatable critical interactions and regression checks. Apple documents that WebDriver support must be enabled for development use; consult its WebDriver documentation.

Simulation, automation, and device testing answer different questions: simulation helps with layout dimensions, automation repeats a flow, and a real device confirms behavior in the actual browser and operating-system environment.

7. Troubleshooting common Safari problems

Symptom	Likely cause	What to check or change
A script stops before the affected control works	A JavaScript error or unavailable API	Read the console, identify the first relevant error, check for the required capability, and add a fallback.
An element is misplaced or clipped	A layout assumption, sizing rule, or overflow behavior	Inspect the element’s computed styles and its parent layout; check the same component at multiple viewport sizes.
A page looks fixed in simulation but breaks on an iPhone or iPad	Real browser chrome, keyboard, form-field, or device behavior differs from the preset	Reproduce on the affected device and orientation, then adjust the responsive layout or interaction based on that observation.
Audio or video does not play	Unsupported encoding, incorrect source, failed request, or plug-in dependency	Inspect the resource response and encoding; use an HTML media element and provide an alternative suitable for the target platform.
A change seems to have no effect	Cached content or a different resource is being loaded	Inspect the loaded resource and clear the cache from Safari’s Develop menu before reproducing.
A fix based on browser detection works inconsistently	User-agent detection is being used as a proxy for actual feature support	Check the specific API or capability and branch on its availability instead.
The problem occurs only in one test run	The steps or environment may not be repeatable, or a resource may be intermittently failing	Record device, OS, viewport, URL, and steps; repeat the flow and inspect resource failures before changing code.

8. Keep the fix reliable and efficient

Fix the smallest confirmed cause and retest the original scenario. Feature detection and fallbacks help avoid tying the whole site to one browser assumption. Automated WebDriver checks can make critical flows repeatable; manual device checks remain useful when real device behavior is part of the bug.

For performance, inspect whether the failure involves a resource that is slow or never completes, and avoid adding heavyweight browser-specific code until the underlying need is clear. For reliability, keep a record of the failing environment and repeat the same steps after the change. There is no single Safari compatibility test that replaces checking the browsers, devices, and flows your site actually supports.

9. Capture a Safari page for review

A screenshot can make a visual regression easier to share or compare. Use the browser tools above to diagnose the live behavior first; a screenshot records the rendered result but does not explain why it happened.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. A single request can capture a page as PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for 1,000 screenshots a month, no card required.

FAQ

Should I add Safari-specific CSS?

Only when you have identified a concrete behavior that needs a targeted adjustment. First inspect the cause and check whether a standards-based rule or feature fallback fixes it.

Is Responsive Design Mode enough to test an iPhone?

It is useful for quick viewport checks, but Apple describes its presets as approximations. Confirm device-specific behavior on the actual device when it affects the issue.

Should I use the user-agent string to detect Safari?

Prefer detecting the capability your code needs. Browser identification can misstate what a particular environment supports.

Can a screenshot prove the site works in Safari?

No. It captures a visual result at a point in time; it does not verify interactions, media playback, or behavior across devices.